The Socket class allows Qore programs safe access to network sockets. More...

Public Member Functions
Socket	accept ()
	Accepts connections on a listening socket.
*Socket	accept (timeout timeout_ms)
	Accepts connections on a listening socket (see Socket::listen()) accepting a timeout value with a millisecond resolution.
Socket	acceptSSL ()
	Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection.
*Socket	acceptSSL (timeout timeout_ms)
	Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection accepting a timeout value with a millisecond resolution.
int	bind (string str, softbool reuseaddr=False)
	Opens and binds the socket to a port, interface and port (if the $bind_to string has a format "host:port"), or UNIX domain socket file.
int	bind (int port, softbool reuseaddr=False)
	Opens and binds the socket to an INET port on all interfaces.
nothing	bindINET (string iface, softstring service, softbool reuseaddr=False, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
	Opens and binds the socket to the given IPv4 or IPv6 interface (or if no interface is given, then to all interfaces on the local system) and port (the port number will be derived from the service name if a numeric port number is not given)
nothing	bindUNIX (string path, softint socktype=SOCK_STREAM, softint protocol=0)
	Opens and binds the socket to the given UNIX domain socket file as given by the filename argument. If any errors occur, an exception is thrown.
int	close ()
	Closes an open socket.
nothing	connect (string target, timeout timeout_ms=-1)
	Connects to a remote port (if the string has a format "host:port") or UNIX domain socket file with an optional timeout value with a millisecond resolution.
nothing	connectINET (string host, softstring service, timeout timeout_ms=-1, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
	Connects to the given host and port with an optional timeout value with a millisecond resolution.
nothing	connectINETSSL (string host, softstring service, timeout timeout_ms=-1, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
	Connects to the given host and port and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution.
nothing	connectSSL (string target, timeout timeout_ms=-1)
	Connects to a remote socket and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution.
nothing	connectUNIX (string path, softint socktype=SOCK_STREAM, softint protocol=0)
	Connects to a UNIX domain socket file.
nothing	connectUNIXSSL (string path, softint socktype=SOCK_STREAM, softint protocol=0)
	Connects to the given UNIX domain socket file and attempts to establish a TLS/SSL connection.
	constructor ()
	Creates the socket object.
	copy ()
	Creates a new Socket object, not based on the source being copied.
string	getCharset ()
	Returns the character encoding for the socket.
string	getEncoding ()
	Returns the character encoding for the socket.
bool	getNoDelay ()
	Returns the `TCP_NODELAY` setting for the socket.
hash	getPeerInfo ()
	Returns a hash of information about the remote end for connected sockets.
int	getPort ()
	Returns the port number of the socket for INET sockets.
int	getRecvTimeout ()
	Returns the receive timeout socket option value as an integer in milliseconds.
*string	getSSLCipherName ()
	Returns the name of the cipher for an encrypted connection or NOTHING if a secure connection has not been established.
*string	getSSLCipherVersion ()
	Returns the version string of the cipher for an encrypted connection or NOTHING if a secure connection has not been established.
int	getSendTimeout ()
	Returns the send timeout socket option value as an integer in milliseconds.
int	getSocket ()
	Returns the socket file descriptor number.
hash	getSocketInfo ()
	Returns information about the local socket as a hash.
bool	isDataAvailable (timeout timeout_ms=0)
	Returns True or False depending on whether there is data to be read on the socket.
bool	isOpen ()
	Returns True if the socket is open.
bool	isSecure ()
	Returns True if the connection is a secure TLS/SSL connection.
bool	isWriteFinished (timeout timeout_ms=0)
	Returns True or False depending on whether all the data has been written to the socket.
int	listen ()
	Listens for connections on a bound socket; sets the socket in a listening state.
hash	readHTTPChunkedBody (timeout timeout_ms=-1)
	Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a string in the `"body"` key of a hash (including footers received)
hash	readHTTPChunkedBodyBinary (timeout timeout_ms=-1)
	Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a binary object in the `"body"` key of a hash (including footers received)
hash	readHTTPHeader (timeout timeout_ms=-1, *reference info)
	Retuns a hash representing the data in the HTTP header read, or, if the data cannot be parsed as an HTTP header, the data read is returned as a string.
string	recv (softint size=0, timeout timeout_ms=-1)
	Receives data from the socket and returns a string tagged with the Socket's character encoding.
binary	recvBinary (softint size=0, timeout timeout_ms=-1)
	Receives data from the socket and returns a binary object.
int	recvi1 (timeout timeout_ms=-1)
	Receives a 1-byte signed integer from the socket.
int	recvi2 (timeout timeout_ms=-1)
	Receives a 2-byte (16-bit) signed integer in big-endian format (network byte order) from the socket.
int	recvi2LSB (timeout timeout_ms=-1)
	Receives a 2-byte (16-bit) signed integer in little-endian format from the socket.
int	recvi4 (timeout timeout_ms=-1)
	Receives a 4-byte (32-bit) signed integer in big-endian format (network byte order) from the socket.
int	recvi4LSB (timeout timeout_ms=-1)
	Receives a 4-byte (32-bit) signed integer in little-endian format from the socket.
int	recvi8 (timeout timeout_ms=-1)
	Receives an 8-byte (64-bit) signed integer in big-endian format (network byte order) from the socket.
int	recvi8LSB (timeout timeout_ms=-1)
	Receives an 8-byte (64-bit) signed integer in little-endian format from the socket.
int	recvu1 (timeout timeout_ms=-1)
	Receives a 1-byte unsigned integer from the socket.
int	recvu2 (timeout timeout_ms=-1)
	Receives a 2-byte (16-bit) unsigned integer in big-endian format (network byte order) from the socket.
int	recvu2LSB (timeout timeout_ms=-1)
	Receives a 2-byte (16-bit) unsigned integer in little-endian format from the socket.
int	recvu4 (timeout timeout_ms=-1)
	Receives a 4-byte (32-bit) unsigned integer in big-endian format (network byte order) from the socket.
int	recvu4LSB (timeout timeout_ms=-1)
	Receives a 4-byte (32-bit) unsigned integer in little-endian format from the socket.
int	send (binary bin)
	Sends binary data over the socket.
int	send (string str)
	Sends string data over the socket; string data is converted to the socket's encoding if necessary.
nothing	send2 (binary bin)
	Sends binary data over the socket; if any errors occur, an exception is thrown.
nothing	send2 (string str)
	Sends string data over the socket; string data is converted to the socket's encoding if necessary; if any errors occur, an exception is thrown.
int	sendBinary (string str)
	Sends string data over the socket without converting the string to the socket's encoding, but instead is sent exactly as-is.
int	sendBinary (binary bin)
	Sends binary data over the socket.
nothing	sendBinary2 (string str)
	Sends string data over the socket without converting the string to the socket's encoding, but instead is sent exactly as-is; if any errors occur, an exception is thrown.
nothing	sendBinary2 (binary bin)
	Sends binary data over the socket; if any errors occur, an exception is thrown.
nothing	sendHTTPMessage (string method, string path, string http_version, hash headers, string body, reference info)
	Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body.
nothing	sendHTTPMessage (string method, string path, string http_version, hash headers, binary body, *reference info)
	Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body.
nothing	sendHTTPResponse (softint status_code, string status_desc, string http_version, hash headers, *string body)
	Sends an HTTP response with user-defined headers given as a hash and an optional message body.
nothing	sendHTTPResponse (softint status_code, string status_desc, string http_version, hash headers, binary body)
	Sends an HTTP response with user-defined headers given as a hash and a message body as literal binary data.
int	sendi1 (softint i=0)
	Sends a 1-byte integer over the socket.
int	sendi2 (softint i=0)
	Sends a 2-byte (16-bit) integer in big-endian format (network byte order) over the socket.
int	sendi2LSB (softint i=0)
	Sends a 2-byte (16-bit) integer in little-endian format over the socket.
int	sendi4 (softint i=0)
	Sends a 4-byte (32-bit) integer in big-endian format (network byte order) over the socket.
int	sendi4LSB (softint i=0)
	Sends a 4-byte (32-bit) integer in little-endian format over the socket.
int	sendi8 (softint i=0)
	Sends an 8-byte (64-bit) integer in big-endian format (network byte order) over the socket.
int	sendi8LSB (softint i=0)
	Sends an 8-byte (64-bit) integer in little-endian format over the socket.
nothing	setCertificate (SSLCertificate cert)
	Sets the X.509 certificate to use for negotiating encrypted connections.
nothing	setCertificate (string cert_pem)
	Sets the X.509 certificate to use for negotiating encrypted connections from the PEM-encoded string representing the X.509 certificate.
nothing	setCertificate (binary cert_der)
	Sets the X.509 certificate to use for negotiating encrypted connections from the DER-encoded binary object representing the X.509 certificate.
nothing	setCharset (string encoding)
	Sets the character encoding for the socket.
nothing	setEncoding (string encoding)
	Sets the character encoding for the socket.
nothing	setEventQueue ()
	Removes any Queue object from the Socket object so that socket events are no longer added to the Queue.
nothing	setEventQueue (Queue queue)
	Sets a Queue object to receive socket events.
int	setNoDelay (bool nd=True)
	Sets the boolean `TCP_NODELAY` setting for the socket.
nothing	setPrivateKey (SSLPrivateKey key)
	Sets the private key to use for negotiating encrypted connections along with the X.509 certificate.
nothing	setPrivateKey (string key_pem, *string pass)
	Sets the private key to use for negotiating encrypted connections along with the X.509 certificate from a PEM-encoded string representing the private key and an optional password.
nothing	setPrivateKey (binary key_der)
	Sets the private key to use for negotiating encrypted connections along with the X.509 certificate from a DER-encoded binary object representing the private key.
int	setRecvTimeout (timeout timeout_ms)
	sets the receive timeout as a socket option
int	setSendTimeout (timeout timeout_ms)
	sets the send timeout as a socket option
int	shutdown ()
	Ensures that a socket will be closed even if the file descriptor is shared with other processes (for example, after a call to fork())
nothing	shutdownSSL ()
	Shuts down the SSL connection on a secure connection.
nothing	upgradeClientToSSL ()
	Upgrades a client socket connection to a TLS/SSL connection.
nothing	upgradeServerToSSL ()
	Upgrades a server socket connection to a TLS/SSL connection.
*string	verifyPeerCertificate ()
	Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not currently established.

Detailed Description

The Socket class allows Qore programs safe access to network sockets.

Note:: This class is not available with the PO_NO_NETWORK parse option.

Non-blocking socket I/O can be performed by appending a timeout value in milliseconds to all Socket::recv*() methods, or by using the Socket::isDataAvailable() method with a timeout value in milliseconds (1000 ms = 1 second). Note that as with all Qore functions and methods accepting a timeout value, relative date/time values can be given instead of integers to make the source more readable, for example:

    my bool $rc = $socket.isDataAvailable(1250ms); # times out in 1.25 seconds

Socket objects can automatically convert character encodings if desired when sending string data with Socket::send(). Use the Socket::setEncoding() method to set the character encoding for the socket. If a character encoding is set, and string data is read with the Socket::recv() method, then it will be tagged with the encoding of the socket as well.

Client applications should call Socket::connect() to connect to a remote port or a UNIX domain socket (socket file on the local server). However, if the remote end is expecting a TLS/SSL connection, use Socket::connectSSL() instead.

Server applications should call Socket::bind(), Socket::listen(), and Socket::accept() in this order to accept incoming connections. Normally a new thread should be started after the Socket::accept() call to handle the new connection in a separate thread (Socket::accept() returns a new Socket object for the accepted connection).

To support TLS/SSL server connections, first set the certificate and private key with the Socket::setCertificate() and Socket::setPrivateKey() methods (see the SSLCertificate Class and the SSLPrivateKey Class for more information on the parameters required for these methods). Then Socket::acceptSSL() should be called after the socket is in a listening state to accept client connections and negotiate a TLS/SSL connection.

This class supports posting events to a Queue. See I/O Event Handling for more information.

The events raised by this object are listed in the following table:

Socket Events

Name	Description
EVENT_PACKET_READ	Raised when a network packet is received.
EVENT_PACKET_SENT	Raised when a network packet is sent.
EVENT_CHANNEL_CLOSED	Raised when a socket is closed.
EVENT_DELETED	Raised when the object being monitored is deleted.
EVENT_HOSTNAME_LOOKUP	Raised when a hostname lookup is attempted.
EVENT_HOSTNAME_RESOLVED	Raised when a hostname lookup is resolved.
EVENT_HTTP_SEND_MESSAGE	Raised when an HTTP message is sent.
EVENT_HTTP_MESSAGE_RECEIVED	Raised when an HTTP message is received.
EVENT_CONNECTING	Raised right before a socket connection attempt is made.
EVENT_CONNECTED	Raised when the socket connection has been established.
EVENT_START_SSL	Raised when socket SSL negotiation starts.
EVENT_SSL_ESTABLISHED	Raised when SSL communication has been negotiated and established.

Socket Information Hash

Key	Description
`hostname`	The interface name if available (ex: `"localhost"`; note that this key is not present when retrieving information about UNIX sockets)
`hostname_desc`	A descriptive string giving the hostname and the address family if the hostname is available (ex: `"ipv6[localhost]"`; note that this key is not present when retrieving information about UNIX sockets)
`address`	A string giving the address (ex: `"::ffff:0.0.0.0"`)
`address_desc`	A descriptive string giving the address and the address family (ex: `"ipv6[::ffff:0.0.0.0]"`)
`port`	An integer port number if available (note that this key is not present when retrieving information about UNIX sockets)
`family`	The network address family (see Network Address Family Constants)
`familystr`	A string describing the network address family (ex: `"ipv4"`)

Member Function Documentation

Socket Qore::Socket::accept ( )

Accepts connections on a listening socket.

Accepts connections on a listening socket; if any errors occur, an exception is thrown.

The new Socket object returned will have the same character encoding as the current object. Once a new connection has been accepted, call Socket::getPeerInfo() to get information about the remote socket.

Example:

 my Socket $new_socket = $sock.accept();

Returns:: a new Socket object is returned for the new connection

Exceptions:

SOCKET-NOT-OPEN	The socket is not bound
SOCKET-ACCEPT-ERROR	Error in accepting connection

See also:: Socket::acceptSSL(), Socket::listen(), Socket::getPeerInfo()

*Socket Qore::Socket::accept ( timeout timeout_ms )

Accepts connections on a listening socket (see Socket::listen()) accepting a timeout value with a millisecond resolution.

If any errors occur, an exception is thrown.

The new Socket object returned will have the same character encoding as the current object. Once a new connection has been accepted, call Socket::getPeerInfo() to get information about the remote socket.

Example:

 my *Socket $new_socket = $sock.accept(30s);

Parameters:

timeout_ms If a timeout value is passed and the connection takes longer to establish than the timeout, then NOTHING is returned

Returns:: If no connection is accepted within the timeout period, then NOTHING is returned, otherwise a Socket object for the new connection is returned.

Exceptions:

SOCKET-NOT-OPEN	The socket is not bound
SOCKET-ACCEPT-ERROR	Error in accepting connection

See also:: Socket::acceptSSL(), Socket::listen(), Socket::getPeerInfo()

Socket Qore::Socket::acceptSSL ( )

Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection.

Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection; if any errors occur, an exception is thrown.

The new Socket object returned will have the same character encoding as the current object. Once a new connection has been accepted, call Socket::getPeerInfo() to get information about the remote socket.

Example:

 my Socket $new_socket = $sock.acceptSSL();

Returns:: When a new connection is accepted and a TLS/SSL session has been successfully negotated, a new Socket object is returned for the new connectio

Exceptions:

SOCKET-NOT-OPEN	The socket is not bound
SOCKET-ACCEPT-ERROR	Error in accepting connection

See also:: Socket::accept(), Socket::listen(), Socket::getPeerInfo()

*Socket Qore::Socket::acceptSSL ( timeout timeout_ms )

Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection accepting a timeout value with a millisecond resolution.

If any errors occur, an exception is thrown.

The new Socket object returned will have the same character encoding as the current object. Once a new connection has been accepted, call Socket::getPeerInfo() to get information about the remote socket.

Example:

 my *Socket $new_socket = $sock.acceptSSL(30s);

Parameters:

timeout_ms If a timeout value is passed and the connection takes longer to establish than the timeout, then NOTHING is returned

Returns:: If no connection is accepted within the timeout period, then NOTHING is returned, otherwise a Socket object for the new connection is returned.

Exceptions:

SOCKET-NOT-OPEN	The socket is not bound
SOCKET-ACCEPT-ERROR	Error in accepting connection

See also:: Socket::acceptSSL(), Socket::listen(), Socket::getPeerInfo()

int Qore::Socket::bind	(	string	str,
		softbool	reuseaddr = `False`
	)

Opens and binds the socket to a port, interface and port (if the $bind_to string has a format "host:port"), or UNIX domain socket file.

If the second parameter is True, then the socket will set the SO_REUSEADDR option, which will allow the socket to be bound to a port that is not yet closed (for example, in a TIME_WAIT state).

If any errors occur a non-zero error code is returned.

This method tries to automatically pick the appropriate address family from the arguments; note that a hostname or address in square brackets (ex: "[localhost]") will be looked up and bound as an IPv6 address; additionally, the method recognizes ipv6 addresses by embedded colons (:) in the address string and binds them as such.

Internally, the getaddrinfo() function is used to look up bind addresses; internal bind() operations are tried in sequence for each address returned; as soon as a bind operation is successful, the method returns. If none of the addresses can be bound, then an error code is returned.

Parameters:

str If a colon appears in the string, the string will be assumed to be a "bind_address:port" specification, and the port on the named IP address will be bound, otherwise, if the string contains no colon, the socket will be bound to a UNIX domain socket file on the local filesystem with the given name. Note that a hostname or address in square brackets (ex: "[localhost]") will be looked up and bound as an IPv6 address; additionally, the method recognizes ipv6 addresses by embedded colons (:) in the address string (if surrounded by square brackets) and binds them as such.

reuseaddr If this optional argument evaluates to True, the SO_REUSEADDR option will be set on the socket, which will allow the socket to be bound to a port that is not yet closed (for example, in a TIME_WAIT state); note that this only applies to IPv4 (AF_INET) and IPv6 (AF_INET6) sockets; this option is ignored for UNIX (AF_UNIX) sockets.

See also:: Socket::bindINET() and Socket::bindUNIX()

Note:: UNIX domain sockets are not available on native Windows ports

int Qore::Socket::bind	(	int	port,
		softbool	reuseaddr = `False`
	)

Opens and binds the socket to an INET port on all interfaces.

If the second parameter is True, then the socket will set the SO_REUSEADDR option, which will allow the socket to be bound to a port that is not yet closed (for example, in a TIME_WAIT state).

If any errors occur a non-zero error code is returned.

Example:

 # bind to port 80 on all interfaces on the local system and reuse the address, check return code
if ($sock.bind(80, True))
    throw "BIND-ERROR", strerror(errno());

Parameters:

port	A port number to bind to on all interfaces
reuseaddr	If this optional argument evaluates to True, the `SO_REUSEADDR` option will be set on the socket, which will allow the socket to be bound to a port that is not yet closed (for example, in a `TIME_WAIT` state)

See also:: Socket::bindINET() and Socket::bindUNIX()

nothing Qore::Socket::bindINET	(	*string	iface,
		*softstring	service,
		softbool	reuseaddr = `False`,
		softint	family = `AF_UNSPEC`,
		softint	socktype = `SOCK_STREAM`,
		softint	protocol = `0`
	)

Opens and binds the socket to the given IPv4 or IPv6 interface (or if no interface is given, then to all interfaces on the local system) and port (the port number will be derived from the service name if a numeric port number is not given)

Opens and binds the socket to a port, interface and port (if the interface string has a format "host:port"), or UNIX domain socket file (if no port or service name appears in the bind string). If the second parameter is True, then the socket will set the SO_REUSEADDR option, which will allow the socket to be bound to a port that is not yet closed (for example, in a TIME_WAIT state).

Internally, the getaddrinfo() function is used to look up bind addresses; internal bind() operations are tried in sequence for each address returned; as soon as a bind operation is successful, the method returns. If none of the addresses can be bound, then an error code is returned.

If any errors occur, an exception is thrown.

Examples:

 # bind to port 80 on all interfaces on the local system and reuse the address
$sock.bindINET(NOTHING, 80, True);

 # bind to interface 192.168.2.23 port 8080 and do not reuse the address
$sock.bindINET("192.168.2.23", 8080);

 # bind to localhost port 8080 with ipv6 and do not reuse the address
$sock.bindINET("localhost", 8080, False, AF_INET6);

 # bind to ipv6 host address fe80::21c:42ff:fe00:8, port 1001, reuse the address
$sock.bindINET("fe80::21c:42ff:fe00:8", 1001, True);

Parameters:

iface	the host name or IP address to bind to
service	the service name (ex: "http" or port number (given as or converted to a string) to bind to
reuseaddr	if this optional argument evaluates to True, the `SO_REUSEADDR` option will be set on the socket, which will allow the socket to be bound to a port that is not yet closed (for example, in a `TIME_WAIT` state)
family	the address family to use to bind; see Network Address Family Constants; `AF_UNSPEC` means to try all possible addres families
socktype	the type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets
protocol	the protocol number for the socket; use 0 for the default protocol

Exceptions:

SOCKET-BIND-ERROR	Both hostname and service name are empty or not set; error opening socket for bind; error binding on socket.
QOREADDRINFO-GETINFO-ERROR	error looking up either nodename or servicename (or not known)

See also:: Socket::bind() and Socket::bindUNIX()

nothing Qore::Socket::bindUNIX	(	string	path,
		softint	socktype = `SOCK_STREAM`,
		softint	protocol = `0`
	)

Opens and binds the socket to the given UNIX domain socket file as given by the filename argument. If any errors occur, an exception is thrown.

Opens and binds the socket to the given UNIX domain socket file as given by the filename argument. Note that the socket file is automatically deleted in the destructor when a UNIX socket is closed. If any errors occur, an exception is thrown.

Example:

 # bind to UNIX domain socket file "/tmp/socket"
$sock.bindUNIX("/tmp/socket");

Parameters:

path	The path of the UNIX domain socket to create and bind to
socktype	the type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets
protocol	the protocol number for the socket; use 0 for the default protocol

Exceptions:

SOCKET-BIND-ERROR Error opening socket for bind; error binding on socket

See also:: Socket::bind() and Socket::bindINET()

Note:: UNIX domain sockets are not available on native Windows ports

int Qore::Socket::close ( )

Closes an open socket.

Also deletes the UNIX domain socket file if it was created by a call to Socket::bind(). Returns 0 for success, -1 for error; in this case check errno() for the error number

Example:

 if ($sock.close())
    stderr.printf("Error closing socket: %s\n", strerror(errno()));

Events:: EVENT_CHANNEL_CLOSED

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

nothing Qore::Socket::connect	(	string	target,
		timeout	timeout_ms = `-1`
	)

Connects to a remote port (if the string has a format "host:port") or UNIX domain socket file with an optional timeout value with a millisecond resolution.

Connects the socket to a remote (or local) port or UNIX domain socket file, for network (ipv4 and ipv6) connections, accepts an optional timeout value in milliseconds (relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s). If any errors occur, an exception is thrown.

Examples:

 # connect to ipv4 adress 192.168.1.45 port 8080 with a 30 second timeout
$sock.connect("192.168.1.45:8080", 30s);

 # connect to ipv6 adress 2001:0db8:85a3:0000:0000:8a2e:0370:7334 port 80 with a 10 second timeout
$sock.connect("[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80", 10s);

 # connect to localhost using ipv6 (::1) port 80 with a 10 second timeout
$sock.connect("[localhost]:80", 15s);

 # connect to UNIX domain socket file "/tmp/socket"
$sock.connect("/tmp/socket");

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED

Parameters:

target

The target address interpreted with the following rules:

If a colon appears in the string, the string will be assumed to be a "hostname:port" specification to connect to; where "port" can also be a service name (ex: "example.com:https")
If the string contains no colon, the socket will try to connect to a UNIX domain socket file on the local filesystem with the given name.
Enclose ipv6 addresses in square brackets (ex: "[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80", will connect to port 80 on the given ipv6 address); also if a hostname is enclosed in square brackets, it will be resolved as an ipv6 address (ex: "[localhost]:80" will connect to port 80 on ::1, assuming "localhost" can be resolved to the ipv6 loopback address on the system).

timeout_ms If a timeout value is passed and the connection takes longer to establish than the timeout, a "SOCKET-CONNECT-ERROR" exception is thrown.

Exceptions:

SOCKET-CONNECT-ERROR An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc).

See also:: Socket::connectUNIX(), Socket::connectUNIX(), Socket::connectSSL(), Socket::connectINETSSL(), and Socket::connectUNIXSSL()

nothing Qore::Socket::connectINET	(	string	host,
		softstring	service,
		timeout	timeout_ms = `-1`,
		softint	family = `AF_UNSPEC`,
		softint	socktype = `SOCK_STREAM`,
		softint	protocol = `0`
	)

Connects to the given host and port with an optional timeout value with a millisecond resolution.

Connects the socket to a remote (or local) port; accepts an optional timeout value in milliseconds (relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s). If any errors occur, an exception is thrown.

Do not use square brackets to designate ipv6 addresses with this method; just give the address in its normal form (ex: "2001:0db8:85a3:0000:0000:8a2e:0370:7334").

Examples:

 # connect to ipv4 address 192.168.1.45 port 8080 with a 30 second timeout
$sock.connectINET("192.168.1.45", 8080, 30s);

 # connect to ipv6 address 2001:0db8:85a3:0000:0000:8a2e:0370:7334 port 80 with a 20 second timeout
$sock.connectINET("2001:0db8:85a3:0000:0000:8a2e:0370:7334", 80, 20s);

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED

Parameters:

host	The host name or IP address to connect to
service	The service name (ex: `"http"` or port number (given as or converted to a string) to connect to
timeout_ms	If a timeout value is passed and the connection takes longer to establish than the timeout, a `"SOCKET-CONNECT-ERROR"` exception is thrown
family	The address family to use to connect to the remote socket; see Network Address Family Constants
socktype	The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets
protocol	The protocol number for the socket (if not sure leave this 0)

Exceptions:

SOCKET-CONNECT-ERROR An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc)

See also:: Socket::connect(), Socket::connectUNIX(), Socket::connectSSL(), Socket::connectINETSSL(), and Socket::connectUNIXSSL()

nothing Qore::Socket::connectINETSSL	(	string	host,
		softstring	service,
		timeout	timeout_ms = `-1`,
		softint	family = `AF_UNSPEC`,
		softint	socktype = `SOCK_STREAM`,
		softint	protocol = `0`
	)

Connects to the given host and port and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution.

Connects the socket to a remote (or local) port and attempts to establish a TLS/SSL connection; accepts an optional timeout value in milliseconds (relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s). If any errors occur, an exception is thrown.

Do not use square brackets to designate ipv6 addresses with this method; just give the address in its normal form (ex: "2001:0db8:85a3:0000:0000:8a2e:0370:7334").

Examples:

 # connect to 192.168.1.45 port 8080 with a 30 second timeout
$sock.connectINETSSL("192.168.1.45", 8080, 30s);

 # connect to ipv6 address 2001:0db8:85a3:0000:0000:8a2e:0370:7334 port 80 with a 20 second timeout
$sock.connectINETSSL("2001:0db8:85a3:0000:0000:8a2e:0370:7334", 80, 20s);

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Parameters:

host	The host name or IP address to connect to
service	The service name (ex: `"http"` or port number (given as or converted to a string) to connect to
timeout_ms	If a timeout value is passed and the connection takes longer to establish than the timeout, a `"SOCKET-CONNECT-ERROR"` exception is thrown
family	The address family to use to connect to the remote socket; see Network Address Family Constants
socktype	The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets
protocol	The protocol number for the socket (if not sure leave this 0)

Exceptions:

SOCKET-CONNECT-ERROR	An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc)
SOCKET-SSL-ERROR	An error occurred establishing the TLS/SSL connection

See also:: Socket::connect(), Socket::connectUNIX(), Socket::connectSSL(), Socket::connectINET(), and Socket::connectUNIXSSL()

nothing Qore::Socket::connectSSL	(	string	target,
		timeout	timeout_ms = `-1`
	)

Connects to a remote socket and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution.

Connects to a remote socket and attempts to establish a TLS/SSL connection, for network (INET) connections, accepts an optional timeout value in milliseconds (relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s). If any errors occur, an exception is thrown.

Enclose ipv6 addresses in square brackets (ex: "[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80", will connect to port 80 on the given ipv6 address); also if a hostname is enclosed in square brackets, it will be resolved as an ipv6 adress (ex: "[localhost]:80" will connect to port 80 on ::1, assuming "localhost" can be resolved to the ipv6 loopback address on the system).

Examples:

 # connect to ipv4 adress 192.168.1.45 port 8080 with a 30 second timeout
$sock.connectSSL("192.168.1.45:8080", 30s);

 # connect to ipv6 adress 2001:0db8:85a3:0000:0000:8a2e:0370:7334 port 80 with a 10 second timeout
$sock.connectSSL("[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80", 10s);

 # connect to localhost using ipv6 (::1) port 80 with a 10 second timeout
$sock.connectSSL("[localhost]:80", 15s);

 # connect to UNIX domain socket file "/tmp/socket"
$sock.connectSSL("/tmp/socket");

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Parameters:

target

The target address interpreted with the following rules:

If a colon appears in the string, the string will be assumed to be a "hostname:port" specification to connect to; where "port" can also be a service name (ex: "example.com:https")
If the string contains no colon, the socket will try to connect to a UNIX domain socket file on the local filesystem with the given name.
Enclose ipv6 addresses in square brackets (ex: "[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80", will connect to port 80 on the given ipv6 address); also if a hostname is enclosed in square brackets, it will be resolved as an ipv6 address (ex: "[localhost]:80" will connect to port 80 on ::1, assuming "localhost" can be resolved to the ipv6 loopback address on the system).

timeout_ms if a timeout value is passed and the connection takes longer to establish than the timeout, an exception is thrown

Exceptions:

SOCKET-CONNECT-ERROR	An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc)
SOCKET-SSL-ERROR	An error occurred establishing the TLS/SSL connection

See also:: Socket::connect(), Socket::connectUNIX(), Socket::connectUNIXSSL(), Socket::connectINETSSL(), and Socket::connectINET()

nothing Qore::Socket::connectUNIX	(	string	path,
		softint	socktype = `SOCK_STREAM`,
		softint	protocol = `0`
	)

Connects to a UNIX domain socket file.

Connects the socket to the given UNIX domain socket file; if any errors occur, an exception is thrown

Example:

 # connect to UNIX domain socket file "/tmp/socket"
$sock.connectUNIX("/tmp/socket");

Events:: EVENT_CONNECTING, EVENT_CONNECTED

Parameters:

path	The socket will try to connect to a UNIX domain socket file on the local filesystem with the given name
socktype	The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets
protocol	The protocol number for the socket (if not sure leave this 0)

Exceptions:

SOCKET-CONNECT-ERROR An error occured connecting to the socket

See also:: Socket::connect(), Socket::connectINET(), Socket::connectSSL(), Socket::connectINETSSL(), and Socket::connectUNIXSSL()

Note:: UNIX domain sockets are not available on native Windows ports

nothing Qore::Socket::connectUNIXSSL	(	string	path,
		softint	socktype = `SOCK_STREAM`,
		softint	protocol = `0`
	)

Connects to the given UNIX domain socket file and attempts to establish a TLS/SSL connection.

Connects the socket to a UNIX domain socket file and attempts to establish a TLS/SSL connection. If any errors occur, an exception is thrown.

Example:

 # connect to UNIX domain socket file "/tmp/socket"
$sock.connectUNIXSSL("/tmp/socket");

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Parameters:

path	The socket will try to connect to a UNIX domain socket file on the local filesystem with the given name
socktype	The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets
protocol	The protocol number for the socket (if not sure leave this 0)

Exceptions:

SOCKET-CONNECT-ERROR	An error occured connecting to the socket
SOCKET-SSL-ERROR	An error occurred establishing the TLS/SSL connection

See also:: Socket::connect(), Socket::connectUNIX(), Socket::connectSSL(), Socket::connectINETSSL(), and Socket::connectINET()

Note:: UNIX domain sockets are not available on native Windows ports

Qore::Socket::constructor ( )

Creates the socket object.

Example:

 my Socket $sock();

Qore::Socket::copy ( )

Creates a new Socket object, not based on the source being copied.

Example:

 my Socket $newsock = $sock.copy();

string Qore::Socket::getCharset ( )

Returns the character encoding for the socket.

Code Flags:: CONSTANT

A method synonym for Socket::getEncoding(), kept for backwards-compatibility

Returns:: the character encoding for the socket

string Qore::Socket::getEncoding ( )

Returns the character encoding for the socket.

Code Flags:: CONSTANT

Returns:: the character encoding for the socket

bool Qore::Socket::getNoDelay ( )

Returns the TCP_NODELAY setting for the socket.

Code Flags:: CONSTANT

Example:

 my bool $b = $sock.getNoDelay();

Returns:: the TCP_NODELAY setting for the socket

See also:: Socket::setNoDelay() for a description of the TCP_NODELAY setting

hash Qore::Socket::getPeerInfo ( )

Returns a hash of information about the remote end for connected sockets.

If the socket is not connected, an exception is thrown

Example:

 my hash $h = $sock.getPeerInfo();

Returns:: a hash of information about the local socket

Exceptions:

SOCKET-GETPEERINFO-ERROR Socket is not open or error in getpeername()

int Qore::Socket::getPort ( )

Returns the port number of the socket for INET sockets.

Code Flags:: CONSTANT

Example:

 my int $port = $sock.getPort();

Returns:: the port number for an INET connection, -1 if no INET connection has been established

int Qore::Socket::getRecvTimeout ( )

Returns the receive timeout socket option value as an integer in milliseconds.

Code Flags:: CONSTANT

Example:

 my int $to = $sock.getRecvTimeout();

Returns:: the receive timeout socket option value as an integer in milliseconds

int Qore::Socket::getSendTimeout ( )

Returns the send timeout socket option value as an integer in milliseconds.

Code Flags:: CONSTANT

Example:

 my int $to = $sock.getSendTimeout();

Returns:: the send timeout socket option value as an integer in milliseconds

int Qore::Socket::getSocket ( )

Returns the socket file descriptor number.

Code Flags:: CONSTANT

Example:

 my int $sock = $sock.getSocket();

Returns:: the socket file descriptor number or -1 if the socket is not open

hash Qore::Socket::getSocketInfo ( )

Returns information about the local socket as a hash.

If the socket is not open, an exception is thrown

Example:

 my hash $h = $sock.getSocketInfo();

Returns:: a hash of information about the remote end for connected sockets

*string Qore::Socket::getSSLCipherName ( )

Returns the name of the cipher for an encrypted connection or NOTHING if a secure connection has not been established.

Code Flags:: CONSTANT

Example:

 my *string $str = $sock.getSSLCipherName();

Returns:: the name of the cipher for an encrypted connection or NOTHING if a secure connection has not been established

*string Qore::Socket::getSSLCipherVersion ( )

Returns the version string of the cipher for an encrypted connection or NOTHING if a secure connection has not been established.

Code Flags:: CONSTANT

Example:

 my *string $str = $sock.getSSLCipherVersion();

Returns:: the version string of the cipher for an encrypted connection or NOTHING if a secure connection has not been established

bool Qore::Socket::isDataAvailable ( timeout timeout_ms = 0 )

Returns True or False depending on whether there is data to be read on the socket.

With a timeout of zero this method returns immediately and can be used for non-blocking polling the socket for data (can also be used to poll for new connections before Socket::accept()).

Example:

 my bool $b = $sock.isDataAvailable();

Parameters:

timeout_ms an optional timeout in milliseconds (1/1000 second); if no timeout is given, the method returns immediately

Returns:: True if data is available on the Socket within the timeout period, False if not

bool Qore::Socket::isOpen ( )

Returns True if the socket is open.

Code Flags:: CONSTANT

Example:

 my bool $b = $sock.isOpen();

Returns:: True if the socket is open, False if not

bool Qore::Socket::isSecure ( )

Returns True if the connection is a secure TLS/SSL connection.

Code Flags:: CONSTANT

Example:

 my bool $b = $sock.isSecure();

Returns:: True if the connection is encrypted, False if not

bool Qore::Socket::isWriteFinished ( timeout timeout_ms = 0 )

Returns True or False depending on whether all the data has been written to the socket.

With a timeout of zero this method returns immediately.

Example:

 my bool $b = $sock.isWriteFinished();

Parameters:

timeout_ms an optional timeout in milliseconds (1/1000 second); if no timeout is given, the method returns immediately

Returns:: True if the send action completes within the timeout period, False if not

int Qore::Socket::listen ( )

Listens for connections on a bound socket; sets the socket in a listening state.

Listens for new connections on a bound socket.

Example:

 $sock.listen();

Returns:: Returns 0 for success, -1 for error

Exceptions:

SOCKET-NOT-OPEN The socket is not bound

hash Qore::Socket::readHTTPChunkedBody ( timeout timeout_ms = -1 )

Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a string in the "body" key of a hash (including footers received)

If any errors are encountered, an exception is raised

Events:: EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED

Parameters:

timeout_ms The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a "SOCKET-TIMEOUT" exception is raised.

Returns:: a hash of any HTTP footers received (with footer keys converted to lower case), with the body returned in the "body" key as a string in the Socket's encoding

Exceptions:

SOCKET-NOT-OPEN	The socket is not connected
SOCKET-CLOSED	The remote end has closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	The data requested was not received in the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
READ-HTTP-CHUNK-ERROR	negative value given for chunk size by server

hash Qore::Socket::readHTTPChunkedBodyBinary ( timeout timeout_ms = -1 )

Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a binary object in the "body" key of a hash (including footers received)

If any errors are encountered, an exception is raised

Events:: EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED

Parameters:

timeout_ms The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a "SOCKET-TIMEOUT" exception is raised.

Returns:: a hash of any HTTP footers received (with footer keys converted to lower case), with the body returned in the "body" key as a binary object

Exceptions:

SOCKET-NOT-OPEN	The socket is not connected
SOCKET-CLOSED	The remote end has closed the connection
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	The data requested was not received in the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
READ-HTTP-CHUNK-ERROR	negative value given for chunk size by server

hash Qore::Socket::readHTTPHeader	(	timeout	timeout_ms = `-1`,
		*reference	info
	)

Retuns a hash representing the data in the HTTP header read, or, if the data cannot be parsed as an HTTP header, the data read is returned as a string.

If any errors occur reading from the socket or if invalid HTTP data is received, an exception is raised. Accepts an optional timeout value in milliseconds.

Example:

my hash $ans = $sock.readHTTPHeader(10s);

Events:: EVENT_PACKET_READ, EVENT_HTTP_MESSAGE_RECEIVED

Parameters:

timeout_ms	The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised.
info	An optional reference to an lvalue that can accept a hash that will be used as an output variable with one of the following two keys: `request-uri`: (only set when parsing a request header) gives the request URI in an HTTP request `response-uri`: (only set when parsing a response header) gives the response URI in an HTTP response

Returns:

a hash of headers (where each header key is converted to lower-case) also including the following keys giving additional information about the HTTP header received:

http_version: a string giving the HTTP version set in the header
status_code: (HTTP responses only) an integer giving the status code
status_message: (HTTP responses only) if present in an HTTP response, this key will be set to the message after the status code
method: (HTTP requests only) a string giving the HTTP method (i.e. "GET", "POST", etc)
path: (HTTP requests only) a string giving the path in a request without any decoding; use decode_url() to decode if necessary

Exceptions:

SOCKET-NOT-OPEN	The socket is not connected
SOCKET-CLOSED	The remote end closed the connection without sending any data
SOCKET-RECV-ERROR	There was an error receiving the data
SOCKET-TIMEOUT	The data requested was not received in the timeout period
SOCKET-SSL-ERROR	There was an SSL error while reading data from the socket
SOCKET-HTTP-ERROR	Invalid HTTP data was received, in the case of invalid header info received, the `arg` key of the exception hash will have the invalid data received

Since:: Qore 0.8.4 this method always returns a hash and raises a SOCKET-HTTP-ERROR if invalid HTTP data is received

string Qore::Socket::recv	(	softint	size = `0`,
		timeout	timeout_ms = `-1`
	)

Receives data from the socket and returns a string tagged with the Socket's character encoding.

If any errors occur reading from the socket, an exception is raised

Example:

 my string $data = $sock.recv(-1); # read all data available

Events:: EVENT_PACKET_READ

Parameters:

size	the amount of data to read in bytes; to read until the remote closes the connection, use -1; a value of 0 means to read all data currently available or available up until the timeout period (if non-negative)
timeout_ms	the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: the data read, returned as a string tagged with the Socket's character encoding

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection.
SOCKET-RECV-ERROR	there was an error receiving the data.
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:

binary Qore::Socket::recvBinary	(	softint	size = `0`,
		timeout	timeout_ms = `-1`
	)

Receives data from the socket and returns a binary object.

If any errors occur reading from the socket, an exception is raised

Example:

 my binary $data = $sock.recvBinary(-1); # read all data available

Events:: EVENT_PACKET_READ

Parameters:

size	the amount of data to read in bytes; to read until the remote closes the connection, use -1; a value of 0 means to read all data currently available or available up until the timeout period (if non-negative)
timeout_ms	the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: the data read, returned as a binary object

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection.
SOCKET-RECV-ERROR	there was an error receiving the data.
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recv()

int Qore::Socket::recvi1 ( timeout timeout_ms = -1 )

Receives a 1-byte signed integer from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvi1();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 1-byte signed integer read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvu1()

int Qore::Socket::recvi2 ( timeout timeout_ms = -1 )

Receives a 2-byte (16-bit) signed integer in big-endian format (network byte order) from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvi2();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 2-byte signed integer in big-endian format (network byte order) read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvu2(), Socket::recvi2LSB(), Socket::recvu2LSB()

int Qore::Socket::recvi2LSB ( timeout timeout_ms = -1 )

Receives a 2-byte (16-bit) signed integer in little-endian format from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvi2LSB();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 2-byte signed integer in little-endian format read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi2(), Socket::recvu2(), Socket::recvu2LSB()

int Qore::Socket::recvi4 ( timeout timeout_ms = -1 )

Receives a 4-byte (32-bit) signed integer in big-endian format (network byte order) from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvi4();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 4-byte signed integer in big-endian format (network byte order) read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvu4(), Socket::recvi4LSB(), Socket::recvu4LSB()

int Qore::Socket::recvi4LSB ( timeout timeout_ms = -1 )

Receives a 4-byte (32-bit) signed integer in little-endian format from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvi4LSB();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 4-byte signed integer in little-endian format read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi4(), Socket::recvu4(), Socket::recvu4LSB()

int Qore::Socket::recvi8 ( timeout timeout_ms = -1 )

Receives an 8-byte (64-bit) signed integer in big-endian format (network byte order) from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvi8();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 8-byte signed integer in big-endian format (network byte order) read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi8LSB()

int Qore::Socket::recvi8LSB ( timeout timeout_ms = -1 )

Receives an 8-byte (64-bit) signed integer in little-endian format from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvi8LSB();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 8-byte signed integer in little-endian format read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi8()

int Qore::Socket::recvu1 ( timeout timeout_ms = -1 )

Receives a 1-byte unsigned integer from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvu1();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 1-byte unsigned integer read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi1()

int Qore::Socket::recvu2 ( timeout timeout_ms = -1 )

Receives a 2-byte (16-bit) unsigned integer in big-endian format (network byte order) from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvu2();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 2-byte unsigned integer in big-endian format (network byte order) read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi2(), Socket::recvi2LSB(), Socket::recvu2LSB()

int Qore::Socket::recvu2LSB ( timeout timeout_ms = -1 )

Receives a 2-byte (16-bit) unsigned integer in little-endian format from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvi2LSB();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 2-byte unsigned integer in little-endian format read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi2(), Socket::recvu2(), Socket::recvi2LSB()

int Qore::Socket::recvu4 ( timeout timeout_ms = -1 )

Receives a 4-byte (32-bit) unsigned integer in big-endian format (network byte order) from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvu4();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 4-byte unsigned integer in big-endian format (network byte order) read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi4(), Socket::recvi4LSB(), Socket::recvu4LSB()

int Qore::Socket::recvu4LSB ( timeout timeout_ms = -1 )

Receives a 4-byte (32-bit) unsigned integer in little-endian format from the socket.

If any errors occur reading from the socket, an exception is raised

Example:

 my int $val = $sock.recvu4LSB();

Events:: EVENT_PACKET_READ

Parameters:

timeout_ms the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection

Returns:: The 4-byte unsigned integer in little-endian format read; if any errors occur reading from the socket, an exception is raised

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-CLOSED	the remote end has closed the connection
SOCKET-RECV-ERROR	there was an error receiving the data
SOCKET-TIMEOUT	the data requested was not received in the timeout period
SOCKET-SSL-ERROR	there was an SSL error while reading data from the socket

See also:: Socket::recvi4(), Socket::recvu4(), Socket::recvi4LSB()

int Qore::Socket::send ( binary bin )

Sends binary data over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number.

Note:: In case of SSL errors, errno() will not provide any information; use Socket::send2() instead

Example:

if ($sock.send($data))
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

bin	Sends the binary data over the socket

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

See also:

int Qore::Socket::send ( string str )

Sends string data over the socket; string data is converted to the socket's encoding if necessary.

String data will be converted to the encoding set for the socket if necessary. If an error occurs, -1 will be returned; in this case check errno() for the error number.

Note:: In case of SSL errors, errno() will not provide any information; use Socket::send2() instead

Example:

if ($sock.send($str) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

str	dends the string data over the socket without the trailing null ('\0') character; the string's encoding is converted to the socket's encoding if necessary

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

See also:

nothing Qore::Socket::send2 ( binary bin )

Sends binary data over the socket; if any errors occur, an exception is thrown.

Example:

$sock.send2($data);

Events:: EVENT_PACKET_SENT

Parameters:

bin	Sends the binary data over the socket

Exceptions:

SOCKET-NOT-OPEN	The socket is not connected
SOCKET-SEND-ERROR	an error occurred sending the socket data
SOCKET-SSL-ERROR	there was an SSL error while writing data to the socket

See also:

Socket::sendBinary2()

Since:: Qore 0.8.4

nothing Qore::Socket::send2 ( string str )

Sends string data over the socket; string data is converted to the socket's encoding if necessary; if any errors occur, an exception is thrown.

String data will be converted to the encoding set for the socket if necessary.

Example:

$sock.send2($str);

Events:: EVENT_PACKET_SENT

Parameters:

str	dends the string data over the socket without the trailing null ('\0') character; the string's encoding is converted to the socket's encoding if necessary

Exceptions:

SOCKET-NOT-OPEN	The socket is not connected
SOCKET-SEND-ERROR	an error occurred sending the socket data
SOCKET-SSL-ERROR	there was an SSL error while writing data to the socket

See also:

Socket::sendBinary2()

Since:: Qore 0.8.4

int Qore::Socket::sendBinary ( string str )

Sends string data over the socket without converting the string to the socket's encoding, but instead is sent exactly as-is.

If an error occurs, -1 will be returned; in this case check errno() for the error number.

Note:: In case of SSL errors, errno() will not provide any information; use Socket::sendBinary2() instead

Example:

if ($sock.sendBinary($str) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

str	dends the string data over the socket without the trailing null ('\0') character

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

See also:

int Qore::Socket::sendBinary ( binary bin )

Sends binary data over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number.

Note:: In case of SSL errors, errno() will not provide any information; use Socket::sendBinary2() instead

Example:

 if ($sock.sendBinary($data) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

bin	Sends the binary data over the socket

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

See also:

nothing Qore::Socket::sendBinary2 ( string str )

Sends string data over the socket without converting the string to the socket's encoding, but instead is sent exactly as-is; if any errors occur, an exception is thrown.

Example:

$sock.sendBinary2($str);

Events:: EVENT_PACKET_SENT

Parameters:

str	dends the string data over the socket without the trailing null ('\0') character

Exceptions:

SOCKET-NOT-OPEN	The socket is not connected
SOCKET-SEND-ERROR	an error occurred sending the socket data
SOCKET-SSL-ERROR	there was an SSL error while writing data to the socket

See also:: Socket::send2()

Since:: Qore 0.8.4

nothing Qore::Socket::sendBinary2 ( binary bin )

Sends binary data over the socket; if any errors occur, an exception is thrown.

Example:

$sock.sendBinary2($data);

Events:: EVENT_PACKET_SENT

Parameters:

bin	Sends the binary data over the socket

Exceptions:

SOCKET-NOT-OPEN	The socket is not connected
SOCKET-SEND-ERROR	an error occurred sending the socket data
SOCKET-SSL-ERROR	there was an SSL error while writing data to the socket

See also:: Socket::send2()

Since:: Qore 0.8.4

nothing Qore::Socket::sendHTTPMessage	(	string	method,
		string	path,
		string	http_version,
		hash	headers,
		*string	body,
		*reference	info
	)

Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body.

Creates a properly-formatted HTTP message and sends it over the Socket. To send a string without converting the encoding to the Socket's encoding, convert the string to a binary object using the binary() function and use the variant of this method that takes a binary object for the data argument.

Example:

 $sock.sendHTTPMessage("POST", "/RPC2", "1.1", ("Content-Type" : "text/xml"), $xml);

Events:: EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters:

method	the HTTP method name to send (i.e. POST, HEAD, etc)
path	the path component of the URL
http_version	the HTTP protocol version (`"1.0"` or `"1.1"`)
headers	a hash of additional headers to send (key-value pairs)
body	if present (and does not have a length of zero), the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set); string data will be automatically converted to the Socket's encoding if necessary
info	An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `request-uri`: The request URI as sent in the output message

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-SEND-ERROR	Send failed
SOCKET-SSL-ERROR	there was an error sending SSL data

See also:: Socket::sendHTTPResponse(), Socket::readHTTPHeader()

nothing Qore::Socket::sendHTTPMessage	(	string	method,
		string	path,
		string	http_version,
		hash	headers,
		binary	body,
		*reference	info
	)

Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body.

Creates a properly-formatted HTTP message and sends it over the Socket

Example:

 $sock.sendHTTPMessage("POST", "/RPC2", "1.1", ("Content-Type" : "text/xml"), $xml);

Events:: EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters:

method	the HTTP method name to send (i.e. POST, HEAD, etc)
path	the path component of the URL
http_version	the HTTP protocol version (`"1.0"` or `"1.1"`)
headers	a hash of additional headers to send (key-value pairs)
body	if it does not have a length of zero, the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set)
info	An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `request-uri`: The request URI as sent in the output message

Exceptions:

SOCKET-NOT-OPEN	the socket is not connected
SOCKET-SEND-ERROR	Send failed
SOCKET-SSL-ERROR	there was an error sending SSL data

See also:: Socket::sendHTTPResponse(), Socket::readHTTPHeader()

nothing Qore::Socket::sendHTTPResponse	(	softint	status_code,
		string	status_desc,
		string	http_version,
		hash	headers,
		*string	body
	)

Sends an HTTP response with user-defined headers given as a hash and an optional message body.

Creates a properly-formatted HTTP response message and sends it over the Socket (must already be connected). If any errors occur, an exception is raised. To send a string without converting the encoding to the Socket's encoding, convert the string to a binary object using the binary() function and use the variant of this method that takes a binary object for the data argument.

Example:

 $sock.sendHTTPResponse(200, "OK", "1.1", ("Connection":"Keep-Alive"));

Events:: EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters:

status_code	the HTTP status code to send (i.e. `200`, `404`, etc)
status_desc	the descriptive text for the status code.
http_version	the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
headers	a hash of additional headers to send (key-value pairs)
body	if present (and does not have a length of zero), the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set); string data will be automatically converted to the Socket's encoding if necessary

Exceptions:

SOCKET-SENDHTTPRESPONSE-STATUS-ERROR	raised if the status_code (first argument) is < 100 or > 599
ENCODING-CONVERSION-ERROR	the given string could not be converted to the socket's character encoding
SOCKET-NOT-OPEN	the socket is not connected
SOCKET-SEND-ERROR	send failed

nothing Qore::Socket::sendHTTPResponse	(	softint	status_code,
		string	status_desc,
		string	http_version,
		hash	headers,
		binary	body
	)

Sends an HTTP response with user-defined headers given as a hash and a message body as literal binary data.

Creates a properly-formatted HTTP response message and sends it over the Socket (must already be connected). If any errors occur, an exception is raised.

Example:

 $sock.sendHTTPResponse(200, "OK", "1.1", ("Connection":"Keep-Alive"), $bin);

Events:: EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters:

status_code	the HTTP status code to send (i.e. `200`, `404`, etc)
status_desc	the descriptive text for the status code.
http_version	the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
headers	a hash of additional headers to send (key-value pairs)
body	if the binary object given does not have a length of zero, the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set)

Exceptions:

SOCKET-SENDHTTPRESPONSE-STATUS-ERROR	raised if the status_code (first argument) is < 100 or > 599
SOCKET-NOT-OPEN	the socket is not connected
SOCKET-SEND-ERROR	send failed

int Qore::Socket::sendi1 ( softint i = 0 )

Sends a 1-byte integer over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number

Example:

 if ($sock.sendi1($val) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

i	the integer to send; only the least-significant byte will be sent

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

int Qore::Socket::sendi2 ( softint i = 0 )

Sends a 2-byte (16-bit) integer in big-endian format (network byte order) over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number

Example:

 if ($sock.sendi2($val) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

i	the integer to send; only the least-significant 2 bytes will be sent

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

int Qore::Socket::sendi2LSB ( softint i = 0 )

Sends a 2-byte (16-bit) integer in little-endian format over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number

Example:

 if ($sock.sendi2LSB($val) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

i	the integer to send; only the least-significant 2 bytes will be sent

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

int Qore::Socket::sendi4 ( softint i = 0 )

Sends a 4-byte (32-bit) integer in big-endian format (network byte order) over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number

Example:

 if ($sock.sendi4($val) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

i	the integer to send; only the least-significant 4 bytes will be sent

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

int Qore::Socket::sendi4LSB ( softint i = 0 )

Sends a 4-byte (32-bit) integer in little-endian format over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number

Example:

 if ($sock.sendi4LSB($val) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

i	the integer to send; only the least-significant 4 bytes will be sent

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

int Qore::Socket::sendi8 ( softint i = 0 )

Sends an 8-byte (64-bit) integer in big-endian format (network byte order) over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number

Example:

 if ($sock.sendi8($val) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

i	the integer to send

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

int Qore::Socket::sendi8LSB ( softint i = 0 )

Sends an 8-byte (64-bit) integer in little-endian format over the socket.

If an error occurs, -1 will be returned; in this case check errno() for the error number

Example:

 if ($sock.sendi8LSB($val) == -1)
    printf("error sending data: %s\n", strerror(errno()));

Events:: EVENT_PACKET_SENT

Parameters:

i	the integer to send

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

Exceptions:

SOCKET-NOT-OPEN The socket is not connected

nothing Qore::Socket::setCertificate ( SSLCertificate cert )

Sets the X.509 certificate to use for negotiating encrypted connections.

Example:

 $sock.setCertificate($cert);

Parameters:

cert	This must be an SSLCertificate object

nothing Qore::Socket::setCertificate ( string cert_pem )

Sets the X.509 certificate to use for negotiating encrypted connections from the PEM-encoded string representing the X.509 certificate.

Example:

 $sock.setCertificate($cert_string);

Parameters:

cert_pem the PEM-encoded string representing the X.509 certificate

nothing Qore::Socket::setCertificate ( binary cert_der )

Sets the X.509 certificate to use for negotiating encrypted connections from the DER-encoded binary object representing the X.509 certificate.

Example:

 $sock.setCertificate($cert_der);

Parameters:

cert_der the DER-encoded binary object representing the X.509 certificate

nothing Qore::Socket::setCharset ( string encoding )

Sets the character encoding for the socket.

A method synonym for Socket::setEncoding(), kept for backwards-compatibility

Parameters:

encoding The character encoding for the socket

nothing Qore::Socket::setEncoding ( string encoding )

Sets the character encoding for the socket.

Parameters:

encoding the character encoding for the socket

nothing Qore::Socket::setEventQueue ( )

Removes any Queue object from the Socket object so that socket events are no longer added to the Queue.

Example:

 $sock.setEventQueue();

See also:: I/O Event Handling for more information

nothing Qore::Socket::setEventQueue ( Queue queue )

Sets a Queue object to receive socket events.

Example:

 $sock.setEventQueue($queue);

Parameters:

queue the Queue object to receive socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown

Exceptions:

QUEUE-ERROR the Queue passed has a maximum size set

See also:: I/O Event Handling for more information

int Qore::Socket::setNoDelay ( bool nd = True )

Sets the boolean TCP_NODELAY setting for the socket.

When this setting is True, then data will be immediately sent out over the socket, when it is False, then data transmission may be delayed to be packaged with other data for the same target.

Delayed data transmissions may cause problems when the sender immediately closes the socket after sending data; in this case the receiver may not get the data even though the send succeeded.

Note that if no value is given to the method, the argument will be assumed to be True, and output buffering will be turned off for the socket.

Example:

 if ($sock.setNoDelay(True))
    printf("error setting TCP_NODELAY: %s\n", strerror(errno()));

Parameters:

nd	the boolean `TCP_NODELAY` setting for the socket

Returns:: 0 for success, non-zero for errors; to get error information, see errno() and strerror()

See also:: Socket::getNoDelay()

nothing Qore::Socket::setPrivateKey ( SSLPrivateKey key )

Sets the private key to use for negotiating encrypted connections along with the X.509 certificate.

Example:

 $sock.setPrivateKey($key);

Parameters:

key	the private key for the X.509 certificate to use when establishing TLS/SSL encrypted connections

nothing Qore::Socket::setPrivateKey	(	string	key_pem,
		*string	pass
	)

Sets the private key to use for negotiating encrypted connections along with the X.509 certificate from a PEM-encoded string representing the private key and an optional password.

Example:

 $sock.setPrivateKey($key_pem, $password);

Parameters:

key_pem	the PEM-encoded string representing the private key for the X.509 certificate to use when establishing TLS/SSL encrypted connections
pass	the password for the private key, if needed

nothing Qore::Socket::setPrivateKey ( binary key_der )

Sets the private key to use for negotiating encrypted connections along with the X.509 certificate from a DER-encoded binary object representing the private key.

Example:

 $sock.setPrivateKey($key_der);

Parameters:

key_der the DER-encoded binary object representing the private key for the X.509 certificate to use when establishing TLS/SSL encrypted connections

int Qore::Socket::setRecvTimeout ( timeout timeout_ms )

sets the receive timeout as a socket option

Returns 0 for success, -1 for error (check errno() for the actual error in this case)

Example:

 if ($sock.setRecvTimeout(20s))
    printf("error setting timeout on socket: %s\n", strerror(errno()));

Parameters:

timeout_ms the receive timeout to set with a resolution of milliseconds

Returns:: 0 for success, -1 for error (check errno() for the actual error in this case)

int Qore::Socket::setSendTimeout ( timeout timeout_ms )

sets the send timeout as a socket option

Returns 0 for success, -1 for error (check errno() for the actual error in this case)

Example:

 if ($sock.setSendTimeout(20s))
    printf("error setting timeout on socket: %s\n", strerror(errno()));

Parameters:

timeout_ms the send timeout to set with a resolution of milliseconds

Returns:: 0 for success, -1 for error (check errno() for the actual error in this case)

int Qore::Socket::shutdown ( )

Ensures that a socket will be closed even if the file descriptor is shared with other processes (for example, after a call to fork())

Does not throw any exceptions; returns an error code in case of an error

Example:

 if ($sock.shutdown())
    stderr.printf("Error calling Socket::shutdown(): %s\n", strerror(errno()));

Returns:: 0 for success, -1 for error; in this case check errno() for the error number

nothing Qore::Socket::shutdownSSL ( )

Shuts down the SSL connection on a secure connection.

If any errors occur, an exception is raised

Example:

 $sock.shutdownSSL();

Exceptions:

SOCKET-SSL-ERROR an error occurred shutting down the TLS/SSL connection

nothing Qore::Socket::upgradeClientToSSL ( )

Upgrades a client socket connection to a TLS/SSL connection.

Example:

 $sock.upgradeClientToSSL();

nothing Qore::Socket::upgradeServerToSSL ( )

Upgrades a server socket connection to a TLS/SSL connection.

Example:

 $sock.upgradeServerToSSL();

*string Qore::Socket::verifyPeerCertificate ( )

Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not currently established.

Code Flags:: CONSTANT

Example:

 my *string $str = $sock.verifyPeerCertificate();

Returns:: A string code giving the result of verifying the peer's certificate. No value is returned if a secure connection has not been established. The set of possible return values is made up of the keys of the X509_VerificationReasons hash. This hash can also be used to generate a textual description of the verification result.

Public Member Functions

Detailed Description

Member Function Documentation