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 $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.393. 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.394. 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.

Socket::connect()

Y

Connects to a remote port or UNIX domain socket file.

Socket::connectSSL()

Y

Connects to a remote socket and attempts to establish a TLS/SSL connection.

Socket::bind()

Y

Binds the socket to a 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).

Socket::accept()

Y

Accepts connections on a listening socket.

Socket::acceptSSL()

Y

Accepts a remote connection and attempts to negotiate a TLS/SSL connection.

Socket::shutdownSSL()

Y

Shuts down the SSL connection on a secure connection.

Socket::listen()

Y

Listens for connections on the socket

Socket::isDataAvailable()

N

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

Socket::isWriteFinished()

N

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

Socket::send()

Y

Sends string or binary data over the socket

Socket::sendi1()

Y

Sends a 1-byte integer over the socket.

Socket::sendi2()

Y

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

Socket::sendi4()

Y

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

Socket::sendi8()

Y

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

Socket::sendi2LSB()

Y

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

Socket::sendi4LSB()

Y

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

Socket::sendi8LSB()

Y

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

Socket::sendHTTPMessage()

Y

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

Socket::sendHTTPResponse()

Y

Sends an HTTP response with user-defined headers given as a hash

Socket::recv()

Y

Receives data from the socket and returns a string

Socket::recvi1()

Y

Receives a 1-byte signed integer from the socket.

Socket::recvi2()

Y

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

Socket::recvi4()

Y

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

Socket::recvi8()

Y

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

Socket::recvi2LSB()

Y

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

Socket::recvi4LSB()

Y

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

Socket::recvi8LSB()

Y

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

Socket::recvu1()

Y

Receives a 1-byte unsigned integer from the socket.

Socket::recvu2()

Y

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

Socket::recvu4()

Y

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

Socket::recvu2LSB()

Y

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

Socket::recvu4LSB()

Y

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

Socket::recvBinary()

Y

Receives data on a socket and returns a binary object

Socket::readHTTPHeader()

Y

Retuns a hash representing the data in the HTTP header read

Socket::getPort()

N

Returns the port number of the socket for INET sockets.

Socket::shutdown()

N

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

Socket::close()

N

Closes the socket.

Socket::getCharset()

N

Returns the character encoding for the socket.

Socket::setCharset()

N

Sets the character encoding for the socket.

Socket::getNoDelay()

N

Returns the TCP_NODELAY setting for the socket.

Socket::setNoDelay()

N

Sets the TCP_NODELAY setting for the socket.

Socket::getSocket()

N

Returns the socket file descriptor number.

Socket::getSSLCipherName()

N

Returns the name of the cipher for an encrypted connection.

Socket::getSSLCipherVersion()

N

Returns the version string of the cipher for encrypted connections.

Socket::isSecure()

N

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

Socket::isOpen()

N

Returns True if the socket is open.

Socket::setCertificate()

N

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

Socket::setPrivateKey()

N

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

Socket::verifyPeerCertificate()

N

Returns a string code giving the result of verifying the remote certificate.

Socket::setEventQueue()

N

Sets a Queue object to receive socket events.


4.9.1. Socket::constructor()

Synopsis

Creates the socket object.

Usage
new Socket()
Example
$sock = new Socket();

Table 4.395. Arguments for Socket::constructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Object

The new Socket object created.


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(), then the socket file will be deleted as well.

Usage
delete lvalue
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.

Usage
Socket::copy()
Example
$new_sock = $sock.copy();

Table 4.397. Arguments for Socket::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.398. Return Values for Socket::copy()

Return Type

Description

Socket Object

A new Socket object, not based on the original.


4.9.4. Socket::bind()

Synopsis

Binds the socket to a 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).

Usage
Socket::bind(port, [reuse_addr])
Socket::bind(host_and_port, [reuse_addr])
Socket::bind(filename, [reuse_addr])
Examples
# bind to port 80 on all interfaces on the local system and reuse the address
$sock.bind(80, True);
# bind to interface 192.168.2.23 and do not reuse the address
$sock.bind("192.168.2.23");
# bind to UNIX domain socket file "/tmp/socket"
$sock.bind("/tmp/socket");

Table 4.399. Arguments for Socket::bind()

Argument

Type

Description

port

Integer

A single integer will be taken as a port number on the local machine; all network interfaces will be bound with this port number.

host_and_port

String

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.

filename

String

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.

[reuse_addr]

