4.9. Socket Class
Prev Chapter 4. System Namespaces and Class Library Next

4.9. Socket Class

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

Socket objects allow Qore programs safe access to network sockets. 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::setCharset() 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 Event Handling for more information.

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

Table 4.341. 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.


Table 4.342. Socket Method Overview

Method

Except?

Description

Socket::constructor()

N

Creates the socket object

Socket::destructor()

N

Closes the socket if it's open and destroys the object.

Socket::copy()

N

Creates a new Socket object, not based on the parent.

nothingSocket::connect(string$dest, timeout$timeout_ms = -1)

Y

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.

nothingSocket::connectINET(string$host, softstring$service, timeout$timeout_ms = -1, softint$family = AF_UNSPEC, softint$socktype = SOCK_STREAM)

Y

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

nothingSocket::connectUNIX(string$file)

Y

Connects to the UNIX domain socket file.

nothingSocket::connectSSL(string$dest, timeout$timeout_ms = -1)

Y

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

nothingSocket::connectINETSSL(string$host, softstring$service, timeout$timeout_ms = -1, softint$family = AF_UNSPEC, softint$socktype = SOCK_STREAM)

Y

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

nothingSocket::connectUNIXSSL(string$file)

Y

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

intSocket::bind(string$bind_to, softbool$reuseaddr = False)

intSocket::bind(int$port, softbool$reuseaddr = False)

N

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.

nothingSocket::bindINET(*string$interface, *softstring$service, softbool$reuseaddr = False, softint$family = AF_UNSPEC, softint$socktype = SOCK_STREAM, softint$protocol = 0)

Y

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). If the third 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, an exception is thrown.

nothingSocket::bindUNIX(string$path, softint$socktype = SOCK_STREAM, softint$protocol = 0)

Y

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.

SocketSocket::accept()

*SocketSocket::accept(timeout$timeout_ms)

Y

Accepts connections on a listening socket with a variant accepting a timeout value with a millisecond resolution. If the variant with a timeout is used, then if no connection is accepted within the timeout period, then NOTHING is returned, otherwise a Socket object for the new connection is returned. Otherwise, if any errors occur, an exception is thrown.

SocketSocket::acceptSSL()

*SocketSocket::acceptSSL(timeout$timeout_ms)

Y

Accepts a remote connection and attempts to negotiate a TLS/SSL connection. If the variant with a timeout is used, then if no connection is accepted within the timeout period, then NOTHING is returned, otherwise a Socket object for the new connection is returned. Otherwise, if any errors occur, an exception is thrown.

nothingSocket::shutdownSSL()

Y

Shuts down the SSL connection on a secure connection.

intSocket::listen()

Y

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

boolSocket::isDataAvailable(timeout$timeout_ms = 0)

N

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

boolSocket::isWriteFinished(timeout$timeout_ms = 0)

N

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

intSocket::send(data$data)

Y

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

intSocket::sendBinary(data$data)

Y

Sends string or binary data over the socket; string data is not converted to the socket's encoding, but sent exactly as-is.

intSocket::sendi1(softint$i = 0)

Y

Sends a 1-byte integer over the socket.

intSocket::sendi2(softint$i = 0)

Y

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

intSocket::sendi4(softint$i = 0)

Y

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

intSocket::sendi8(softint$i = 0)

Y

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

intSocket::sendi2LSB(softint$i = 0)

Y

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

intSocket::sendi4LSB(softint$i = 0)

Y

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

intSocket::sendi8LSB(softint$i = 0)

Y

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

nothingSocket::sendHTTPMessage(string$method, string$path, string$http_version, hash$headers, data$body = binary())

Y

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

Socket::sendHTTPResponse(softint$status_code, string$desc, string$http_version, hash$headers, data$body = binary())

Y

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

stringSocket::recv(softint$size = 0, timeout$timeout_ms = -1)

Y

Receives data from the socket and returns a string.

intSocket::recvi1(timeout$timeout_ms = -1)

Y

Receives a 1-byte signed integer from the socket.

intSocket::recvi2(timeout$timeout_ms = -1)

Y

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

intSocket::recvi4(timeout$timeout_ms = -1)

Y

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

intSocket::recvi8(timeout$timeout_ms = -1)

Y

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

intSocket::recvi2LSB(timeout$timeout_ms = -1)

Y

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

intSocket::recvi4LSB(timeout$timeout_ms = -1)

Y

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

intSocket::recvi8LSB(timeout$timeout_ms = -1)

Y

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

intSocket::recvu1(timeout$timeout_ms = -1)

Y

Receives a 1-byte unsigned integer from the socket.

intSocket::recvu2(timeout$timeout_ms = -1)

Y

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

intSocket::recvu4(timeout$timeout_ms = -1)

Y

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

intSocket::recvu2LSB(timeout$timeout_ms = -1)

Y

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

intSocket::recvu4LSB(timeout$timeout_ms = -1)

Y

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

binarySocket::recvBinary(softint$size = 0, timeout$timeout_ms = -1)

Y

Receives data on a socket and returns a binary object

anySocket::readHTTPHeader(timeout$timeout_ms = -1)

Y

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.

