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 |
---|---|
Raised when a network packet is received. | |
Raised when a network packet is sent. | |
Raised when a socket is closed. | |
Raised when the object being monitored is deleted. | |
Raised when a hostname lookup is attempted. | |
Raised when a hostname lookup is resolved. | |
Raised when an HTTP message is sent. | |
Raised when an HTTP message is received. | |
Raised right before a socket connection attempt is made. | |
Raised when the socket connection has been established. | |
Raised when socket SSL negotiation starts. | |
Raised when SSL communication has been negotiated and established. |
Table 4.394. Socket Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the socket object | |
N | Closes the socket if it's open and destroys the object. | |
N | Creates a new Socket object, not based on the parent. | |
Y | Connects to a remote port or UNIX domain socket file. | |
Y |
Connects to a remote socket and attempts to establish a TLS/SSL connection. | |
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). | |
Y | Accepts connections on a listening socket. | |
Y |
Accepts a remote connection and attempts to negotiate a TLS/SSL connection. | |
Y |
Shuts down the SSL connection on a secure connection. | |
Y | Listens for connections on the socket | |
N | Returns True or False depending on whether there is data to be read on the socket | |
N | Returns True or False depending on whether all data has been written to the socket | |
Y | Sends string or binary data over the socket | |
Y | Sends a 1-byte integer over the socket. | |
Y | Sends a 2-byte (16-bit) integer in big-endian format (network byte order) over the socket. | |
Y | Sends a 4-byte (32-bit) integer in big-endian format (network byte order) over the socket. | |
Y | Sends an 8-byte (64-bit) integer in big-endian format (network byte order) over the socket. | |
Y | Sends a 2-byte (16-bit) integer in little-endian format over the socket. | |
Y | Sends a 4-byte (32-bit) integer in little-endian format over the socket. | |
Y | Sends an 8-byte (64-bit) integer in little-endian format over the socket. | |
Y | Sends an HTTP message with a method and user-defined headers given as a hash | |
Y | Sends an HTTP response with user-defined headers given as a hash | |
Y | Receives data from the socket and returns a string | |
Y | Receives a 1-byte signed integer from the socket. | |
Y | Receives a 2-byte (16-bit) signed integer in big-endian format (network byte order) from the socket. | |
Y | Receives a 4-byte (32-bit) signed integer in big-endian format (network byte order) from the socket. | |
Y | Receives an 8-byte (64-bit) signed integer in big-endian format (network byte order) from the socket. | |
Y | Receives a 2-byte (16-bit) signed integer in little-endian format from the socket. | |
Y | Receives a 4-byte (32-bit) signed integer in little-endian format from the socket. | |
Y | Receives an 8-byte (64-bit) signed integer in little-endian format from the socket. | |
Y | Receives a 1-byte unsigned integer from the socket. | |
Y | Receives a 2-byte (16-bit) unsigned integer in big-endian format (network byte order) from the socket. | |
Y | Receives a 4-byte (32-bit) unsigned integer in big-endian format (network byte order) from the socket. | |
Y | Receives a 2-byte (16-bit) unsigned integer in little-endian format from the socket. | |
Y | Receives a 4-byte (32-bit) unsigned integer in little-endian format from the socket. | |
Y | Receives data on a socket and returns a binary object | |
Y | Retuns a hash representing the data in the HTTP header read | |
N | Returns the port number of the socket for INET sockets. | |
N | Ensures that a socket will be closed even if shared with other processes. | |
N | Closes the socket. | |
N | Returns the character encoding for the socket. | |
N | Sets the character encoding for the socket. | |
N | Returns the | |
N | Sets the | |
N | Returns the socket file descriptor number. | |
N |
Returns the name of the cipher for an encrypted connection. | |
N |
Returns the version string of the cipher for encrypted connections. | |
N |
Returns True if the connection is a secure TLS/SSL connection. | |
N |
Returns True if the socket is open. | |
N |
Sets the X.509 certificate to use for negotiating encrypted connections. | |
N |
Sets the private key to use for negotiating encrypted connections along with the X.509 certificate. | |
N | Returns a string code giving the result of verifying the remote certificate. | |
N | Sets a Queue object to receive socket events. |
Creates the socket object.
new Socket()
$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. |
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.
delete lvalue
delete $sock;
EVENT_CHANNEL_CLOSED, EVENT_DELETED
Creates a new Socket object, not based on the original.
Socket::copy()
$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. |
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::bind(port, [reuse_addr]
)
Socket::bind(host_and_port, [reuse_addr]
)
Socket::bind(filename, [reuse_addr]
)
# 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 |
---|---|---|
| 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. |
| 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. |
| 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. |
| 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 |
---|---|
| No argument was passed to the method. |
Accepts connections on a listening socket (see Socket::listen()).
Socket::accept()
$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. |
Accepts a remote connection and attempts to negotiate a TLS/SSL connection.
Socket::acceptSSL()
$new_sock = $sock.acceptSSL();
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 |
---|---|
|
An error occurred establishing the TLS/SSL connection. |
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.
Socket::connect(string:host_and_port, [timeout_ms]
)
Socket::connect(string:filename
)
$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"
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED
Table 4.408. Arguments for Socket::connect()
Argument | Type | Description |
---|---|---|
| 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. |
| 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 |
---|---|
| No argument was passed to the method. |
| An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc). |
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.
Socket::connectSSL(remote, [timeout_ms]
)
$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"
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 |
---|---|---|
| String | The remote socket, i.e. 'hostname:port', 'filename' (for UNIX domain sockets), etc. |
| 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 |
---|---|
|
missing remote socket |
| An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc). |
|
An error occurred establishing the TLS/SSL connection. |
Listens for new connections on a bound socket (see Socket::bind())
Socket::listen()
$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. |
Shuts down the SSL connection on a secure connection.
Socket::shutdownSSL()
$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 |
---|---|
|
An error occurred shutting down the TLS/SSL connection. |
Returns the name of the cipher for an encrypted connection.
Socket::getSSLCipherName()
$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. |
Returns the version string of the cipher for encrypted connections.
Socket::getSSLCipherVersion()
$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. |
Returns True if the connection is a secure TLS/SSL connection.
Socket::isSecure()
$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. |
Returns True if the socket is open.
Socket::isOpen()
$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. |
Sets the X.509 certificate to use for negotiating encrypted connections. Requires an SSLCertificate object as the only argument to the method.
Socket::setCertificate(certificate
)
$sock.setCertificate($cert);
Table 4.428. Arguments for Socket::setCertificate()
Argument |
Type |
Description |
---|---|---|
|
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 |
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.
Socket::setPrivateKey(private_key_object
)
$sock.setPrivateKey($pkey);
Table 4.430. Arguments for Socket::setPrivateKey()
Argument |
Type |
Description |
---|---|---|
|
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 |
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.
Socket::verifyPeerCertificate()
$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. |
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.
Socket::setEventQueue([queue]
)
$sock.setEventQueue($queue);
Table 4.435. Return Values for Socket::setEventQueue()
Return Type |
Description |
---|---|
n/a | This method does not return any value. |
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()).
Socket::isDataAvailable([timeout_ms]
)
$bool = $sock.isDataAvailable(0); # returns True if data is available now
Table 4.436. Arguments for Socket::isDataAvailable()
Argument | Type | Description |
---|---|---|
| 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. |
Returns True if all data has been written to the socket, takes an optional timeout. With a timeout of zero this method returns immediately.
Socket::isWriteFinished([timeout_ms]
)
$bool = $sock.isWriteFinished(0);
Table 4.438. Arguments for Socket::isWriteFinished()
Argument | Type | Description |
---|---|---|
| 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. |
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.
Socket::send(data
)
$sock.send($data);
EVENT_PACKET_SENT
Table 4.440. Arguments for Socket::send()
Argument | Type | Description |
---|---|---|
| String | Sends the string data over the socket without the trailing null ('\0') character. |
| 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 |
---|---|
| No argument was passed to the method. |
| The socket is not connected. |
Sends a 1-byte integer over the socket.
Socket::sendi1(integer
)
$sock.sendi1($val);
EVENT_PACKET_SENT
Table 4.443. Arguments for Socket::sendi1()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
Sends a 2-byte integer in big-endian format (network byte order) over the socket.
Socket::sendi2(integer
)
$sock.sendi2($val);
EVENT_PACKET_SENT
Table 4.446. Arguments for Socket::sendi2()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
Sends a 4-byte integer in big-endian format (network byte order) over the socket.
Socket::sendi4(integer
)
$sock.sendi4($val);
EVENT_PACKET_SENT
Table 4.449. Arguments for Socket::sendi4()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
Sends an 8-byte (64-bit) integer in big-endian format (network byte order) over the socket.
Socket::sendi8(integer
)
$sock.sendi8($val);
EVENT_PACKET_SENT
Table 4.452. Arguments for Socket::sendi8()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
Sends a 2-byte integer in little-endian format over the socket.
Socket::sendi2LSB(integer
)
$sock.sendi2LSB($val);
EVENT_PACKET_SENT
Table 4.455. Arguments for Socket::sendi2LSB()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
Sends a 4-byte integer in little-endian format over the socket.
Socket::sendi4LSB(integer
)
$sock.sendi4LSB($val);
EVENT_PACKET_SENT
Table 4.458. Arguments for Socket::sendi4LSB()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
Sends an 8-byte (64-bit) integer in little-endian format over the socket.
Socket::sendi8LSB(integer
)
$sock.sendi8LSB($val);
EVENT_PACKET_SENT
Table 4.461. Arguments for Socket::sendi8LSB()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
Creates a properly-formatted HTTP message and sends it over the Socket.
Socket::sendHTTPMessage(string:method, string:path, string:http_version, hash:headers, [body]
)
$sock.sendHTTPMessage("POST", "/RPC2", "1.1", ("Content-Type" : "text/xml"), $xml);
EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE
Table 4.464. Arguments for Socket::sendHTTPMessage()
Argument | Type | Description |
---|---|---|
| String | The HTTP method name to send (i.e. POST, HEAD, etc) |
| String | The path component of the URL. |
| String | The HTTP protocol version (1.0 or 1.1). |
| Hash | A hash of additional headers to send (key-value pairs). |
| String | If present, the body to be sent with the message (if present, the Content-Length header will be automatically set). |
| 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 |
---|---|
| One or more of the required arguments is missing. |
| The socket is not connected. |
| Send failed. |
Creates a properly-formatted HTTP response message and sends it over the Socket.
Socket::sendHTTPResponse(status_code, string:description, string:http_version, hash:headers, [body]
)
$sock.sendHTTPResponse(200, "OK", "1.1", ("Connection":"Keep-Alive"));
EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE
Table 4.467. Arguments for Socket::sendHTTPMessage()
Argument | Type | Description |
---|---|---|
| Integer | The HTTP status code to send (i.e. 200, 404, etc) |
| String | The descriptive text for the status code. |
| String | The HTTP protocol version (1.0 or 1.1). |
| Hash | A hash of additional headers to send (key-value pairs). |
| String | If present, the body to be sent with the message (if present, the Content-Length header will be automatically set). |
| 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 |
---|---|
| One or more of the required arguments is missing. |
| The socket is not connected. |
| Send failed. |
Receives data from the socket and returns a string.
Socket::recv(size, [timeout_ms]
)
$data = $sock.recv(-1); # read all data available
EVENT_PACKET_READ
Table 4.470. Arguments for Socket::recv()
Argument | Type | Description |
---|---|---|
| Integer | The amount of data to read in bytes. To read until the remote closes the connection, use -1. |
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives data from the socket and returns a binary object.
Socket::recvBinary(size, [timeout_ms]
)
$bin = $sock.recvBinary(-1); # read all data available
EVENT_PACKET_READ
Table 4.473. Arguments for Socket::recvBinary()
Argument | Type | Description |
---|---|---|
| Integer | The amount of data to read in bytes. To read until the remote closes the connection, use -1. |
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 1-byte signed integer from the socket.
Socket::recvi1([timeout_ms]
)
$int = $sock.recvi1();
EVENT_PACKET_READ
Table 4.476. Arguments for Socket::recvi1()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 2-byte signed integer in big-endian format (network byte order) from the socket.
Socket::recvi2([timeout_ms]
)
$int = $sock.recvi2();
EVENT_PACKET_READ
Table 4.479. Arguments for Socket::recvi2()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 4-byte signed integer in big-endian format (network byte order) from the socket.
Socket::recvi4([timeout_ms]
)
$int = $sock.recvi4();
EVENT_PACKET_READ
Table 4.482. Arguments for Socket::recvi4()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives an 8-byte (64-bit) signed integer in big-endian format (network byte order) from the socket.
Socket::recvi8([timeout_ms]
)
$int = $sock.recvi8();
EVENT_PACKET_READ
Table 4.485. Arguments for Socket::recvi8()
Argument | Type | Description |
---|---|---|
| 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. |
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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 2-byte signed integer in little-endian format from the socket.
Socket::recvi2LSB([timeout_ms]
)
$int = $sock.recvi2LSB();
EVENT_PACKET_READ
Table 4.488. Arguments for Socket::recvi2LSB()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 4-byte signed integer in little-endian format from the socket.
Socket::recvi4LSB([timeout_ms]
)
$int = $sock.recvi4LSB(1250ms); # timeout in 1.25 seconds
EVENT_PACKET_READ
Table 4.491. Arguments for Socket::recvi4LSB()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives an 8-byte (64-bit) signed integer in little-endian format from the socket.
Socket::recvi8LSB([timeout_ms]
)
$int = $sock.recvi8LSB();
EVENT_PACKET_READ
Table 4.494. Arguments for Socket::recvi8LSB()
Argument | Type | Description |
---|---|---|
| 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. |
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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 1-byte unsigned integer from the socket.
Socket::recvu1([timeout_ms]
)
$int = $sock.recvu1();
EVENT_PACKET_READ
Table 4.497. Arguments for Socket::recvu1()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 2-byte unsigned integer in big-endian format (network byte order) from the socket.
Socket::recvu2([timeout_ms]
)
$int = $sock.recvu2();
EVENT_PACKET_READ
Table 4.500. Arguments for Socket::recvu2()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 4-byte unsigned integer in big-endian format (network byte order) from the socket.
Socket::recvu4([timeout_ms]
)
$int = $sock.recvu4();
EVENT_PACKET_READ
Table 4.503. Arguments for Socket::recvu4()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 2-byte unsigned integer in little-endian format from the socket.
Socket::recvu2LSB([timeout_ms]
)
$int = $sock.recvu2LSB();
EVENT_PACKET_READ
Table 4.506. Arguments for Socket::recvu2LSB()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 4-byte unsigned integer in little-endian format from the socket.
Socket::recvu4LSB([timeout_ms]
)
$int = $sock.recvu4LSB();
EVENT_PACKET_READ
Table 4.509. Arguments for Socket::recvu4LSB()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
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 | |
---|---|---|
| A string giving the HTTP version set in the header | |
| An integer giving the status code; this key is only set in HTTP responses | |
| If present in an HTTP response, this key will be set to the message after the status code | |
| A string giving the HTTP method (i.e. | |
| A string giving the path in a request without any decoding; use decode_url() to decode if necessary. |
Socket::readHTTPHeader([timeout_ms]
)
$hash = $sock.readHTTPHeader();
EVENT_PACKET_READ, EVENT_HTTP_MESSAGE_RECEIVED
Table 4.513. Arguments for Socket::readHTTPHeader()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Returns the port number of the socket for INET sockets.
Socket::getPort()
$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. |
Ensures that a socket will be closed even if the file descriptor is shared with other processes (for example, after a call to fork()).
Socket::shutdown()
$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. |
Closes an open socket. Also deletes the UNIX domain socket file if it was created by a call to Socket::bind()
Socket::close()
$sock.close();
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. |
Returns the character encoding for the socket.
Socket::getCharset()
$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. |
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.
Socket::setCharset(string:encoding
)
$sock.setCharset("ISO-8859-1");
Table 4.524. Arguments for Socket::setCharset()
Argument | Type | Description |
---|---|---|
| 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. |
Returns the TCP_NODELAY
setting for the socket. See also Socket::setNoDelay().
Socket::getNoDelay()
$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 |
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().
Socket::setNoDelay(boolean
)
$sock.setNoDelay(True);
Table 4.528. Arguments for Socket::setNoDelay()
Argument | Type | Description |
---|---|---|
| boolean | The |
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(). |
Returns the file descriptor number associated with the socket.
Socket::getSocket()
$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. |