Boolean

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.400. Return Values for Socket::bind()

Return Type

Description

Integer

Returns 0 for success, -1 for error.


Table 4.401. Exceptions Thrown by Socket::bind()

err

desc

SOCKET-BIND-PARAMETER-ERROR

No argument was passed to the method.


4.9.5. Socket::accept()

Synopsis

Accepts connections on a listening socket (see Socket::listen()).

Usage
Socket::accept()
Example
$new_socket = $sock.accept();

Table 4.402. Arguments for Socket::accept()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Socket Object

When a new connection has been accepted, a new Socket object is returned for the new connection.


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

err

desc

SOCKET-NOT-OPEN

The socket is not bound.


4.9.6. Socket::acceptSSL()

Synopsis

Accepts a remote connection and attempts to negotiate a TLS/SSL connection.

Usage
Socket::acceptSSL()
Example
$new_sock = $sock.acceptSSL();
Events
EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Table 4.405. Arguments for Socket::acceptSSL()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Object

A new socket object is returned for the new connection.


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

err

desc

SOCKET-SSL-ERROR

An error occurred establishing the TLS/SSL connection.


4.9.7. Socket::connect()

Synopsis

Connects the socket to a remote port or UNIX domain socket file, 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.

Usage
Socket::connect(string:host_and_port, [timeout_ms])
Socket::connect(string:filename)
Examples
$sock.connect("192.168.1.45:8080", 30s); # connect to 192.168.1.45 port 8080 with a 30 second timeout
$sock.connect("/tmp/socket");       # connect to UNIX domain socket file "/tmp/socket"
Events
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED

Table 4.408. Arguments for Socket::connect()

Argument

Type

Description

host_and_port, [timeout_ms]

String, Integer or Relative Date/Time

If a colon appears in the string, the string will be assumed to be a hostname:port specification to connect to. If a timeout value is passed and the connection takes longer to establish than the timeout, an exception is thrown.

filename

String

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.


Table 4.409. Return Values for Socket::connect()

Return Type

Description

n/a

This method does not return any value; if an error occurs, an exception is thrown.


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

err

desc

SOCKET-CONNECT-PARAMETER-ERROR

No argument was passed to the method.

SOCKET-CONNECT-ERROR

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


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

Usage
Socket::connectSSL(remote, [timeout_ms])
Examples
$sock.connectSSL("192.168.1.45:8080", 30s); # connect to 192.168.1.45 port 8080 with a 30-second timeout
$sock.connectSSL("/tmp/socket");       # connect to UNIX domain socket file "/tmp/socket"
Events
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Table 4.411. Arguments for Socket::connectSSL()

Argument

Type

Description

remote

String

The remote socket, i.e. 'hostname:port', 'filename' (for UNIX domain sockets), etc.

[timeout_ms]

Integer or Date/Time

An optional timeout value for the connection; if the connection cannot be established in the timeout period, an exception is thrown.


Table 4.412. Return Values for Socket::connectSSL()

Return Type

Description

n/a

This method returns no value; if an error occurs, an exception is thrown.


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

err

desc

SOCKET-CONNECTSSL-PARAMETER-ERROR

missing remote socket

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.


4.9.9. Socket::listen()

Synopsis

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

Usage
Socket::listen()
Example
$sock.listen();

Table 4.414. Arguments for Socket::listen()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

SOCKET-NOT-OPEN

The socket is not bound.


4.9.10. Socket::shutdownSSL()

Synopsis

Shuts down the SSL connection on a secure connection.

Usage
Socket::shutdownSSL()
Example
$sock.shutdownSSL();

Table 4.417. Arguments for Socket::shutdownSSL()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Integer

Returns 0 if successful.


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

err

desc

SOCKET-SSL-ERROR

An error occurred shutting down the TLS/SSL connection.


4.9.11. Socket::getSSLCipherName()

Synopsis

Returns the name of the cipher for an encrypted connection.

Usage
Socket::getSSLCipherName()
Example
$str = $sock.getSSLCipherName();

Table 4.420. Arguments for Socket::getSSLCipherName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

String

The name of the cipher for an encrypted connection.


4.9.12. Socket::getSSLCipherVersion()

Synopsis

Returns the version string of the cipher for encrypted connections.

Usage
Socket::getSSLCipherVersion()
Example
$str = $sock.getSSLCipherVersion();

Table 4.422. Arguments for Socket::getSSLCipherVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