hashSocket::getPeerInfo()

Y

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

intSocket::getPort()

N

Returns the port number of the socket for INET sockets.

hashSocket::getSocketInfo()

Y

Returns information about the local socket as a hash; the socket must be open.

intSocket::shutdown()

N

Ensures that a socket will be closed even if shared with other processes.

intSocket::close()

N

Closes the socket.

stringSocket::getCharset()

N

Returns the character encoding for the socket.

nothingSocket::setCharset(string$encoding)

N

Sets the character encoding for the socket.

boolSocket::getNoDelay()

N

Returns the TCP_NODELAY setting for the socket.

intSocket::setNoDelay(bool$nodelay = True)

N

Sets the TCP_NODELAY setting for the socket.

intSocket::getSocket()

N

Returns the socket file descriptor number.

*stringSocket::getSSLCipherName()

N

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

*stringSocket::getSSLCipherVersion()

N

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

boolSocket::isSecure()

N

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

boolSocket::isOpen()

N

Returns True if the socket is open.

nothingSocket::setCertificate(SSLCertificate$cert)

nothingSocket::setCertificate(string$cert_pem)

nothingSocket::setCertificate(binary$cert_der)

N

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

nothingSocket::setPrivateKey(SSLPrivateKey$key)

nothingSocket::setPrivateKey(string$key_pem, string$pass)

nothingSocket::setPrivateKey(string$key_pem)

nothingSocket::setPrivateKey(binary$key_der)

N

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

anySocket::verifyPeerCertificate()

N

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

nothingSocket::setEventQueue()

nothingSocket::setEventQueue(Queue$queue)

N

Sets a Queue object to receive socket events, or clears the queue when called with no argument..


4.9.1. Socket::constructor()

Synopsis

Creates the socket object.

Prototype

Socket::constructor()

Example
my Socket $sock();

4.9.2. Socket::destructor()

Synopsis

Closes the socket if it's open and destroys the object. If the socket was a UNIX domain socket, and was created with Socket::bind() or Socket::bindUNIX(), then the socket file will be deleted as well.

Example
delete $sock;
Events

EVENT_CHANNEL_CLOSED, EVENT_DELETED

4.9.3. Socket::copy()

Synopsis

Creates a new Socket object, not based on the original.

Example
my Socket $new_sock = $sock.copy();

4.9.4. Socket::bind()

Synopsis

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 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).

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.

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

Note

UNIX domain sockets are not available on native Windows ports.

Prototype

intSocket::bind(string$bind_to, softbool$reuseaddr = False)

intSocket::bind(int$port, softbool$reuseaddr = False)

Examples
# 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());
# bind to interface 192.168.2.23 port 8080 and do not reuse the address, check return code
if ($sock.bind("192.168.2.23:8080"))
    throw "BIND-ERROR", strerror(errno());
# bind to localhost port 8080 with ipv6 and do not reuse the address, check return code
if ($sock.bind("[localhost]:8080"))
    throw "BIND-ERROR", strerror(errno());
# bind to ipv6 host address fe80::21c:42ff:fe00:8, port 1001, reuse the address, check return code
if ($sock.bind("[fe80::21c:42ff:fe00:8]:1001", True))
    throw "BIND-ERROR", strerror(errno());
# bind to UNIX domain socket file "/tmp/socket", check return code
if ($sock.bind("/tmp/socket"))
    throw "BIND-ERROR", strerror(errno());

Table 4.343. Arguments for Socket::bind(string $bind_to, softbool $reuseaddr = False) Variant

Argument

Description

string$bind_to

If a colon appears in the string, the string will be assumed to be a hostname: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.

softbool$reuseaddr = False

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.


Table 4.344. Arguments for Socket::bind(int $port, softbool $reuseaddr = False) Variant

Argument

Description

int$port, softbool$reuseaddr = False

The first argument gives the port number on the local machine; all network interfaces will be bound with this port number.

softbool$reuseaddr = False

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).


Table 4.345. Return Values for Socket::bind()

Return Type

Description

int

Returns 0 for success, -1 for error.


This method does not throw any exceptions.

4.9.5. Socket::bindINET()

Synopsis

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 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.

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

Prototype

nothingSocket::bindINET(*string$interface, *softstring$service, softbool$reuseaddr = False, softint$family = AF_UNSPEC, softint$socktype = SOCK_STREAM, softint$protocol = 0)

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);

Table 4.346. Arguments for Socket::bindINET()

Argument

Description

*string$interface

The host name or IP address to bind to.

*softstring$service

The service name (ex: "http" or port number (given as or converted to a string) to bind to.

softbool$reuseaddr = False

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).

softint$family = AF_UNSPEC

The address family to use to bind; see Network Address Family Constants. AF_UNSPEC means to try all possible addres families.

softint$socktype = SOCK_STREAM

The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets.

softint$protocol = 0

The protocol number for the socket; use 0 for the default protocol.


Table 4.347. Exceptions Thrown by Socket::bindINET()

err

desc

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)


4.9.6. Socket::bindUNIX()

Synopsis

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.

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

Note

UNIX domain sockets are not available on native Windows ports.

Prototype