String

The version string of the cipher for encrypted connections.


4.9.13. Socket::isSecure()

Synopsis

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

Usage
Socket::isSecure()
Example
$bool = $sock.isSecure();

Table 4.424. Arguments for Socket::isSecure()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Boolean

True if the connection is encrypted.


4.9.14. Socket::isOpen()

Synopsis

Returns True if the socket is open.

Usage
Socket::isOpen()
Example
$bool = $sock.isOpen();

Table 4.426. Arguments for Socket::isOpen()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Boolean

True if the socket is open.


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

Usage
Socket::setCertificate(certificate)
Example
$sock.setCertificate($cert);

Table 4.428. Arguments for Socket::setCertificate()

Argument

Type

Description

certificate

SSLCertificate Object

This must be an SSL Certificate object.


Table 4.429. Return Values for Socket::setCertificate()

Return Type

Description

n/a

This method returns no value


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

Usage
Socket::setPrivateKey(private_key_object)
Example
$sock.setPrivateKey($pkey);

Table 4.430. Arguments for Socket::setPrivateKey()

Argument

Type

Description

privat_key_object

SSLPrivateKey Object

The private key for the certificate.


Table 4.431. Return Values for Socket::setPrivateKey()

Return Type

Description

n/a

This method returns no value


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

Usage
Socket::verifyPeerCertificate()
Example
$str = $sock.verifyPeerCertificate();

Table 4.432. Arguments for Socket::verifyPeerCertificate()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.433. 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 no secure connection has been established.


4.9.18. Socket::setEventQueue()

Synopsis

Sets a Queue object to receive socket events. To remove the event queue and stop monitoring socket events, pass NOTHING to the method. See Event Handling for more information.

Usage
Socket::setEventQueue([queue])
Example
$sock.setEventQueue($queue);

Table 4.434. Arguments for Socket::setEventQueue()

Argument

Type

Description

[queue]

Queue

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


Table 4.435. Return Values for Socket::setEventQueue()

Return Type

Description

n/a

This method does not return any value.


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

Usage
Socket::isDataAvailable([timeout_ms])
Example
$bool = $sock.isDataAvailable(0); # returns True if data is available now

Table 4.436. Arguments for Socket::isDataAvailable()

Argument

Type

Description

[timeout_ms]

Integer

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


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

Return Type

Description

Boolean

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


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

Usage
Socket::isWriteFinished([timeout_ms])
Example
$bool = $sock.isWriteFinished(0);

Table 4.438. Arguments for Socket::isWriteFinished()

Argument

Type

Description

[timeout_ms]

Integer

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


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

Return Type

Description

Boolean

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


4.9.21. Socket::send()

Synopsis

Sends string or binary data over a connected socket. If the argument is not present, or is neither a String or Binary type, an exception will be thrown. String data will be converted to the encoding set for the socket if necessary.

Usage
Socket::send(data)
Example
$sock.send($data);
Events
EVENT_PACKET_SENT

Table 4.440. Arguments for Socket::send()

Argument

Type

Description

data

String

Sends the string data over the socket without the trailing null ('\0') character.

data

Binary

Sends the binary data over the socket.


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

Return Type

Description

Integer

0 for success, -1 for error.


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

err

desc

SOCKET-SEND-PARAMETER-ERROR

No argument was passed to the method.

SOCKET-NOT-OPEN

The socket is not connected.


4.9.22. Socket::sendi1()

Synopsis

Sends a 1-byte integer over the socket.

Usage
Socket::sendi1(integer)
Example
$sock.sendi1($val);
Events
EVENT_PACKET_SENT

Table 4.443. Arguments for Socket::sendi1()

Argument

Type

Description

integer

Integer

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


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.23. Socket::sendi2()

Synopsis

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

Usage
Socket::sendi2(integer)
Example
$sock.sendi2($val);
Events
EVENT_PACKET_SENT

Table 4.446. Arguments for Socket::sendi2()

Argument

Type

Description

integer

Integer

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


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.24. Socket::sendi4()

Synopsis

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

Usage
Socket::sendi4(integer)
Example
$sock.sendi4($val);
Events
EVENT_PACKET_SENT

Table 4.449. Arguments for Socket::sendi4()

Argument

Type

Description

integer

Integer

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


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.25. Socket::sendi8()

Synopsis

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

Usage
Socket::sendi8(integer)
Example
$sock.sendi8($val);
Events
EVENT_PACKET_SENT

Table 4.452. Arguments for Socket::sendi8()

Argument

Type

Description

integer

Integer

The integer to send.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.26. Socket::sendi2LSB()

Synopsis

Sends a 2-byte integer in little-endian format over the socket.

Usage
Socket::sendi2LSB(integer)
Example
$sock.sendi2LSB($val);
Events
EVENT_PACKET_SENT

Table 4.455. Arguments for Socket::sendi2LSB()

Argument

Type

Description

integer

Integer

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


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.27. Socket::sendi4LSB()

Synopsis

Sends a 4-byte integer in little-endian format over the socket.

Usage
Socket::sendi4LSB(integer)
Example
$sock.sendi4LSB($val);
Events
EVENT_PACKET_SENT

Table 4.458. Arguments for Socket::sendi4LSB()

Argument

Type

Description

integer

Integer

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


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.28. Socket::sendi8LSB()

Synopsis

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

Usage
Socket::sendi8LSB(integer)
Example
$sock.sendi8LSB($val);
Events
EVENT_PACKET_SENT

Table 4.461. Arguments for Socket::sendi8LSB()

Argument

Type

Description

integer

Integer

The integer to send.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


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

err

desc

SOCKET-NOT-OPEN

The socket is not connected.


4.9.29. Socket::sendHTTPMessage()

Synopsis

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

Usage
Socket::sendHTTPMessage(string:method, string:path, string:http_version, hash:headers, [body])
Example
$sock.sendHTTPMessage("POST", "/RPC2", "1.1", ("Content-Type" : "text/xml"), $xml);
Events
EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Table 4.464. Arguments for Socket::sendHTTPMessage()

Argument

Type

Description

method

String

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

path

String

The path component of the URL.

http_version

String

The HTTP protocol version (1.0 or 1.1).

headers

Hash

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

[body]

String

If present, the body to be sent with the message (if present, the Content-Length header will be automatically set).

[body]

Binary

If present, the body to be sent with the message (if present, the Content-Length header will be automatically set).


Table 4.465. Return Values for Socket::sendHTTPMessage()

Return Type

Description

n/a

This method returns no value. If any errors occur, exceptions are raised.


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

err

desc

SOCKET-SENDHTTPMESSAGE-PARAMETER-ERROR

One or more of the required arguments is missing.

SOCKET-NOT-OPEN

The socket is not connected.

SOCKET-SEND-ERROR

Send failed.


4.9.30. Socket::sendHTTPResponse()

Synopsis

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

Usage
Socket::sendHTTPResponse(status_code, string:description, string:http_version, hash:headers, [body])
Example
$sock.sendHTTPResponse(200, "OK", "1.1", ("Connection":"Keep-Alive"));
Events
EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Table 4.467. Arguments for Socket::sendHTTPMessage()

Argument

Type

Description

status_code

Integer

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

description

String

The descriptive text for the status code.

http_version

String

The HTTP protocol version (1.0 or 1.1).

headers

Hash

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

[body]

String

If present, the body to be sent with the message (if present, the Content-Length header will be automatically set).

[body]

Binary

If present, the body to be sent with the message (if present, the Content-Length header will be automatically set).


Table 4.468. Return Values for Socket::sendHTTPResponse()

Return Type

Description

n/a

This method returns no value. If any errors occur, exceptions are raised.


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

err

desc

SOCKET-SENDHTTPRESPONSE-PARAMETER-ERROR

One or more of the required arguments is missing.

SOCKET-NOT-OPEN

The socket is not connected.

SOCKET-SEND-ERROR

Send failed.


4.9.31. Socket::recv()

Synopsis

Receives data from the socket and returns a string.

Usage
Socket::recv(size, [timeout_ms])
Example
$data = $sock.recv(-1); # read all data available
Events
EVENT_PACKET_READ

Table 4.470. Arguments for Socket::recv()

Argument

Type

Description

size

Integer

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

[timeout_ms]

Integer

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.471. Return Values for Socket::recv()

Return Type

Description

String

The data read, returned as a string.


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


4.9.32. Socket::recvBinary()

Synopsis

Receives data from the socket and returns a binary object.

Usage
Socket::recvBinary(size, [timeout_ms])
Example
$bin = $sock.recvBinary(-1); # read all data available
Events
EVENT_PACKET_READ

Table 4.473. Arguments for Socket::recvBinary()