nothingSocket::bindUNIX(string$path, softint$socktype = SOCK_STREAM, softint$protocol = 0)

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

Table 4.348. Arguments for Socket::bindUNIX()

Argument

Description

string$path

The path of the UNIX domain socket to create and bind to.

softint$socktype = SOCK_STREAM

The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets.

softint$protocol = 0

The protocol number for the socket; use 0 for the default protocol.


Table 4.349. Exceptions Thrown by Socket::bindUNIX()

err

desc

SOCKET-BIND-ERROR

Error opening socket for bind; error binding on socket.


4.9.7. Socket::accept()

Synopsis

Accepts connections on a listening socket (see Socket::listen()) with a variant accepting a timeout value with a millisecond resolution. If the variant with a timeout is used, then if no connection is accepted within the timeout period, then NOTHING is returned, otherwise a Socket object for the new connection is returned.

Otherwise, 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.

Prototype

SocketSocket::accept()

*SocketSocket::accept(timeout$timeout_ms)

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

Table 4.350. Arguments for Socket::accept()

Argument

Description

[timeout$timeout_ms]

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


Table 4.351. Return Values for Socket::accept()

Return Type

Description

*Socket

When a new connection has been accepted, a new Socket object is returned for the new connection, unless the variable with a timeout is used and a timeout occurs; in this case NOTHING is returned.


Table 4.352. Exceptions Thrown by Socket::accept()

err

desc

SOCKET-NOT-OPEN

The socket is not bound.

SOCKET-ACCEPT-ERROR

Error in accepting connection.


4.9.8. Socket::acceptSSL()

Synopsis

Accepts connections on a listening socket (see Socket::listen()) and attempts to negotiate a TLS/SSL connection.

If the variant with a timeout is used, then if no connection is accepted within the timeout period, then NOTHING is returned, otherwise a Socket object for the new connection is returned.

Otherwise, 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.

Prototype

SocketSocket::acceptSSL()

*SocketSocket::acceptSSL(timeout$timeout_ms)

Example
my *Socket $new_sock = $sock.acceptSSL(30s);
Events

EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Table 4.353. Arguments for Socket::acceptSSL()

Argument

Description

[timeout$timeout_ms]

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


Table 4.354. Return Values for Socket::acceptSSL()

Return Type

Description

*Socket

When a new connection is accepted and a TLS/SSL session has been successfully negotated, a new Socket object is returned for the new connection, unless the variable with a timeout is used and a timeout occurs; in this case NOTHING is returned.


Table 4.355. Exceptions thrown by Socket::acceptSSL()

err

desc

SOCKET-NOT-OPEN

The socket is not bound.

SOCKET-ACCEPT-ERROR

Error in accepting connection.

SOCKET-SSL-ERROR

An error occurred establishing the TLS/SSL connection.

SOCKET-CLOSED

The TLS/SSL connection was shut down by the remote end.


4.9.9. Socket::connect()

Synopsis

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.

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 squark 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).

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

Note

UNIX domain sockets are not available on native Windows ports.

Prototype

nothingSocket::connect(string$dest, timeout$timeout_ms = -1)

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

Table 4.356. Arguments for Socket::connect()

Argument

Description

string$dest

If a colon appears in the string, the string will be assumed to be a hostname:port specification to connect to. 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.

timeout$timeout_ms = -1

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


Table 4.357. Exceptions Thrown by Socket::connect()

err

desc

SOCKET-CONNECT-ERROR

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


4.9.10. Socket::connectINET()

Synopsis

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").

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

Note

UNIX domain sockets are not available on native Windows ports.

Prototype

nothingSocket::connectINET(string$host, softstring$service, timeout$timeout_ms = -1, softint$family = AF_UNSPEC, softint$socktype = SOCK_STREAM)

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

Table 4.358. Arguments for Socket::connectINET()

Argument

Description

string$host

The host name or IP address to connect to.

softstring$service