Argument

Type

Description

size

Integer

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

[timeout_ms]

Integer

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.474. Return Values for Socket::recvBinary()

Return Type

Description

Binary

The data read, returned as a binary object.


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


4.9.33. Socket::recvi1()

Synopsis

Receives a 1-byte signed integer from the socket.

Usage
Socket::recvi1([timeout_ms])
Example
$int = $sock.recvi1();
Events
EVENT_PACKET_READ

Table 4.476. Arguments for Socket::recvi1()

Argument

Type

Description

[timeout_ms]

Integer

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.477. Return Values for Socket::recvi1()

Return Type

Description

Integer

The 1-byte signed integer read.


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


4.9.34. Socket::recvi2()

Synopsis

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

Usage
Socket::recvi2([timeout_ms])
Example
$int = $sock.recvi2();
Events
EVENT_PACKET_READ

Table 4.479. Arguments for Socket::recvi2()

Argument

Type

Description

[timeout_ms]

Integer

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.480. Return Values for Socket::recvi2()

Return Type

Description

Integer

The 2-byte signed integer read.


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


4.9.35. Socket::recvi4()

Synopsis

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

Usage
Socket::recvi4([timeout_ms])
Example
$int = $sock.recvi4();
Events
EVENT_PACKET_READ

Table 4.482. Arguments for Socket::recvi4()

Argument

Type

Description

[timeout_ms]

Integer

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.483. Return Values for Socket::recvi4()

Return Type

Description

Integer

The 4-byte signed integer read.


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


4.9.36. Socket::recvi8()

Synopsis

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

Usage
Socket::recvi8([timeout_ms])
Example
$int = $sock.recvi8();
Events
EVENT_PACKET_READ

Table 4.485. Arguments for Socket::recvi8()

Argument

Type

Description

[timeout_ms]

Integer

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.486. Return Values for Socket::recvi8()

Return Type

Description

Integer

The 8-byte (64-bit) signed integer read.


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


4.9.37. Socket::recvi2LSB()

Synopsis

Receives a 2-byte signed integer in little-endian format from the socket.

Usage
Socket::recvi2LSB([timeout_ms])
Example
$int = $sock.recvi2LSB();
Events
EVENT_PACKET_READ

Table 4.488. Arguments for Socket::recvi2LSB()

Argument

Type

Description

[timeout_ms]

Integer

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.489. Return Values for Socket::recvi2LSB()

Return Type

Description

Integer

The 2-byte signed integer read.


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


4.9.38. Socket::recvi4LSB()

Synopsis

Receives a 4-byte signed integer in little-endian format from the socket.

Usage
Socket::recvi4LSB([timeout_ms])
Example
$int = $sock.recvi4LSB(1250ms); # timeout in 1.25 seconds
Events
EVENT_PACKET_READ

Table 4.491. Arguments for Socket::recvi4LSB()

Argument

Type

Description

[timeout_ms]

Integer

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.492. Return Values for Socket::recvi4LSB()

Return Type

Description

Integer

The 4-byte signed integer read.


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


4.9.39. Socket::recvi8LSB()

Synopsis

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

Usage
Socket::recvi8LSB([timeout_ms])
Example
$int = $sock.recvi8LSB();
Events
EVENT_PACKET_READ

Table 4.494. Arguments for Socket::recvi8LSB()

Argument

Type

Description

[timeout_ms]

Integer

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.495. Return Values for Socket::recvi8LSB()

Return Type

Description

Integer

The 8-byte (64-bit) signed integer read.


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


4.9.40. Socket::recvu1()

Synopsis

Receives a 1-byte unsigned integer from the socket.

Usage
Socket::recvu1([timeout_ms])
Example
$int = $sock.recvu1();
Events
EVENT_PACKET_READ

Table 4.497. Arguments for Socket::recvu1()

Argument

Type

Description

[timeout_ms]

Integer

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.498. Return Values for Socket::recvu1()

Return Type

Description

Integer

The 1-byte unsigned integer read.


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


4.9.41. Socket::recvu2()

Synopsis

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

Usage
Socket::recvu2([timeout_ms])
Example
$int = $sock.recvu2();
Events
EVENT_PACKET_READ

Table 4.500. Arguments for Socket::recvu2()

Argument

Type

Description

[timeout_ms]

Integer

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.501. Return Values for Socket::recvu2()

Return Type

Description

Integer

The 2-byte unsigned integer read.


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


4.9.42. Socket::recvu4()

Synopsis

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

Usage
Socket::recvu4([timeout_ms])
Example
$int = $sock.recvu4();
Events
EVENT_PACKET_READ

Table 4.503. Arguments for Socket::recvu4()

Argument

Type

Description

[timeout_ms]

Integer

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.504. Return Values for Socket::recvu4()

Return Type

Description

Integer

The 4-byte unsigned integer read.


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


4.9.43. Socket::recvu2LSB()

Synopsis

Receives a 2-byte unsigned integer in little-endian format from the socket.

Usage
Socket::recvu2LSB([timeout_ms])
Example
$int = $sock.recvu2LSB();
Events
EVENT_PACKET_READ

Table 4.506. Arguments for Socket::recvu2LSB()

Argument

Type

Description

[timeout_ms]

Integer

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.507. Return Values for Socket::recvu2LSB()

Return Type

Description

Integer

The 2-byte unsigned integer read.


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


4.9.44. Socket::recvu4LSB()

Synopsis

Receives a 4-byte unsigned integer in little-endian format from the socket.

Usage
Socket::recvu4LSB([timeout_ms])
Example
$int = $sock.recvu4LSB();
Events
EVENT_PACKET_READ

Table 4.509. Arguments for Socket::recvu4LSB()

Argument

Type

Description

[timeout_ms]

Integer

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.510. Return Values for Socket::recvu4LSB()

Return Type

Description

Integer

The 4-byte unsigned integer read.


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


4.9.45. Socket::readHTTPHeader()

Synopsis

Reads an HTTP header and returns a hash representing the data read. 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.512. 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.

 

Usage
Socket::readHTTPHeader([timeout_ms])
Example
$hash = $sock.readHTTPHeader();
Events
EVENT_PACKET_READ, EVENT_HTTP_MESSAGE_RECEIVED

Table 4.513. Arguments for Socket::readHTTPHeader()

Argument

Type

Description

[timeout_ms]

Integer

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


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


4.9.46. Socket::getPort()

Synopsis

Returns the port number of the socket for INET sockets.

Usage
Socket::getPort()
Example
$port = $sock.getPort();

Table 4.516. Arguments for Socket::getPort()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Integer

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


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

Usage
Socket::shutdown()
Example
$sock.shutdown();

Table 4.518. Arguments for Socket::shutdown()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


4.9.48. Socket::close()

Synopsis

Closes an open socket. Also deletes the UNIX domain socket file if it was created by a call to Socket::bind()

Usage
Socket::close()
Example
$sock.close();
Events
EVENT_CHANNEL_CLOSED

Table 4.520. Arguments for Socket::close()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Integer

Returns 0 for success, -1 for error.


4.9.49. Socket::getCharset()

Synopsis

Returns the character encoding for the socket.

Usage
Socket::getCharset()
Example
$enc = $sock.getCharset();

Table 4.522. Arguments for Socket::getCharset()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

String

The character encoding for the socket.


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

Usage
Socket::setCharset(string:encoding)
Example
$sock.setCharset("ISO-8859-1");

Table 4.524. Arguments for Socket::setCharset()

Argument

Type

Description

encoding

String

The character encoding for the socket.


Table 4.525. Return Value for Socket::setCharset()

Return Type

Description

n/a

This method does not return any value.


4.9.51. Socket::getNoDelay()

Synopsis

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

Usage
Socket::getNoDelay()
Example
$nodelay = $sock.getNoDelay();

Table 4.526. Arguments for Socket::getNoDelay()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Boolean

The TCP_NODELAY setting for the socket.


4.9.52. 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 False, and output buffering will be turned on for the socket, which may be the opposite of what the programmer intends, therefore it's recommended to always pass an argument to this method.

See also Socket::getNoDelay().

Usage
Socket::setNoDelay(boolean)
Example
$sock.setNoDelay(True);

Table 4.528. Arguments for Socket::setNoDelay()

Argument

Type

Description

boolean

boolean

The TCP_NODELAY setting for the socket.


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

Return Type

Description

Integer

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


4.9.53. Socket::getSocket()

Synopsis

Returns the file descriptor number associated with the socket.

Usage
Socket::getSocket()
Example
$sock = $sock.getSocket();

Table 4.530. Arguments for Socket::getSocket()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


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

Return Type

Description

Integer

The file descriptor associated to the socket.