The service name (ex: "http" or port number (given as or converted to a string) to connect to.

timeout$timeout_ms = -1

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

softint$family = AF_UNSPEC

The address family to use to connect to the remote socket; see Network Address Family Constants.

softint$socktype = SOCK_STREAM

The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets.


Table 4.359. Exceptions Thrown by Socket::connectINET()

err

desc

SOCKET-CONNECT-ERROR

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


4.9.11. Socket::connectINETSSL()

Synopsis

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").

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

Prototype

nothingSocket::connectINETSSL(string$host, softstring$service, timeout$timeout_ms = -1, softint$family = AF_UNSPEC, softint$socktype = SOCK_STREAM)

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

Table 4.360. Arguments for Socket::connectINETSSL()

Argument

Description

string$host

The host name or IP address to connect to.

softstring$service

The service name (ex: "http" or port number (given as or converted to a string) to connect to.

timeout$timeout_ms = -1

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


Table 4.361. Exceptions Thrown by Socket::connectINETSSL()

err

desc

SOCKET-CONNECT-ERROR

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


4.9.12. Socket::connectUNIX()

Synopsis

Connects the socket to a UNIX domain socket file. If any errors occur, an exception is thrown.

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

Note

UNIX domain sockets are not available on native Windows ports.

Prototype

nothingSocket::connectUNIX(string$file, softint$socktype = SOCK_STREAM, softint$protocol = 0)

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

EVENT_CONNECTING, EVENT_CONNECTED

Table 4.362. Arguments for Socket::connectUNIX()

Argument

Description

string$file

The socket will try to connect to a UNIX domain socket file on the local filesystem with the given name.

softint$socktype = SOCK_STREAM

The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets.

softint$protocol = 0

The protocol number for the socket; use 0 for the default protocol.


Table 4.363. Exceptions Thrown by Socket::connectUNIX()

err

desc

SOCKET-CONNECT-ERROR

An error occured connecting to the remote socket.


4.9.13. Socket::connectUNIXSSL()

Synopsis

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.

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

Note

UNIX domain sockets are not available on native Windows ports.

Prototype

nothingSocket::connectUNIXSSL(string$file, softint$socktype = SOCK_STREAM, softint$protocol = 0)

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

EVENT_CONNECTING, EVENT_CONNECTED

Table 4.364. Arguments for Socket::connectUNIXSSL()

Argument

Description

string$file

The socket will try to connect to a UNIX domain socket file on the local filesystem with the given name.

softint$socktype = SOCK_STREAM

The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets.

softint$protocol = 0

The protocol number for the socket; use 0 for the default protocol.


Table 4.365. Exceptions Thrown by Socket::connectUNIXSSL()

err

desc

SOCKET-CONNECT-ERROR

An error occured connecting to the remote socket.


4.9.14. Socket::connectSSL()

Synopsis

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 squark 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).

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

Note

UNIX domain sockets are not available on native Windows ports.

Prototype

nothingSocket::connectSSL(string$dest, timeout$timeout_ms = -1)

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

Table 4.366. Arguments for Socket::connectSSL()

Argument

Description

string$dest

If a colon appears in the string, the string will be assumed to be a hostname:port specification to connect to. 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.

timeout$timeout_ms = -1

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


Table 4.367. Exceptions thrown by Socket::connectSSL()

err

desc

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.

SOCKET-CLOSED

The TLS/SSL connection was shut down by the remote end.


4.9.15. Socket::listen()

Synopsis

Listens for new connections on a bound socket (see Socket::bind())

Prototype

intSocket::listen()

Example
$sock.listen();

Table 4.368. Return Values for Socket::listen()

Return Type

Description

int

Returns 0 for success, -1 for error.


Table 4.369. Exceptions Thrown by Socket::listen()

err

desc

SOCKET-NOT-OPEN

The socket is not bound.


4.9.16. Socket::shutdownSSL()

Synopsis

Shuts down the SSL connection on a secure connection; if any errors occur, an exception is raised.

Prototype

nothingSocket::shutdownSSL()

Example
$sock.shutdownSSL();

Table 4.370. Exceptions thrown by Socket::shutdownSSL()

err

desc

SOCKET-SSL-ERROR

An error occurred shutting down the TLS/SSL connection.


4.9.17. Socket::getSSLCipherName()

Synopsis

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

Prototype

*stringSocket::getSSLCipherName()

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

Table 4.371. Return Values for Socket::getSSLCipherName()

Return Type

Description

*string

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


4.9.18. Socket::getSSLCipherVersion()

Synopsis

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

Prototype

*stringSocket::getSSLCipherVersion()

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

Table 4.372. Return Values for Socket::getSSLCipherVersion()

Return Type

Description

*string

The version string of the cipher for encrypted connections or NOTHING if an encrypted connection has not been established.


4.9.19. Socket::isSecure()

Synopsis

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

Prototype

boolSocket::isSecure()

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

Table 4.373. Return Values for Socket::isSecure()

Return Type

Description

bool

True if the connection is encrypted, False if not.


4.9.20. Socket::isOpen()

Synopsis

Returns True if the socket is open.

Prototype

boolSocket::isOpen()

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

Table 4.374. Return Values for Socket::isOpen()

Return Type

Description

bool

True if the socket is open, False if not.


4.9.21. Socket::setCertificate()

Synopsis

Sets the X.509 certificate to use for negotiating encrypted connections. Requires an SSLCertificate object as the only argument to the method or the PEM or DER-encoded form of the certificate.

Prototype

nothingSocket::setCertificate(SSLCertificate$cert)

nothingSocket::setCertificate(string$cert_pem)

nothingSocket::setCertificate(binary$cert_der)

Example
$sock.setCertificate($cert);

Table 4.375. Arguments for Socket::setCertificate()

Argument

Description

SSLCertificate$cert

This must be an SSL Certificate object.

string$cert_pem

The PEM-encoded string for the SSL Certificate.

binary $cert_der

The DER-encoded binary for the SSL Certificate.


4.9.22. Socket::setPrivateKey()

Synopsis

Sets the private key to use for negotiating encrypted connections along with the X.509 certificate. Requires an SSLPrivateKey object as the only argument to the method or the PEM or DER-encoded form of the private key.

Prototype

nothingSocket::setPrivateKey(SSLPrivateKey$key)

nothingSocket::setPrivateKey(string$key_pem, string$pass)

nothingSocket::setPrivateKey(string$key_pem)

nothingSocket::setPrivateKey(binary$key_der)

Example
$sock.setPrivateKey($pkey);

Table 4.376. Arguments for Socket::setPrivateKey()

Argument

Description

SSLPrivateKey$key

The private key for the certificate.

string$key_pem, [string$pass]

The PEM-encoded string for the private key for the certificate and optionally the password if required.

binary $key_der

The DER-encoded binary form of the private key for the certificate.


4.9.23. Socket::verifyPeerCertificate()

Synopsis

Returns a string code giving the result of verifying the remote certificate. Return value are the keys described in the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.

Prototype

*stringSocket::verifyPeerCertificate()

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

Table 4.377. Return Values for Socket::verifyPeerCertificate()

Return Type

Description

*string

A string code giving the result of verifying the peer's certificate. No value is returned if a secure connection has not been established.


4.9.24. Socket::setEventQueue()

Synopsis

Sets a Queue object to receive socket events. To remove the event queue and stop monitoring socket events; call with no arguments or pass NOTHING to the method. See Event Handling for more information.

Prototype

nothingSocket::setEventQueue()

nothingSocket::setEventQueue(Queue$queue)

Example
$sock.setEventQueue($queue);

Table 4.378. Arguments for Socket::setEventQueue()

Argument

Description

[Queue$queue]

To set the event queue, pass a Queue object; to clear the event queue, pass no argument to the function.


4.9.25. Socket::isDataAvailable()

Synopsis

Returns True is data is available on the socket, takes an optional timeout. With a timeout of zero this method can be used for non-blocking polling the socket for data (can also be used to poll for new connections before Socket::accept()).

Prototype

boolSocket::isDataAvailable(timeout$timeout_ms = 0)

Example
my bool $b = $sock.isDataAvailable(); # returns True if data is available now

Table 4.379. Arguments for Socket::isDataAvailable()

Argument

Description

timeout$timeout_ms = 0

An optional timeout in milliseconds (1/1000 second). If no timeout is given, the method returns immediately.


Table 4.380. Return Values for Socket::isDataAvailable()

Return Type

Description

bool

True if data is available on the socket, False if not.


4.9.26. Socket::isWriteFinished()

Synopsis

Returns True if all data has been written to the socket, takes an optional timeout. With a timeout of zero this method returns immediately.

Prototype

boolSocket::isWriteFinished(timeout$timeout_ms = 0)

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

Table 4.381. Arguments for Socket::isWriteFinished()

Argument

Description

timeout$timeout_ms = 0

An optional timeout in milliseconds (1/1000 second). If no timeout is given, the method returns immediately.


Table 4.382. Return Values for Socket::isWriteFinished()

Return Type

Description

bool

True if the send action is complete, False if not.


4.9.27. Socket::send()

Synopsis

Sends string or binary data over a connected socket. 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.

See also Socket::sendBinary().

Prototype

intSocket::send(data$data)

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

EVENT_PACKET_SENT

Table 4.383. Arguments for Socket::send()

Argument

Description

string$data

Sends 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.

binary$data

Sends the binary data over the socket.


Table 4.384. Return Values for Socket::send()

Return Type

Description

int

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


Table 4.385. Exceptions Thrown by Socket::send()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.28. Socket::sendBinary()

Synopsis

Sends string or binary data over a connected socket. String data will not be converted to the encoding set for the socket, but rather will be sent as-is, even if the string's encoding is different from the socket's encoding. If an error occurs, -1 will be returned; in this case check errno() for the error number.

See also Socket::send().

Prototype

intSocket::sendBinary(data$data)

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

EVENT_PACKET_SENT

Table 4.386. Arguments for Socket::sendBinary()

Argument

Description

string$data

Sends the string data over the socket without the trailing null ('\0') character; the string's encoding is not converted to the socket's encoding, even if it is different.

binary$data

Sends the binary data over the socket.


Table 4.387. Return Values for Socket::sendBinary()

Return Type

Description

int

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


Table 4.388. Exceptions Thrown by Socket::sendBinary()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.29. Socket::sendi1()

Synopsis

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.

Prototype

intSocket::sendi1(softint$i = 0)

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

EVENT_PACKET_SENT

Table 4.389. Arguments for Socket::sendi1()

Argument

Description

softint$i = 0

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


Table 4.390. Return Values for Socket::sendi1()

Return Type

Description

int

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


Table 4.391. Exceptions Thrown by Socket::sendi1()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.30. Socket::sendi2()

Synopsis

Sends a 2-byte 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.

Prototype

intSocket::sendi2(softint$i = 0)

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

EVENT_PACKET_SENT

Table 4.392. Arguments for Socket::sendi2()

Argument

Description

softint$i = 0

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


Table 4.393. Return Values for Socket::sendi2()

Return Type

Description

int

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


Table 4.394. Exceptions Thrown by Socket::sendi2()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.31. Socket::sendi4()

Synopsis

Sends a 4-byte 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.

Prototype

intSocket::sendi4(softint$i = 0)

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

EVENT_PACKET_SENT

Table 4.395. Arguments for Socket::sendi4()

Argument

Description

softint$i = 0

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


Table 4.396. Return Values for Socket::sendi4()

Return Type

Description

int

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


Table 4.397. Exceptions Thrown by Socket::sendi4()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.32. Socket::sendi8()

Synopsis

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.

Prototype

intSocket::sendi8(softint$i = 0)

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

EVENT_PACKET_SENT

Table 4.398. Arguments for Socket::sendi8()

Argument

Description

softint$i = 0

The integer to send.


Table 4.399. Return Values for Socket::sendi8()

Return Type

Description

int

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


Table 4.400. Exceptions Thrown by Socket::sendi8()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.33. Socket::sendi2LSB()

Synopsis

Sends a 2-byte 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.

Prototype

intSocket::sendi2LSB(softint$i = 0)

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

EVENT_PACKET_SENT

Table 4.401. Arguments for Socket::sendi2LSB()

Argument

Description

softint$i = 0

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


Table 4.402. Return Values for Socket::sendi2LSB()

Return Type

Description

int

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


Table 4.403. Exceptions Thrown by Socket::sendi2LSB()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.34. Socket::sendi4LSB()

Synopsis

Sends a 4-byte 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.

Prototype

intSocket::sendi4LSB(softint$i = 0)

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

EVENT_PACKET_SENT

Table 4.404. Arguments for Socket::sendi4LSB()

Argument

Description

softint$i = 0

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


Table 4.405. Return Values for Socket::sendi4LSB()

Return Type

Description

int

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


Table 4.406. Exceptions Thrown by Socket::sendi4LSB()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.35. Socket::sendi8LSB()

Synopsis

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.

Prototype

intSocket::sendi8LSB(softint$i = 0)

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

EVENT_PACKET_SENT

Table 4.407. Arguments for Socket::sendi8LSB()

Argument

Description

softint$i = 0

The integer to send.


Table 4.408. Return Values for Socket::sendi8LSB()

Return Type

Description

int

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


Table 4.409. Exceptions Thrown by Socket::sendi8LSB()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.36. Socket::sendHTTPMessage()

Synopsis

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

Prototype

nothingSocket::sendHTTPMessage(string$method, string$path, string$http_version, hash$headers, data$body = binary())

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

EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Table 4.410. Arguments for Socket::sendHTTPMessage()

Argument

Description

string$method

The HTTP method name to send (i.e. POST, HEAD, etc)

string$path

The path component of the URL.

string$http_version

The HTTP protocol version (1.0 or 1.1).

hash$headers

A hash of additional headers to send (key-value pairs).

data$body = binary()

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).


Table 4.411. Exceptions Thrown by Socket::sendHTTPMessage()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.

SOCKET-SEND-ERROR

Send failed.


4.9.37. Socket::sendHTTPResponse()

Synopsis

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

Prototype

nothingSocket::sendHTTPResponse(softint$status_code, string$desc, string$http_version, hash$headers, data $body = binary())

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

EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Table 4.412. Arguments for Socket::sendHTTPResponse()

Argument

Description

softint$status_code

The HTTP status code to send (i.e. 200, 404, etc)

string$desc

The descriptive text for the status code.

string$http_version

The HTTP protocol version (1.0 or 1.1).

hash$headers

A hash of additional headers to send (key-value pairs).

data$body = binary()

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).


Table 4.413. Exceptions Thrown by Socket::sendHTTPResponse()

err

desc

SOCKET-NOT-OPEN

The socket is not connected.

SOCKET-SEND-ERROR

Send failed.


4.9.38. Socket::recv()

Synopsis

Receives data from the socket and returns a string. If any errors occur reading from the socket, an exception is raised.

Prototype

stringSocket::recv(softint$size = 0, timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.414. Arguments for Socket::recv()

Argument

Description

softint$size = 0

The amount of data to read in bytes. To read until the remote closes the connection, use -1.

timeout$timeout_ms = -1

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.


Table 4.415. Return Values for Socket::recv()

Return Type

Description

string

The data read, returned as a string. If any errors occur reading from the socket, an exception is raised.


Table 4.416. Exceptions Thrown by Socket::recv()

err

desc

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.


4.9.39. Socket::recvBinary()

Synopsis

Receives data from the socket and returns a binary object. If any errors occur reading from the socket, an exception is raised.

Prototype

binarySocket::recvBinary(softint$size = 0, timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.417. Arguments for Socket::recvBinary()

Argument

Description

softint$size = 0

The amount of data to read in bytes. To read until the remote closes the connection, use -1.

timeout$timeout_ms = -1

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.


Table 4.418. Return Values for Socket::recvBinary()

Return Type

Description

binary

The data read, returned as a binary object. If any errors occur reading from the socket, an exception is raised.


Table 4.419. Exceptions Thrown by Socket::recvBinary()

err

desc

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.


4.9.40. Socket::recvi1()

Synopsis

Receives a 1-byte signed integer from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvi1(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.420. Arguments for Socket::recvi1()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.421. Return Values for Socket::recvi1()

Return Type

Description

int

The 1-byte signed integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.422. Exceptions Thrown by Socket::recvi1()

err

desc

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.


4.9.41. Socket::recvi2()

Synopsis

Receives a 2-byte signed integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvi2(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.423. Arguments for Socket::recvi2()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.424. Return Values for Socket::recvi2()

Return Type

Description

int

The 2-byte signed integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.425. Exceptions Thrown by Socket::recvi2()

err

desc

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.


4.9.42. Socket::recvi4()

Synopsis

Receives a 4-byte signed integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvi4(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.426. Arguments for Socket::recvi4()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.427. Return Values for Socket::recvi4()

Return Type

Description

int

The 4-byte signed integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.428. Exceptions Thrown by Socket::recvi4()

err

desc

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.


4.9.43. Socket::recvi8()

Synopsis

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.

Prototype

intSocket::recvi8(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.429. Arguments for Socket::recvi8()

Argument

Description

timeout$timeout_ms = -1

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. A relative date/time value can be used as well (i.e. 1250ms) for clarity.


Table 4.430. Return Values for Socket::recvi8()

Return Type

Description

int

The 8-byte (64-bit) signed integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.431. Exceptions Thrown by Socket::recvi8()

err

desc

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.


4.9.44. Socket::recvi2LSB()

Synopsis

Receives a 2-byte signed integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvi2LSB(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.432. Arguments for Socket::recvi2LSB()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.433. Return Values for Socket::recvi2LSB()

Return Type

Description

int

The 2-byte signed integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.434. Exceptions Thrown by Socket::recvi2LSB()

err

desc

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.


4.9.45. Socket::recvi4LSB()

Synopsis

Receives a 4-byte signed integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvi4LSB(timeout$timeout_ms = -1)

Example
my int $val = $sock.recvi4LSB(1250ms); # timeout in 1.25 seconds
Events

EVENT_PACKET_READ

Table 4.435. Arguments for Socket::recvi4LSB()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.436. Return Values for Socket::recvi4LSB()

Return Type

Description

int

The 4-byte signed integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.437. Exceptions Thrown by Socket::recvi4LSB()

err

desc

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.


4.9.46. Socket::recvi8LSB()

Synopsis

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.

Prototype

intSocket::recvi8LSB(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.438. Arguments for Socket::recvi8LSB()

Argument

Description

timeout$timeout_ms = -1

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. A relative date/time value can be used as well (i.e. 1250ms) for clarity.


Table 4.439. Return Values for Socket::recvi8LSB()

Return Type

Description

int

The 8-byte (64-bit) signed integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.440. Exceptions Thrown by Socket::recvi8LSB()

err

desc

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.


4.9.47. Socket::recvu1()

Synopsis

Receives a 1-byte unsigned integer from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvu1(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.441. Arguments for Socket::recvu1()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.442. Return Values for Socket::recvu1()

Return Type

Description

int

The 1-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.443. Exceptions Thrown by Socket::recvu1()

err

desc

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.


4.9.48. Socket::recvu2()

Synopsis

Receives a 2-byte unsigned integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvu2(timeout$timeout_ms = -1)

intSocket::recvu2(date$timeout)

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

EVENT_PACKET_READ

Table 4.444. Arguments for Socket::recvu2()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.445. Return Values for Socket::recvu2()

Return Type

Description

int

The 2-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.446. Exceptions Thrown by Socket::recvu2()

err

desc

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.


4.9.49. Socket::recvu4()

Synopsis

Receives a 4-byte unsigned integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvu4(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.447. Arguments for Socket::recvu4()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.448. Return Values for Socket::recvu4()

Return Type

Description

int

The 4-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.449. Exceptions Thrown by Socket::recvu4()

err

desc

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.


4.9.50. Socket::recvu2LSB()

Synopsis

Receives a 2-byte unsigned integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvu2LSB(timeout$timeout_ms = -1)

Example
my int $val = $sock.recvu2LSB();
Events

EVENT_PACKET_READ

Table 4.450. Arguments for Socket::recvu2LSB()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.451. Return Values for Socket::recvu2LSB()

Return Type

Description

int

The 2-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.452. Exceptions Thrown by Socket::recvu2LSB()

err

desc

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.


4.9.51. Socket::recvu4LSB()

Synopsis

Receives a 4-byte unsigned integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.

Prototype

intSocket::recvu4LSB(timeout$timeout_ms = -1)

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

EVENT_PACKET_READ

Table 4.453. Arguments for Socket::recvu4LSB()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.454. Return Values for Socket::recvu4LSB()

Return Type

Description

int

The 4-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised.


Table 4.455. Exceptions Thrown by Socket::recvu4LSB()

err

desc

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.


4.9.52. Socket::readHTTPHeader()

Synopsis

Reads an HTTP header and returns a hash representing the data read. If any errors occur reading from the socket, an exception is raised. Accepts an optional timeout value in milliseconds.

This method sets the keys in the following table in the hash returned as well to give additional information about the HTTP header received.

Table 4.456. Special Keys in Hash Returned By Socket::readHTTPHeader()

Key

Description of Value

http_version

A string giving the HTTP version set in the header

status_code

An integer giving the status code; this key is only set in HTTP responses

status_message

If present in an HTTP response, this key will be set to the message after the status code

method

A string giving the HTTP method (i.e. GET, POST, etc); this key is only set when a request header is received

path

A string giving the path in a request without any decoding; use decode_url() to decode if necessary.


Prototype

anySocket::readHTTPHeader(timeout$timeout_ms = -1)

Example
my hash $hash = $sock.readHTTPHeader();
Events

EVENT_PACKET_READ, EVENT_HTTP_MESSAGE_RECEIVED

Table 4.457. Arguments for Socket::readHTTPHeader()

Argument

Description

timeout$timeout_ms = -1

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.


Table 4.458. Return Values for Socket::readHTTPHeader()

Return Type

Description

hash

The return hash will contain keys for each header, plus an http_version key, giving the HTTP protocol version. For HTTP responses, the following keys will be returned: status_code, status_message. For outgoing HTTP messages, the following keys will be populated: method, path. If any errors occur reading from the socket, an exception is raised.


Table 4.459. Exceptions Thrown by Socket::readHTTPHeader()

err

desc

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.


4.9.53. Socket::getPeerInfo()

Synopsis

Returns a Socket Information Hash about the remote end for connected sockets; if the socket is not connected, an exception is thrown.

Prototype

hashSocket::getPeerInfo()

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

Table 4.460. Return Values for Socket::getPeerInfo()

Return Type

Description

hash

Returns a Socket Information Hash about the remote end for connected sockets; if the socket is not connected, an exception is thrown.


Table 4.461. Exceptions thrown by Socket::getPeerInfo()

err

desc

SOCKET-GETPEERINFO-ERROR

Socket is not open or error in getpeername()


Table 4.462. 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")


4.9.54. Socket::getPort()

Synopsis

Returns the port number of the socket for INET sockets.

Prototype

intSocket::getPort()

Example
$port = $sock.getPort();

Table 4.463. Return Values for Socket::getPort()

Return Type

Description

int

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


4.9.55. Socket::getPeerInfo()

Synopsis

Returns a Socket Information Hash about the local socket; if the socket is not open, an exception is thrown.

Prototype

hashSocket::getSocketInfo()

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

Table 4.464. Return Values for Socket::getSocketInfo()

Return Type

Description

hash

Returns a Socket Information Hash about the local socket; if the socket is not open, an exception is thrown.


Table 4.465. Exceptions thrown by Socket::getSocketInfo()

err

desc

SOCKET-GETSOCKETINFO-ERROR

Socket is not open or error in getsockname()


4.9.56. Socket::shutdown()

Synopsis

Ensures that a socket will be closed even if the file descriptor is shared with other processes (for example, after a call to fork()). Returns 0 for success, -1 for error; in this case check errno() for the error number.

Prototype

intSocket::shutdown()

Example
$sock.shutdown();

Table 4.466. Return Values for Socket::shutdown()

Return Type

Description

int

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


4.9.57. Socket::close()

Synopsis

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.

Prototype

intSocket::close()

Example
$sock.close();
Events

EVENT_CHANNEL_CLOSED

Table 4.467. Return Values for Socket::close()

Return Type

Description

int

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


4.9.58. Socket::getCharset()

Synopsis

Returns the character encoding for the socket.

Prototype

stringSocket::getCharset()

Example
$enc = $sock.getCharset();

Table 4.468. Return Value for Socket::getCharset()

Return Type

Description

string

The character encoding for the socket.


4.9.59. Socket::setCharset()

Synopsis

Sets the character encoding for the socket. If any string data is sent over the socket with Socket::send(), then the character encoding will be automatically converted if needed.

Prototype

nothingSocket::setCharset(string$encoding)

Example
$sock.setCharset("ISO-8859-1");

Table 4.469. Arguments for Socket::setCharset()

Argument

Description

string$encoding

The character encoding for the socket.


4.9.60. Socket::getNoDelay()

Synopsis

Returns the TCP_NODELAY setting for the socket. See also Socket::setNoDelay().

Prototype

boolSocket::getNoDelay()

Example
$nodelay = $sock.getNoDelay();

Table 4.470. Return Value for Socket::getNoDelay()

Return Type

Description

bool

The TCP_NODELAY setting for the socket.


4.9.61. Socket::setNoDelay()

Synopsis

Sets the 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.

See also Socket::getNoDelay().

Prototype

intSocket::setNoDelay(bool$nodelay = True)

Example
$sock.setNoDelay(True);

Table 4.471. Arguments for Socket::setNoDelay()

Argument

Description

bool$nodelay = True

The TCP_NODELAY setting for the socket.


Table 4.472. Return Value for Socket::setNoDelay()

Return Type

Description

int

0 for success, non-zero for errors. To get error information, see errno() and strerror().


4.9.62. Socket::getSocket()

Synopsis

Returns the file descriptor number associated with the socket.

Prototype

intSocket::getSocket()

Example
$sock = $sock.getSocket();

Table 4.473. Return Values for Socket::getSocket()

Return Type

Description

int

The file descriptor associated to the socket.


Prev Up Next
4.8. Program Class Home 4.10. HTTPClient Class

There are no comments yet

Leave a Comment



?
? ?
?

 
Powered by TalkBack