| Qore Programming Language Reference Manual 2.2.0

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | List of all members
Qore::Socket Class Reference

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

`#include <QC_Socket.dox.h>`

Inheritance diagram for Qore::Socket:
[legend]

## Public Member Functions
Socket | accept ()
| Accepts connections on a listening socket.
*Socket | accept (timeout timeout_ms)
| Accepts connections on a listening socket (see Socket::listen()) accepting a timeout value with a millisecond resolution.
| acceptAllCertificates (bool accept_all=True)
| with peer verification enabled, all certificates are accepted regardless of the validity of the Certificate Authority
Socket | acceptSSL ()
| Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection.
*Socket | acceptSSL (timeout timeout_ms)
| Accepts connections on a listening socket and attempts to negotiate a TLS/SSL connection accepting a timeout value with a millisecond resolution.
int | bind (string str, softbool reuseaddr=False)
| Opens and binds the socket to a port, interface and port (if the bind_to string has a format "host:port"), or UNIX domain socket file.
int | bind (int port, softbool reuseaddr=False)
| Opens and binds the socket to an INET port on all interfaces.
nothing | bindINET (*string iface, *softstring service, softbool reuseaddr=False, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
| Opens and binds the socket to the given IPv4 or IPv6 interface (or if no interface is given, then to all interfaces on the local system) and port (the port number will be derived from the service name if a numeric port number is not given)
nothing | bindUNIX (string path, softint socktype=SOCK_STREAM, softint protocol=0)
| Opens and binds the socket to the given UNIX domain socket file as given by the filename argument. If any errors occur, an exception is thrown.
bool | captureRemoteCertificates (bool set=True)
| Sets the flag for capturing remote X.509 certificates; by default no capture of remote certificates is performed.
| clearStats ()
| Clears performance statistics.
nothing | clearWarningQueue ()
| Removes any warning Queue object from the Socket.
int | close ()
| Closes an open socket.
nothing | connect (string target, timeout timeout_ms=-1)
| Connects to a remote port (if the string has a format "host:port") or UNIX domain socket file.
nothing | connectINET (string host, softstring service, timeout timeout_ms=-1, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
| Connects to the given host and port with an optional timeout value with a millisecond resolution.
nothing | connectINETSSL (string host, softstring service, timeout timeout_ms=-1, softint family=AF_UNSPEC, softint socktype=SOCK_STREAM, softint protocol=0)
| Connects to the given host and port and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution.
nothing | connectSSL (string target, timeout timeout_ms=-1)
| Connects to a remote socket and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution.
nothing | connectUNIX (string path, softint socktype=SOCK_STREAM, softint protocol=0)
| Connects to a UNIX domain socket file.
nothing | connectUNIXSSL (string path, softint socktype=SOCK_STREAM, softint protocol=0)
| Connects to the given UNIX domain socket file and attempts to establish a TLS/SSL connection.
| constructor ()
| Creates the socket object.
| copy ()
| Creates a new Socket object, not based on the source being copied.
| destructor ()
| Deletes the object.
bool | getAcceptAllCertificates ()
| returns the current value of the "accept all certificates" flag
string | getCharset ()
| Returns the character encoding for the socket.
int | getConnectionId ()
| Returns an integer connection ID that is incremented every time the socket is disconnected.
string | getEncoding ()
| Returns the character encoding for the socket.
bool | getNoDelay ()
| Returns the `TCP_NODELAY` setting for the socket.
hash< auto > | getPeerInfo (bool host_lookup=True)
| Returns a hash of information about the remote end for connected sockets.
int | getPort ()
| Returns the port number of the socket for INET sockets.
int | getRecvTimeout ()
| Returns the receive timeout socket option value as an integer in milliseconds.
*SSLCertificate | getRemoteCertificate ()
| Returns any remote certificate captured or NOTHING if there is none.
*string | getSSLCipherName ()
| Returns the name of the cipher for an encrypted connection or NOTHING if a secure connection has not been established.
*string | getSSLCipherVersion ()
| Returns the version string of the cipher for an encrypted connection or NOTHING if a secure connection has not been established.
int | getSendTimeout ()
| Returns the send timeout socket option value as an integer in milliseconds.
int | getSocket ()
| Returns the socket file descriptor number.
hash< auto > | getSocketInfo (bool host_lookup=True)
| Returns information about the local socket as a hash.
int | getSslVerifyMode ()
| returns the current SSL verification mode
hash< auto > | getUsageInfo ()
| Returns performance statistics for the socket.
bool | isDataAvailable (timeout timeout_ms=0)
| Returns True or False depending on whether there is data to be read on the socket.
bool | isOpen ()
| Returns True if the socket is open.
bool | isSecure ()
| Returns True if the connection is a secure TLS/SSL connection.
bool | isWriteFinished (timeout timeout_ms=0)
| Returns True or False depending on whether all the data has been written to the socket.
int | listen (int backlog=20)
| Listens for connections on a bound socket; sets the socket in a listening state.
bool | pendingHttpChunkedBody ()
| returns True if the socket is still connected, and a HTTP header was read indicating chunked transfer encoding, but no chunked body has been read yet
hash< auto > | readHTTPChunk (timeout timeout_ms=-1)
| Reads in a single HTTP message chunk.
hash< auto > | readHTTPChunkedBody (timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a string in the `"body"` key of a hash (including footers received)
hash< auto > | readHTTPChunkedBodyBinary (timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a binary object in the `"body"` key of a hash (including footers received)
| readHTTPChunkedBodyBinaryWithCallback (code rcb, timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a string in the `"body"` key of a hash (including footers received)
hash< auto > | readHTTPChunkedBodyToOutputStream (Qore::OutputStream os, timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding, writes it in an OutputStream and returns any footers received.
| readHTTPChunkedBodyWithCallback (code rcb, timeout timeout_ms=-1)
| Reads in an HTTP message body sent in chunked transfer encoding and returns it with any footers received as a string in the `"body"` key of a hash (including footers received)
hash< auto > | readHTTPHeader (timeout timeout_ms=-1, *reference< hash< auto > > info)
| Retuns a hash representing the data in the HTTP header read, or, if the data cannot be parsed as an HTTP header, then an exception is thrown, and the data read is returned as a string in the `arg` key of the exception hash.
string | readHTTPHeaderString (timeout timeout_ms=-1)
| Retuns a string representing the data in the HTTP header read (reads until `"\r\n\r\n"`)
hash< SseMessageInfo > | readServerSentEvent (*string content_encoding, timeout timeout_ms=-1)
| Read a server sent event message.
hash< SseMessageInfo > | readServerSentEvent (timeout timeout_ms=-1)
| Read a server sent event message.
string | recv (softint size=0, timeout timeout_ms=-1)
| Receives data from the socket and returns a string tagged with the Socket's character encoding.
binary | recvBinary (softint size=0, timeout timeout_ms=-1)
| Receives data from the socket and returns a binary object.
nothing | recvToOutputStream (Qore::OutputStream os, softint size=-1, timeout timeout_ms=-1)
| Receives data from the socket and writes the bytes to an OutputStream.
int | recvi1 (timeout timeout_ms=-1)
| Receives a 1-byte signed integer from the socket.
int | recvi2 (timeout timeout_ms=-1)
| Receives a 2-byte (16-bit) signed integer in big-endian format (network byte order) from the socket.
int | recvi2LSB (timeout timeout_ms=-1)
| Receives a 2-byte (16-bit) signed integer in little-endian format from the socket.
int | recvi4 (timeout timeout_ms=-1)
| Receives a 4-byte (32-bit) signed integer in big-endian format (network byte order) from the socket.
int | recvi4LSB (timeout timeout_ms=-1)
| Receives a 4-byte (32-bit) signed integer in little-endian format from the socket.
int | recvi8 (timeout timeout_ms=-1)
| Receives an 8-byte (64-bit) signed integer in big-endian format (network byte order) from the socket.
int | recvi8LSB (timeout timeout_ms=-1)
| Receives an 8-byte (64-bit) signed integer in little-endian format from the socket.
int | recvu1 (timeout timeout_ms=-1)
| Receives a 1-byte unsigned integer from the socket.
int | recvu2 (timeout timeout_ms=-1)
| Receives a 2-byte (16-bit) unsigned integer in big-endian format (network byte order) from the socket.
int | recvu2LSB (timeout timeout_ms=-1)
| Receives a 2-byte (16-bit) unsigned integer in little-endian format from the socket.
int | recvu4 (timeout timeout_ms=-1)
| Receives a 4-byte (32-bit) unsigned integer in big-endian format (network byte order) from the socket.
int | recvu4LSB (timeout timeout_ms=-1)
| Receives a 4-byte (32-bit) unsigned integer in little-endian format from the socket.
int | send (binary bin, timeout timeout_ms=-1)
| Sends binary data over the socket; if any errors occur, an exception is thrown.
int | send (string str, timeout timeout_ms=-1)
| Sends string data over the socket; string data is converted to the socket's encoding if necessary; if any errors occur, an exception is thrown.
nothing | send2 (binary bin, timeout timeout_ms=-1)
| Sends binary data over the socket; if any errors occur, an exception is thrown.
nothing | send2 (string str, timeout timeout_ms=-1)
| Sends string data over the socket; string data is converted to the socket's encoding if necessary; if any errors occur, an exception is thrown.
int | sendBinary (string str, timeout timeout_ms=-1)
| Sends string data over the socket without converting the string to the socket's encoding, but instead is sent exactly as-is; if any errors occur, an exception is thrown.
int | sendBinary (binary bin, timeout timeout_ms=-1)
| Sends binary data over the socket; if any errors occur, an exception is thrown.
nothing | sendBinary2 (string str, timeout timeout_ms=-1)
| Sends string data over the socket without converting the string to the socket's encoding, but instead is sent exactly as-is; if any errors occur, an exception is thrown.
nothing | sendBinary2 (binary bin, timeout timeout_ms=-1)
| Sends binary data over the socket; if any errors occur, an exception is thrown.
nothing | sendFromInputStream (Qore::InputStream input_stream, softint size=-1, timeout timeout_ms=-1)
| Reads data from an InputStream and sends the bytes over the socket.
nothing | sendHTTPChunkedBodyFromInputStream (Qore::InputStream input_stream, int max_chunk_size=4096, timeout timeout_ms=-1, *code tcb)
| Sends an HTTP message body in chunked transfer encoding.
nothing | sendHTTPChunkedBodyTrailer (*hash< auto > trailer, timeout timeout_ms=-1)
| Sends the trialer of an HTTP message body in chunked transfer encoding.
nothing | sendHTTPMessage (string method, string path, string http_version, hash< auto > headers, string body, *reference< hash > info, timeout timeout_ms=-1)
| Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body.
nothing | sendHTTPMessage (string method, string path, string http_version, hash< auto > headers, *binary body, *reference< hash< auto > > info, timeout timeout_ms=-1)
| Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body.
nothing | sendHTTPMessageWithCallback (code scb, string method, string path, string http_version, hash< auto > headers, *reference< hash< auto > > info, timeout timeout_ms=-1)
| Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body.
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, string body, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and an optional message body.
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, string body, *reference< hash< auto > > info, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and an optional message body.
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, *binary body, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and a message body as literal binary data.
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, *binary body, *reference< hash< auto > > info, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and a message body as literal binary data.
nothing | sendHTTPResponse (softint status_code, string status_desc, string http_version, hash< auto > headers, Qore::InputStream input_stream, int max_chunk_size=4096, *reference< hash< auto > > info, timeout timeout_ms=-1, *code tcb)
| Sends an HTTP response with user-defined headers and a message body from an input stream in chunked transfer encoding.
nothing | sendHTTPResponseWithCallback (code scb, softint status_code, string status_desc, string http_version, hash< auto > headers, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and a message body to send with chunked transfer encoding provided by a callback.
nothing | sendHTTPResponseWithCallback (code scb, softint status_code, string status_desc, string http_version, hash< auto > headers, *reference< hash< auto > > info, timeout timeout_ms=-1)
| Sends an HTTP response with user-defined headers given as a hash and a message body to send with chunked transfer encoding provided by a callback.
int | sendi1 (softint i=0, timeout timeout_ms=-1)
| Sends a 1-byte integer over the socket.
int | sendi2 (softint i=0, timeout timeout_ms=-1)
| Sends a 2-byte (16-bit) integer in big-endian format (network byte order) over the socket.
int | sendi2LSB (softint i=0, timeout timeout_ms=-1)
| Sends a 2-byte (16-bit) integer in little-endian format over the socket.
int | sendi4 (softint i=0, timeout timeout_ms=-1)
| Sends a 4-byte (32-bit) integer in big-endian format (network byte order) over the socket.
int | sendi4LSB (softint i=0, timeout timeout_ms=-1)
| Sends a 4-byte (32-bit) integer in little-endian format over the socket.
int | sendi8 (softint i=0, timeout timeout_ms=-1)
| Sends an 8-byte (64-bit) integer in big-endian format (network byte order) over the socket.
int | sendi8LSB (softint i=0, timeout timeout_ms=-1)
| Sends an 8-byte (64-bit) integer in little-endian format over the socket.
nothing | setCertificate (SSLCertificate cert)
| Sets the X.509 certificate to use for negotiating encrypted connections.
nothing | setCertificate (string cert_pem)
| Sets the X.509 certificate to use for negotiating encrypted connections from the PEM-encoded string representing the X.509 certificate.
nothing | setCertificate (binary cert_der)
| Sets the X.509 certificate to use for negotiating encrypted connections from the DER-encoded binary object representing the X.509 certificate.
nothing | setCertificateAndPrivateKey (SSLCertificate cert, SSLPrivateKey key)
| Sets the X.509 certificate and private key in one atomic operation to use for negotiating encrypted connections.
nothing | setCharset (string encoding)
| Sets the character encoding for the socket.
nothing | setEncoding (string encoding)
| Sets the character encoding for the socket.
nothing | setEventQueue ()
| Removes any Queue object from the Socket object so that socket events are no longer added to the Queue.
nothing | setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
| Sets a Queue object to receive socket events.
int | setNoDelay (bool nd=True)
| Sets the boolean `TCP_NODELAY` setting for the socket.
nothing | setPrivateKey (SSLPrivateKey key)
| Sets the private key to use for negotiating encrypted connections along with the X.509 certificate.
nothing | setPrivateKey (string key_pem, *string pass)
| Sets the private key to use for negotiating encrypted connections along with the X.509 certificate from a PEM-encoded string representing the private key and an optional password.
nothing | setPrivateKey (binary key_der)
| Sets the private key to use for negotiating encrypted connections along with the X.509 certificate from a DER-encoded binary object representing the private key.
int | setRecvTimeout (timeout timeout_ms)
| sets the receive timeout as a socket option
int | setSendTimeout (timeout timeout_ms)
| sets the send timeout as a socket option
| setSslVerifyMode (int mode)
| sets the SSL verification mode
nothing | setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
| Sets a Queue object to receive socket warnings.
int | shutdown ()
| Ensures that a socket will be closed even if the file descriptor is shared with other processes (for example, after a call to fork())
nothing | shutdownSSL ()
| Shuts down the SSL connection on a secure connection.
AbstractPollOperation | startPollAccept ()
| Returns an AbstractPollOperation object to accept a new connection.
AbstractPollOperation | startPollConnect (string target)
| Returns an AbstractPollOperation object to poll the socket for a standard connection.
AbstractPollOperation | startPollConnectSsl (string target)
| Returns an AbstractPollOperation object to poll the socket for an SSL connection.
AbstractPollOperation | startPollReadHttpHeader ()
| Returns an AbstractPollOperation object to read an HTTP header without blocking.
AbstractPollOperation | startPollRecvBinary (int size)
| Returns an AbstractPollOperation object to read data in non-blocking mode.
AbstractPollOperation | startPollRecvData ()
| Returns an AbstractPollOperation object for receiving data in non-blocking mode.
AbstractPollOperation | startPollRecvString (int size)
| Returns an AbstractPollOperation object to read data in non-blocking mode.
AbstractPollOperation | startPollRecvUntilBytesBinary (string pattern)
| Returns an AbstractPollOperation object to read data in non-blocking mode.
AbstractPollOperation | startPollRecvUntilBytesString (string pattern)
| Returns an AbstractPollOperation object to read data in non-blocking mode.
AbstractPollOperation | startPollSend (string data)
| Returns an AbstractPollOperation object to send data in non-blocking mode.
AbstractPollOperation | startPollSend (binary data)
| Returns an AbstractPollOperation object to send data in non-blocking mode.
AbstractPollOperation | startPollUpgradeClientToSSL ()
| Returns an AbstractPollOperation object to upgrade a connected client socket to SSL.
AbstractPollOperation | startPollUpgradeServerToSSL ()
| Returns an AbstractPollOperation object to upgrade a connected server socket to SSL.
nothing | upgradeClientToSSL (timeout timeout_ms=-1)
| Upgrades a client socket connection to a TLS/SSL connection.
nothing | upgradeServerToSSL (timeout timeout_ms=-1)
| Upgrades a server socket connection to a TLS/SSL connection.
*string | verifyPeerCertificate ()
| Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not currently established.
Public Member Functions inherited from Qore::AbstractPollableIoObjectBase
| constructor ()
| Throws an exception; this class is not usable by Qore classes.
int | getPollableDescriptor ()
| Returns a pollable file / socket / I/O descriptor.
Public Member Functions inherited from Qore::AbstractPollableIoObject
abstract int | getPollableDescriptor ()
| Returns a pollable file / socket / I/O descriptor.

## Static Public Member Functions
static hash< SseMessageInfo > | parseServerSentEvent (string str)
| Parse the given string as a Server Sent Event (SSE) string.
static list< hash< SocketPollInfo > > | poll (list< hash< SocketPollInfo > > items, timeout timeout_ms)
| polls multiple sockets and returns all sockets with events

## Detailed Description

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

Restrictions:
  Qore::PO_NO_NETWORK

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

Non-blocking socket I/O can be performed by appending a timeout value in milliseconds all Socket methods performing I/O operations, 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:

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

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

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

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

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

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

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

Socket Events

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

Socket Information Hash

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

## Member Function Documentation

## ◆ accept() [1/2]

Socket Qore::Socket::accept | ( |  | ) |

Accepts connections on a listening socket.

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

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

Example:
  Socket new_socket = sock.accept();

Returns
  a new Socket object is returned for the new connection

Exceptions

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

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

## ◆ accept() [2/2]

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

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

If any errors occur, an exception is thrown.

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

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

Parameters

  timeout_ms | If a timeout value is passed and the connection takes longer to establish than the timeout, then NOTHING is returned.Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ acceptAllCertificates()

Qore::Socket::acceptAllCertificates | ( | bool | accept_all = True | ) |

with peer verification enabled, all certificates are accepted regardless of the validity of the Certificate Authority

Example:
  # require a certificate from the peer, but accept all certificates, even self-signed ones
  sock.setSslVerifyMode(SSL_VERIFY_PEER|SSL_VERIFY_FAIL_IF_NO_PEER_CERT);
  sock.acceptAllCertificates();

Parameters

  accept_all | if True, then self-signed certificates are accepted, if False, then they are not

See also
  - Socket::getAcceptAllCertificates()
  - Socket::setSslVerifyMode()
  - Socket::getSslVerifyMode()

Since
  Qore 0.8.13

## ◆ acceptSSL() [1/2]

Socket Qore::Socket::acceptSSL | ( |  | ) |

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

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

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

Example:
  Socket new_socket = sock.acceptSSL();

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

Exceptions

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

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

## ◆ acceptSSL() [2/2]

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

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

If any errors occur, an exception is thrown.

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

Example:
  *Socket new_socket = sock.acceptSSL(30s);

Parameters

  timeout_ms | If a timeout value is passed and the connection takes longer to establish than the timeout, then NOTHING is returned. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ bind() [1/2]

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

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

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

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

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

Parameters

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

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

## ◆ bind() [2/2]

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

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

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

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

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

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

Example:
  # bind to a UNIX socket on the local system and reuse the address, check return code
  if (sock.bind("/tmp/my-socket", True))
  throw "BIND-ERROR", strerror();

Parameters

  str | If a colon appears in the string, the string will be assumed to be a `"bind_address:port"` specification, and the port on the named IP address will be bound, otherwise, if the string contains no colon, the socket will be bound to a UNIX domain socket file on the local filesystem with the given name. Note that a hostname or address in square brackets (ex: `"[localhost]"`) will be looked up and bound as an IPv6 address; additionally, the method recognizes ipv6 addresses by embedded colons (:) in the address string (if surrounded by square brackets) and binds them as such.
  reuseaddr | If this optional argument evaluates to True, the `SO_REUSEADDR` option will be set on the socket, which will allow the socket to be bound to a port that is not yet closed (for example, in a `TIME_WAIT` state); note that this only applies to IPv4 (AF_INET) and IPv6 (AF_INET6) sockets; this option is ignored for UNIX (AF_UNIX) sockets.

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

Note
  UNIX domain sockets are not available on native Windows ports

## ◆ bindINET()

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

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

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

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

If any errors occur, an exception is thrown.

Examples:
  # bind to port 80 on all interfaces on the local system and reuse the address
  sock.bindINET(NOTHING, 80, True);
  # bind to interface 192.168.2.23 port 8080 and do not reuse the address
  sock.bindINET("192.168.2.23", 8080);
  # bind to localhost port 8080 with ipv6 and do not reuse the address
  sock.bindINET("localhost", 8080, False, AF_INET6);
  # bind to ipv6 host address fe80::21c:42ff:fe00:8, port 1001, reuse the address
  sock.bindINET("fe80::21c:42ff:fe00:8", 1001, True);

Parameters

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

Exceptions

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

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

## ◆ bindUNIX()

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

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

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

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

Parameters

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

Exceptions

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

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

Note
  UNIX domain sockets are not available on native Windows ports

## ◆ captureRemoteCertificates()

bool Qore::Socket::captureRemoteCertificates | ( | bool | set = True | ) |

Sets the flag for capturing remote X.509 certificates; by default no capture of remote certificates is performed.

Example:
  bool b = sock.captureRemoteCertificates();

Parameters

  set | the flag for capturing remote X.509 certificates; by default no capture of remote certificates is performed

Returns
  the old value of the flag

See also
  getRemoteCertificate()

Since
  Qore 0.9.3

## ◆ clearStats()

Qore::Socket::clearStats | ( |  | ) |

Clears performance statistics.

Example:
  sock.clearStats();

Since
  Qore 0.8.9

See also
  Socket::getUsageInfo()

## ◆ clearWarningQueue()

nothing Qore::Socket::clearWarningQueue | ( |  | ) |

Removes any warning Queue object from the Socket.

Example:
  sock.clearWarningQueue();

See also
  Socket::setWarningQueue()

Since
  Qore 0.8.9

## ◆ close()

int Qore::Socket::close | ( |  | ) |

Closes an open socket.

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

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

Events:
  EVENT_CHANNEL_CLOSED

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

## ◆ connect()

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

Connects to a remote port (if the string has a format "host:port") or UNIX domain socket file.

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

Examples:
  # connect to ipv4 adress 192.168.1.45 port 8080 with a 30 second timeout
  sock.connect("192.168.1.45:8080", 30s);
  # connect to ipv6 adress 2001:0db8:85a3:0000:0000:8a2e:0370:7334 port 80 with a 10 second timeout
  sock.connect("[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80", 10s);
  # connect to localhost using ipv6 (::1) port 80 with a 10 second timeout
  sock.connect("[localhost]:80", 15s);
  # connect to UNIX domain socket file "/tmp/socket"
  sock.connect("/tmp/socket");

Events:
  EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED

Parameters

  target | The target address interpreted with the following rules: If a colon appears in the string, the string will be assumed to be a `"hostname:port"` specification to connect to; where `"port"` can also be a service name (ex: `"example.com:https"`) If the string contains no colon, the socket will try to connect to a UNIX domain socket file on the local filesystem with the given name. Enclose ipv6 addresses in square brackets (ex: `"[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80"`, will connect to port 80 on the given ipv6 address); also if a hostname is enclosed in square brackets, it will be resolved as an IPv6 address (ex: `"[localhost]:80"` will connect to port `80` on `::1`, assuming `"localhost"` can be resolved to the IPv6 loopback address on the system).
  timeout_ms | If a timeout value is passed and the connection takes longer to establish than the timeout, a `"SOCKET-CONNECT-ERROR"` exception is thrown. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

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

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

## ◆ connectINET()

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

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

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

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

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

Events:
  EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED

Parameters

  host | The host name or IP address to connect to
  service | The service name (ex: `"http"` or port number (given as or converted to a string) to connect to
  timeout_ms | If a timeout value is passed and the connection takes longer to establish than the timeout, a `"SOCKET-CONNECT-ERROR"` exception is thrown. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)
  family | The address family to use to connect to the remote socket; see Network Address Family Constants
  socktype | The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets
  protocol | The protocol number for the socket (if not sure leave this 0)

Exceptions

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

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

## ◆ connectINETSSL()

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

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

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

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

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

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

Parameters

  host | The host name or IP address to connect to
  service | The service name (ex: `"http"` or port number (given as or converted to a string) to connect to
  timeout_ms | If a timeout value is passed and the connection takes longer to establish than the timeout, a `"SOCKET-CONNECT-ERROR"` exception is thrown. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)
  family | The address family to use to connect to the remote socket; see Network Address Family Constants
  socktype | The type of socket; see Socket Type Constants; typically SOCK_STREAM for TCP sockets
  protocol | The protocol number for the socket (if not sure leave this 0)

Exceptions

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

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

## ◆ connectSSL()

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

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

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

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

Examples:
  # connect to ipv4 adress 192.168.1.45 port 8080 with a 30 second timeout
  sock.connectSSL("192.168.1.45:8080", 30s);
  # connect to ipv6 adress 2001:0db8:85a3:0000:0000:8a2e:0370:7334 port 80 with a 10 second timeout
  sock.connectSSL("[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80", 10s);
  # connect to localhost using ipv6 (::1) port 80 with a 10 second timeout
  sock.connectSSL("[localhost]:80", 15s);
  # connect to UNIX domain socket file "/tmp/socket"
  sock.connectSSL("/tmp/socket");

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

Parameters

  target | The target address interpreted with the following rules: If a colon appears in the string, the string will be assumed to be a `"hostname:port"` specification to connect to; where `"port"` can also be a service name (ex: `"example.com:https"`) If the string contains no colon, the socket will try to connect to a UNIX domain socket file on the local filesystem with the given name. Enclose ipv6 addresses in square brackets (ex: `"[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:80"`, will connect to port 80 on the given ipv6 address); also if a hostname is enclosed in square brackets, it will be resolved as an ipv6 address (ex: `"[localhost]:80"` will connect to port `80` on `::1`, assuming `"localhost"` can be resolved to the ipv6 loopback address on the system).
  timeout_ms | if a timeout value is passed and the connection takes longer to establish than the timeout, an exception is thrown. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

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

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

## ◆ connectUNIX()

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

Connects to a UNIX domain socket file.

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

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

Events:
  EVENT_CONNECTING, EVENT_CONNECTED

Parameters

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

Exceptions

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

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

Note
  UNIX domain sockets are not available on native Windows ports

## ◆ connectUNIXSSL()

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

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

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

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

Events:
  EVENT_CONNECTING, EVENT_CONNECTED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED

Parameters

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

Exceptions

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

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

Note
  UNIX domain sockets are not available on native Windows ports

## ◆ constructor()

Qore::Socket::constructor | ( |  | ) |

Creates the socket object.

Example:
  Socket sock();

## ◆ copy()

Qore::Socket::copy | ( |  | ) |

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

Example:
  Socket newsock = sock.copy();

## ◆ getAcceptAllCertificates()

bool Qore::Socket::getAcceptAllCertificates | ( |  | ) |

returns the current value of the "accept all certificates" flag

Code Flags:
  CONSTANT

Example:
  bool b = sock.getAcceptAllCertificates();

Returns
  the current value of the "accept all certificates" flag; if True, then self-signed certificates are accepted, if False, then they are not

See also
  - Socket::acceptAllCertificates()
  - Socket::setSslVerifyMode()
  - Socket::getSslVerifyMode()

Since
  Qore 0.8.13

## ◆ getCharset()

string Qore::Socket::getCharset | ( |  | ) |

Returns the character encoding for the socket.

Code Flags:
  CONSTANT

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

Returns
  the character encoding for the socket

## ◆ getConnectionId()

int Qore::Socket::getConnectionId | ( |  | ) |

Returns an integer connection ID that is incremented every time the socket is disconnected.

Code Flags:
  CONSTANT

Example:
  int conn_id = sock.getConnectionId();

Returns
  an integer connection ID that is incremented every time the socket is disconnected

This number can be used to identify new connections

Since
  Qore 0.9.3.1

## ◆ getEncoding()

string Qore::Socket::getEncoding | ( |  | ) |

Returns the character encoding for the socket.

Code Flags:
  CONSTANT

Returns
  the character encoding for the socket

## ◆ getNoDelay()

bool Qore::Socket::getNoDelay | ( |  | ) |

Returns the `TCP_NODELAY` setting for the socket.

Code Flags:
  CONSTANT

Example:
  bool b = sock.getNoDelay();

Returns
  the `TCP_NODELAY` setting for the socket

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

## ◆ getPeerInfo()

hash< auto > Qore::Socket::getPeerInfo | ( | bool | host_lookup = True | ) |

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

If the socket is not connected, an exception is thrown

Example:
  hash<auto> h = sock.getPeerInfo();

Parameters

  host_lookup | do a lookup of the hostname; if this is False then `"hostname"` and `"hostname_desc"` are not present in the response hash

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

Exceptions

  SOCKET-NOT-OPEN | The socket is not open
  SOCKET-GETPEERINFO-ERROR | error in getpeername()

Since
  Qore 0.8.8 added the host_lookup parameter

## ◆ getPort()

int Qore::Socket::getPort | ( |  | ) |

Returns the port number of the socket for INET sockets.

Code Flags:
  CONSTANT

Example:
  int port = sock.getPort();

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

## ◆ getRecvTimeout()

int Qore::Socket::getRecvTimeout | ( |  | ) |

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

Code Flags:
  CONSTANT

Example:
  int to = sock.getRecvTimeout();

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

## ◆ getRemoteCertificate()

*SSLCertificate Qore::Socket::getRemoteCertificate | ( |  | ) |

Returns any remote certificate captured or NOTHING if there is none.

Example:
  *SSLCertificate cert = sock.getRemoteCertificate();

Returns
  any remote certificate captured or NOTHING if there is none

See also
  captureRemoteCertificates()

Since
  Qore 0.9.3

## ◆ getSendTimeout()

int Qore::Socket::getSendTimeout | ( |  | ) |

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

Code Flags:
  CONSTANT

Example:
  int to = sock.getSendTimeout();

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

## ◆ getSocket()

int Qore::Socket::getSocket | ( |  | ) |

Returns the socket file descriptor number.

Code Flags:
  CONSTANT

Example:
  int sock = sock.getSocket();

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

## ◆ getSocketInfo()

hash< auto > Qore::Socket::getSocketInfo | ( | bool | host_lookup = True | ) |

Returns information about the local socket as a hash.

If the socket is not open, an exception is thrown

Example:
  hash<auto> h = sock.getSocketInfo();

Parameters

  host_lookup | do a lookup of the hostname; if this is False then `"hostname"` and `"hostname_desc"` are not present in the response hash

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

Exceptions

  SOCKET-NOT-OPEN | The socket is not open
  SOCKET-GETSOCKETINFO-ERROR | error in getsockname()

Since
  Qore 0.8.8 added the host_lookup parameter

## ◆ getSSLCipherName()

*string Qore::Socket::getSSLCipherName | ( |  | ) |

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

Code Flags:
  CONSTANT

Example:
  *string str = sock.getSSLCipherName();

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

## ◆ getSSLCipherVersion()

*string Qore::Socket::getSSLCipherVersion | ( |  | ) |

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

Code Flags:
  CONSTANT

Example:
  *string str = sock.getSSLCipherVersion();

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

## ◆ getSslVerifyMode()

int Qore::Socket::getSslVerifyMode | ( |  | ) |

returns the current SSL verification mode

Code Flags:
  CONSTANT

Example:
  int mode = sock.getSslVerifyMode();

Returns
  the SSL verfication mode, see SSL Verification Mode Constants for more information

See also
  - Socket::getAcceptAllCertificates()
  - Socket::setSslVerifyMode()
  - Socket::acceptAllCertificates()

Since
  Qore 0.8.13

## ◆ getUsageInfo()

hash< auto > Qore::Socket::getUsageInfo | ( |  | ) |

Returns performance statistics for the socket.

Code Flags:
  CONSTANT

Example:
  hash<auto> h = sock.getUsageInfo();

Returns
  a hash with the following keys:
  - `"bytes_sent"`: an integer giving the total amount of bytes sent
  - `"bytes_recv"`: an integer giving the total amount of bytes received
  - `"us_sent"`: an integer giving the total number of microseconds spent sending data
  - `"us_recv"`: an integer giving the total number of microseconds spent receiving data
  - `"arg"`: (only if warning values have been set with Socket::setWarningQueue()) the optional argument for warning hashes
  - `"timeout"`: (only if warning values have been set with Socket::setWarningQueue()) the warning timeout in microseconds
  - `"min_throughput"`: (only if warning values have been set with Socket::setWarningQueue()) the minimum warning throughput in bytes/sec

Since
  Qore 0.8.9

See also
  Socket::clearStats()

## ◆ isDataAvailable()

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

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

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

Example:
  bool b = sock.isDataAvailable();

Parameters

  timeout_ms | an optional timeout in milliseconds (1/1000 second); if no timeout is given, the method returns immediately; Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-CLOSED | The remote end closed the connection without sending any data

## ◆ isOpen()

bool Qore::Socket::isOpen | ( |  | ) |

Returns True if the socket is open.

Code Flags:
  CONSTANT

Example:
  bool b = sock.isOpen();

Returns
  True if the socket is open, False if not

## ◆ isSecure()

bool Qore::Socket::isSecure | ( |  | ) |

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

Code Flags:
  CONSTANT

Example:
  bool b = sock.isSecure();

Returns
  True if the connection is encrypted, False if not

## ◆ isWriteFinished()

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

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

With a timeout of zero this method returns immediately.

Example:
  bool b = sock.isWriteFinished();

Parameters

  timeout_ms | an optional timeout in milliseconds (1/1000 second); if no timeout is given, the method returns immediately; Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-CLOSED | The remote end closed the connection without sending any data

## ◆ listen()

int Qore::Socket::listen | ( | int | backlog = 20 | ) |

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

Listens for new connections on a bound socket.

Example:
  sock.listen();

Parameters

  backlog | the size of the queue for pending connections

Returns
  Returns 0 for success, -1 for error

Exceptions

  SOCKET-NOT-OPEN | The socket is not bound

Since
  Qore 0.8.8 the backlog parameter was added

## ◆ parseServerSentEvent()

static hash< SseMessageInfo > Qore::Socket::parseServerSentEvent | ( | string | str | ) |
| static

Parse the given string as a Server Sent Event (SSE) string.

Parameters

  str | the string to parse as a Server Sent Event (SSE) string

Returns
  a hash of the event information

## ◆ pendingHttpChunkedBody()

bool Qore::Socket::pendingHttpChunkedBody | ( |  | ) |

returns True if the socket is still connected, and a HTTP header was read indicating chunked transfer encoding, but no chunked body has been read yet

Example:
  bool b = sock.pendingHttpChunkedBody();

Since
  Qore 0.8.10

## ◆ poll()

static list< hash< SocketPollInfo > > Qore::Socket::poll | ( | list< hash< SocketPollInfo > > | items,
|  | timeout | timeout_ms )
| static

polls multiple sockets and returns all sockets with events

Example:
  list<hash<SocketPollInfo>> l(
  <SocketPollInfo>{
  "events": SOCK_POLLOUT,
  "socket": sock1,
  },
  <SocketPollInfo>{
  "events": SOCK_POLLIN | SOCK_POLLOUT,
  "socket": sock2,
  },
  );
  l = Socket::poll(l, 2s);

Parameters

  items | list of SocketPollInfo hashes of sockets with events in the timeout period
  timeout_ms | the poll timeout period; -1 = never timeout

Returns
  a list of sockets with events in the timeout period

Exceptions

  SOCKET-POLL-ERROR | socket value in the items argument is not assigned or there was an error in the poll operation
  SOCKET-NOT-OPEN | socket value in the items argument is closed

Note
  If a socket being polled is closed or deleted in a background thread, the poll operation is not interrupted on Linux; other platforms behave differently (macOS / Darwin interrupts the polling process in this case); for proper operation on all platforms, do not assume that the polling operation will return immediately if a socket being polled is deleted in a background thread.

Since
  Qore 0.9.11

## ◆ readHTTPChunk()

hash< auto > Qore::Socket::readHTTPChunk | ( | timeout | timeout_ms = -1 | ) |

Reads in a single HTTP message chunk.

If any errors are encountered, an exception is raised. The chunk body is returned as a binary value.

Example:
  hash<auto> ans = sock.readHTTPChunk(20s);

Events:
  EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED

Parameters

  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

## ◆ readHTTPChunkedBody()

hash< auto > Qore::Socket::readHTTPChunkedBody | ( | timeout | timeout_ms = -1 | ) |

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

If any errors are encountered, an exception is raised

Example:
  hash<auto> ans = sock.readHTTPChunkedBody(20s);

Events:
  EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED

Parameters

  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

## ◆ readHTTPChunkedBodyBinary()

hash< auto > Qore::Socket::readHTTPChunkedBodyBinary | ( | timeout | timeout_ms = -1 | ) |

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

If any errors are encountered, an exception is raised

Example:
  hash<auto> ans = sock.readHTTPChunkedBodyBinary(20s);

Events:
  EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED

Parameters

  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

## ◆ readHTTPChunkedBodyBinaryWithCallback()

Qore::Socket::readHTTPChunkedBodyBinaryWithCallback | ( | code | rcb,
|  | timeout | timeout_ms = -1 )

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

If any errors are encountered, an exception is raised

Example:
  sock.readHTTPChunkedBodyBinaryWithCallback(recv_callback, 20s);

Events:
  EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED

Parameters

  rcb | The receive callback for the data received; first this method is called with a hash of the message headers, and then with any message body; if a chunked HTTP message is received, then the callback is called once for each chunk; when the message has been received, then the receive callback is called with a hash representing any trailer data received in a chunked transfer or NOTHING if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys: `"data"`: the string or binary data `"chunked"`: True if the data was received with chunked transfer encoding, False if not Header or trailer data is placed in a hash with the following keys: `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message `"obj"`: this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)
  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

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

Since
  Qore 0.8.10

## ◆ readHTTPChunkedBodyToOutputStream()

hash< auto > Qore::Socket::readHTTPChunkedBodyToOutputStream | ( | Qore::OutputStream | os,
|  | timeout | timeout_ms = -1 )

Reads in an HTTP message body sent in chunked transfer encoding, writes it in an OutputStream and returns any footers received.

If any errors are encountered, an exception is raised

Example:
  hash<auto> ans = sock.readHTTPChunkedBodyToOutputStream(outputStream, 20s);

Events:
  EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED

Parameters

  os | The output stream to write the response body to
  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  a hash of any HTTP footers received (with footer keys converted to lower case)

Exceptions

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

## ◆ readHTTPChunkedBodyWithCallback()

Qore::Socket::readHTTPChunkedBodyWithCallback | ( | code | rcb,
|  | timeout | timeout_ms = -1 )

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

If any errors are encountered, an exception is raised

Example:
  sock.readHTTPChunkedBodyWithCallback(recv_callback, 20s);

Events:
  EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED

Parameters

  rcb | The receive callback for the data received; first this method is called with a hash of the message headers, and then with any message body; if a chunked HTTP message is received, then the callback is called once for each chunk; when the message has been received, then the receive callback is called with a hash representing any trailer data received in a chunked transfer or NOTHING if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys: `"data"`: the string or binary data `"chunked"`: True if the data was received with chunked transfer encoding, False if not Header or trailer data is placed in a hash with the following keys: `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message `"obj"`: this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)
  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

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

Since
  Qore 0.8.10

## ◆ readHTTPHeader()

hash< auto > Qore::Socket::readHTTPHeader | ( | timeout | timeout_ms = -1,
|  | *reference< hash< auto > > | info )

Retuns a hash representing the data in the HTTP header read, or, if the data cannot be parsed as an HTTP header, then an exception is thrown, and the data read is returned as a string in the `arg` key of the exception hash.

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

Example:
  hash<auto> ans = sock.readHTTPHeader(10s);

Events:
  EVENT_PACKET_READ, EVENT_HTTP_MESSAGE_RECEIVED

Parameters

  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)
  info | An optional reference to an lvalue that can accept a hash that will be used as an output variable with one of the following two keys: `headers-raw`: the raw headers read without any case conversions or other processing `request-uri`: (only set when parsing a request header) gives the request URI in an HTTP request `response-uri`: (only set when parsing a response header) gives the response URI in an HTTP response `body-content-type`: this is the `"Content-Type"` header without any charset declaration `charset:` if there is a charset declaration in the `"Content-Type"` header, the value is returned in this key `close:` (only set when parsing a request header) set to True if the connection should be closed after responding, False if not; see notes below about how this value is calculated `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list `accept-encoding`: this key will be set to a list of values from any `"Accept-Encoding"` header

Returns
  a hash of headers (where each header key is converted to lower-case) also including the following keys giving additional information about the HTTP header received:
  - `http_version:` a string giving the HTTP version set in the header
  - `status_code:` (HTTP responses only) an integer giving the status code
  - `status_message:` (HTTP responses only) if present in an HTTP response, this key will be set to the message after the status code
  - `method:` (HTTP requests only) a string giving the HTTP method (i.e. `"GET"`, `"POST"`, etc)
  - `path:` (HTTP requests only) a string giving the path in a request without any decoding; use decode_url() to decode if necessary

Exceptions

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

Note
  - if the header claims a certain character encoding via a `charset` declaration in the `"Content-Type"` header, the Socket's character encoding is automatically set accordingly
  - RFC 2616 3.7.1: if no encoding is specified, then set `"iso-8859-1"`
  - RFC 2068 19.7.1: Persistent connections in HTTP/1.0 must be explicitly negotiated as they are not the default behavior
  - RFC 1945 1.3: Except for experimental applications, current practice requires that the connection be established by the client prior to each request and closed by the server after sending the response.
  - the conclusion is that server applications MUST close the connection when a request is received by an HTTP 1.0 client without an explicit request to keep the connection open

Since
  - Qore 0.8.4 this method always returns a hash and raises a `SOCKET-HTTP-ERROR` if invalid HTTP data is received
  - Qore 0.8.8 added the `close`, `charset`, `body-content-type`, and `accept-charset` info keys as well as the encoding handling based on the detected charset
  - Qore 0.9.3 added the `"headers-raw"` key in the output `info` hash

## ◆ readHTTPHeaderString()

string Qore::Socket::readHTTPHeaderString | ( | timeout | timeout_ms = -1 | ) |

Retuns a string representing the data in the HTTP header read (reads until `"\r\n\r\n"`)

If any errors occur reading from the socket, an exception is raised. Accepts an optional timeout value in milliseconds.

Example:
  string str = sock.readHTTPHeaderString(10s);

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  a string representing the header data read

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-CLOSED | The remote end closed the connection without sending any data
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | The data requested was not received in the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket
  SOCKET-HTTP-ERROR | maximum header size was exceeded

Since
  Qore 0.8.8

## ◆ readServerSentEvent() [1/2]

hash< SseMessageInfo > Qore::Socket::readServerSentEvent | ( | *string | content_encoding,
|  | timeout | timeout_ms = -1 )

Read a server sent event message.

Parameters

  content_encoding | any content encoding to use to decode the stream (ex: `"deflate"`)
  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-CLOSED | The remote end closed the connection without sending any data
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | The data requested was not received in the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket

Since
  Qore 2.0

## ◆ readServerSentEvent() [2/2]

hash< SseMessageInfo > Qore::Socket::readServerSentEvent | ( | timeout | timeout_ms = -1 | ) |

Read a server sent event message.

Parameters

  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-CLOSED | The remote end closed the connection without sending any data
  SOCKET-RECV-ERROR | There was an error receiving the data
  SOCKET-TIMEOUT | The data requested was not received in the timeout period
  SOCKET-SSL-ERROR | There was an SSL error while reading data from the socket

Since
  Qore 2.0

## ◆ recv()

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

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

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

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

Events:
  EVENT_PACKET_READ

Parameters

  size | the amount of data to read in bytes; to read until the remote closes the connection, use -1; a value of 0 means to read all data currently available or available up until the timeout period (if non-negative)
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

See also
  - Socket::setEncoding()
  - Socket::recvBinary()

## ◆ recvBinary()

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

Receives data from the socket and returns a binary object.

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

Example:
  binary data = sock.recvBinary(-1); # read all data available

Events:
  EVENT_PACKET_READ

Parameters

  size | the amount of data to read in bytes; to read until the remote closes the connection, use -1; a value of 0 means to read all data currently available or available up until the timeout period (if non-negative)
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  the data read, returned as a binary object

Exceptions

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

See also
  Socket::recv()

## ◆ recvi1()

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

Receives a 1-byte signed integer from the socket.

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

Example:
  int val = sock.recvi1();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

See also
  Socket::recvu1()

## ◆ recvi2()

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

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

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

Example:
  int val = sock.recvi2();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ recvi2LSB()

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

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

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

Example:
  int val = sock.recvi2LSB();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ recvi4()

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

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

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

Example:
  int val = sock.recvi4();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ recvi4LSB()

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

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

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

Example:
  int val = sock.recvi4LSB();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ recvi8()

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

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

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

Example:
  int val = sock.recvi8();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

See also
  Socket::recvi8LSB()

## ◆ recvi8LSB()

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

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

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

Example:
  int val = sock.recvi8LSB();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

See also
  Socket::recvi8()

## ◆ recvToOutputStream()

nothing Qore::Socket::recvToOutputStream | ( | Qore::OutputStream | os,
|  | softint | size = -1,
|  | timeout | timeout_ms = -1 )

Receives data from the socket and writes the bytes to an OutputStream.

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

Example:
  sock.recvToOutputStream(os, -1); # read all data available

Events:
  EVENT_PACKET_READ

Parameters

  os | The output stream to write the response body to
  size | the amount of data to read in bytes; to read until the remote closes the connection, use -1
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

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

See also
  Socket::recv()

Since
  Qore 0.8.13

## ◆ recvu1()

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

Receives a 1-byte unsigned integer from the socket.

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

Example:
  int val = sock.recvu1();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

See also
  Socket::recvi1()

## ◆ recvu2()

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

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

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

Example:
  int val = sock.recvu2();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ recvu2LSB()

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

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

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

Example:
  int val = sock.recvi2LSB();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ recvu4()

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

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

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

Example:
  int val = sock.recvu4();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ recvu4LSB()

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

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

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

Example:
  int val = sock.recvu4LSB();

Events:
  EVENT_PACKET_READ

Parameters

  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

Exceptions

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

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

## ◆ send() [1/2]

int Qore::Socket::send | ( | binary | bin,
|  | timeout | timeout_ms = -1 )

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

Example:
  sock.send(data, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  bin | Sends the binary data over the socket
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

See also
  - Socket::sendBinary()

Note
  this method is as of Qore 0.8.6+ equivalent to Socket::send2() except for the return value

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error like Socket::send2(); this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ send() [2/2]

int Qore::Socket::send | ( | string | str,
|  | timeout | timeout_ms = -1 )

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

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

Example:
  sock.send(str, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  str | sends the string data over the socket without the trailing null ('\0') character; the string's encoding is converted to the socket's encoding if necessary
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

See also
  - Socket::sendBinary2()

Note
  this method is as of Qore 0.8.6+ equivalent to Socket::send2() except for the return value

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error like Socket::send2(); this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ send2() [1/2]

nothing Qore::Socket::send2 | ( | binary | bin,
|  | timeout | timeout_ms = -1 )

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

Example:
  sock.send2(data);

Events:
  EVENT_PACKET_SENT

Parameters

  bin | Sends the binary data over the socket
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

See also
  - Socket::sendBinary2()

Note
  this method is as of Qore 0.8.6+ equivalent to Socket::send() except for the lack of a return value (since errors cause exceptions to be thrown, no return value is necessary)

Since
  Qore 0.8.4

## ◆ send2() [2/2]

nothing Qore::Socket::send2 | ( | string | str,
|  | timeout | timeout_ms = -1 )

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

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

Example:
  sock.send2(str);

Events:
  EVENT_PACKET_SENT

Parameters

  str | sends the string data over the socket without the trailing null ('\0') character; the string's encoding is converted to the socket's encoding if necessary
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

See also
  - Socket::sendBinary2()

Note
  this method is as of Qore 0.8.6+ equivalent to Socket::send() except for the lack of a return value (since errors cause exceptions to be thrown, no return value is necessary)

Since
  Qore 0.8.4

## ◆ sendBinary() [1/2]

int Qore::Socket::sendBinary | ( | binary | bin,
|  | timeout | timeout_ms = -1 )

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

Example:
  sock.sendBinary2(data);

Events:
  EVENT_PACKET_SENT

Parameters

  bin | Sends the binary data over the socket
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

See also
  Socket::send2()

Note
  this method is as of Qore 0.8.6+ equivalent to Socket::sendBinary2() except for the return value

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error like Socket::send2(); this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ sendBinary() [2/2]

int Qore::Socket::sendBinary | ( | string | str,
|  | timeout | timeout_ms = -1 )

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

Example:
  sock.sendBinary(str);

Events:
  EVENT_PACKET_SENT

Parameters

  str | string data to be sent (without any conversion to the socket's encoding) over the socket without the trailing null ('\0') character
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

See also
  Socket::send2()

Note
  this method is as of Qore 0.8.6+ equivalent to Socket::sendBinary2() except for the return value

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error like Socket::send2(); this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ sendBinary2() [1/2]

nothing Qore::Socket::sendBinary2 | ( | binary | bin,
|  | timeout | timeout_ms = -1 )

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

Example:
  sock.sendBinary2(data);

Events:
  EVENT_PACKET_SENT

Parameters

  bin | Sends the binary data over the socket
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

See also
  Socket::send2()

Note
  this method is as of Qore 0.8.6+ equivalent to Socket::sendBinary() except for the lack of a return value (since errors cause exceptions to be thrown, no return value is necessary)

Since
  Qore 0.8.4

## ◆ sendBinary2() [2/2]

nothing Qore::Socket::sendBinary2 | ( | string | str,
|  | timeout | timeout_ms = -1 )

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

Example:
  sock.sendBinary2(str);

Events:
  EVENT_PACKET_SENT

Parameters

  str | string data to be sent (without any conversion to the socket's encoding) over the socket without the trailing null ('\0') character
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

See also
  Socket::send2()

Note
  this method is as of Qore 0.8.6+ equivalent to Socket::sendBinary() except for the lack of a return value (since errors cause exceptions to be thrown, no return value is necessary)

Since
  Qore 0.8.4

## ◆ sendFromInputStream()

nothing Qore::Socket::sendFromInputStream | ( | Qore::InputStream | input_stream,
|  | softint | size = -1,
|  | timeout | timeout_ms = -1 )

Reads data from an InputStream and sends the bytes over the socket.

If any errors occur writing to the socket, an exception is raised

Example:
  sock.sendFromInputStream(input_stream, -1); # write all data available

Events:
  EVENT_PACKET_SENT

Parameters

  input_stream | the InputStream providing the data to send
  size | the amount of data to send in bytes; to send all data available in the InputStream, use -1
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

Since
  Qore 0.8.13

## ◆ sendHTTPChunkedBodyFromInputStream()

nothing Qore::Socket::sendHTTPChunkedBodyFromInputStream | ( | Qore::InputStream | input_stream,
|  | int | max_chunk_size = 4096,
|  | timeout | timeout_ms = -1,
|  | *code | tcb )

Sends an HTTP message body in chunked transfer encoding.

If any errors are encountered, an exception is raised.

Example:
  sock.sendHTTPChunkedBodyFromInputStream(inputStream);

Events:
  EVENT_PACKET_SENT

Parameters

  input_stream | The input stream to read data from
  max_chunk_size | the maximum chunk size as the read block size for the InputStream read block size; the actual size of the data read will determine the size of each HTTP chunk
  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)
  tcb | An optional trailer callback for message trailers to write in the outgoing chunked message; the callback takes no arguments and must return either NOTHING or hash giving a hash of trailers for the final chunk

Exceptions

  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | send failed
  HTTP-CHUNK-ERROR | the chunk size given is not greater than 0
  HTTP-TRAILER-ERROR | the trailer callback must return either NOTHING or hash; this exception is thrown is another type is returned

Since
  Qore 0.8.13

## ◆ sendHTTPChunkedBodyTrailer()

nothing Qore::Socket::sendHTTPChunkedBodyTrailer | ( | *hash< auto > | trailer,
|  | timeout | timeout_ms = -1 )

Sends the trialer of an HTTP message body in chunked transfer encoding.

If any errors are encountered, an exception is raised

Example:
  sock.sendHTTPChunkedBodyTrailer({});

Events:
  EVENT_PACKET_SENT

Parameters

  trailer | optional trailer data
  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | send failed

Since
  Qore 0.8.13

## ◆ sendHTTPMessage() [1/2]

nothing Qore::Socket::sendHTTPMessage | ( | string | method,
|  | string | path,
|  | string | http_version,
|  | hash< auto > | headers,
|  | *binary | body,
|  | *reference< hash< auto > > | info,
|  | timeout | timeout_ms = -1 )

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

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

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

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  method | the HTTP method name to send (i.e. POST, HEAD, etc)
  path | the path component of the URL
  http_version | the HTTP protocol version (`"1.0"` or `"1.1"`)
  headers | a hash of additional headers to send (key-value pairs)
  body | if it does not have a length of zero, the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set)
  info | An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `request-uri`: The request URI as sent in the output message
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | Send failed
  SOCKET-SSL-ERROR | there was an error sending SSL data

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

## ◆ sendHTTPMessage() [2/2]

nothing Qore::Socket::sendHTTPMessage | ( | string | method,
|  | string | path,
|  | string | http_version,
|  | hash< auto > | headers,
|  | string | body,
|  | *reference< hash > | info,
|  | timeout | timeout_ms = -1 )

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

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

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

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  method | the HTTP method name to send (i.e. POST, HEAD, etc)
  path | the path component of the URL
  http_version | the HTTP protocol version (`"1.0"` or `"1.1"`)
  headers | a hash of additional headers to send (key-value pairs)
  body | the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set); string data will be automatically converted to the Socket's encoding if necessary
  info | An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `request-uri`: The request URI as sent in the output message
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

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

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

## ◆ sendHTTPMessageWithCallback()

nothing Qore::Socket::sendHTTPMessageWithCallback | ( | code | scb,
|  | string | method,
|  | string | path,
|  | string | http_version,
|  | hash< auto > | headers,
|  | *reference< hash< auto > > | info,
|  | timeout | timeout_ms = -1 )

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

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

Example:
  sock.sendHTTPMessageWithCallback(send_callback, "POST", "/RPC2", "1.1", ("Content-Type" : "text/xml"));

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  scb | The callback giving the chunked HTTP data to send; this callback must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be sent or simply NOTHING which will close the chunked message
  method | the HTTP method name to send (i.e. POST, HEAD, etc)
  path | the path component of the URL
  http_version | the HTTP protocol version (`"1.0"` or `"1.1"`)
  headers | a hash of additional headers to send (key-value pairs)
  info | An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `request-uri`: The request URI as sent in the output message
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | Send failed
  SOCKET-SSL-ERROR | there was an error sending SSL data

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

Since
  Qore 0.8.10

## ◆ sendHTTPResponse() [1/5]

nothing Qore::Socket::sendHTTPResponse | ( | softint | status_code,
|  | string | status_desc,
|  | string | http_version,
|  | hash< auto > | headers,
|  | *binary | body,
|  | *reference< hash< auto > > | info,
|  | timeout | timeout_ms = -1 )

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

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

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

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  status_code | the HTTP status code to send (i.e. `200`, `404`, etc)
  status_desc | the descriptive text for the status code.
  http_version | the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
  headers | a hash of additional headers to send (key-value pairs)
  body | if the binary object given does not have a length of zero, the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set)
  info | An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `response-uri`: The response URI as sent in the output message
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-SENDHTTPRESPONSE-STATUS-ERROR | raised if the status_code (first argument) is < 100 or > 599
  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | send failed

Since
  Qore 0.9.4

## ◆ sendHTTPResponse() [2/5]

nothing Qore::Socket::sendHTTPResponse | ( | softint | status_code,
|  | string | status_desc,
|  | string | http_version,
|  | hash< auto > | headers,
|  | *binary | body,
|  | timeout | timeout_ms = -1 )

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

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

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

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  status_code | the HTTP status code to send (i.e. `200`, `404`, etc)
  status_desc | the descriptive text for the status code.
  http_version | the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
  headers | a hash of additional headers to send (key-value pairs)
  body | if the binary object given does not have a length of zero, the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set)
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-SENDHTTPRESPONSE-STATUS-ERROR | raised if the status_code (first argument) is < 100 or > 599
  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | send failed

## ◆ sendHTTPResponse() [3/5]

nothing Qore::Socket::sendHTTPResponse | ( | softint | status_code,
|  | string | status_desc,
|  | string | http_version,
|  | hash< auto > | headers,
|  | Qore::InputStream | input_stream,
|  | int | max_chunk_size = 4096,
|  | *reference< hash< auto > > | info,
|  | timeout | timeout_ms = -1,
|  | *code | tcb )

Sends an HTTP response with user-defined headers and a message body from an input stream in chunked transfer encoding.

If any errors are encountered, an exception is raised.

Example:
  sock.sendHTTPResponse(200, "OK", "1.1", {"Connection": "Keep-Alive", "Transfer-Encoding": "chunked"}, inputStream);

Events:
  EVENT_PACKET_SENT

Parameters

  status_code | the HTTP status code to send (i.e. `200`, `404`, etc)
  status_desc | the descriptive text for the status code.
  http_version | the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
  headers | a hash of additional headers to send (key-value pairs); note that the `"Transfer-Encoding"` header must be set to `"chunked"` manually with this call
  input_stream | The input stream to read data from
  max_chunk_size | the maximum chunk size as the read block size for the InputStream read block size; the actual size of the data read will determine the size of each HTTP chunk
  info | An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `response-uri`: The response URI as sent in the output message
  timeout_ms | The timeout in milliseconds (1/1000 second). If no timeout or if a negative timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. If a timeout occurs, a `"SOCKET-TIMEOUT"` exception is raised. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)
  tcb | An optional trailer callback for message trailers to write in the outgoing chunked message; the callback takes no arguments and must return either NOTHING or hash giving a hash of trailers for the final chunk

Note
  the `"Transfer-Encoding"` header must be set to `"chunked"` manually in the headers argument as in the example

Exceptions

  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | send failed
  HTTP-CHUNK-ERROR | the chunk size given is not greater than 0
  HTTP-TRAILER-ERROR | the trailer callback must return either NOTHING or hash; this exception is thrown is another type is returned

Since
  Qore 0.9.4

## ◆ sendHTTPResponse() [4/5]

nothing Qore::Socket::sendHTTPResponse | ( | softint | status_code,
|  | string | status_desc,
|  | string | http_version,
|  | hash< auto > | headers,
|  | string | body,
|  | *reference< hash< auto > > | info,
|  | timeout | timeout_ms = -1 )

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

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

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

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  status_code | the HTTP status code to send (i.e. `200`, `404`, etc)
  status_desc | the descriptive text for the status code.
  http_version | the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
  headers | a hash of additional headers to send (key-value pairs)
  body | if present (and does not have a length of zero), the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set); string data will be automatically converted to the Socket's encoding if necessary
  info | An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `response-uri`: The response URI as sent in the output message
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

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

Since
  Qore 0.9.4

## ◆ sendHTTPResponse() [5/5]

nothing Qore::Socket::sendHTTPResponse | ( | softint | status_code,
|  | string | status_desc,
|  | string | http_version,
|  | hash< auto > | headers,
|  | string | body,
|  | timeout | timeout_ms = -1 )

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

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

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

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  status_code | the HTTP status code to send (i.e. `200`, `404`, etc)
  status_desc | the descriptive text for the status code.
  http_version | the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
  headers | a hash of additional headers to send (key-value pairs)
  body | if present (and does not have a length of zero), the body to be sent with the message (if present, the `"Content-Length"` header will be automatically set); string data will be automatically converted to the Socket's encoding if necessary
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

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

## ◆ sendHTTPResponseWithCallback() [1/2]

nothing Qore::Socket::sendHTTPResponseWithCallback | ( | code | scb,
|  | softint | status_code,
|  | string | status_desc,
|  | string | http_version,
|  | hash< auto > | headers,
|  | *reference< hash< auto > > | info,
|  | timeout | timeout_ms = -1 )

Sends an HTTP response with user-defined headers given as a hash and a message body to send with chunked transfer encoding provided by a callback.

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

Example:
  sock.sendHTTPResponseWithCallback(send_callback, 200, "OK", "1.1", {"Connection": "Keep-Alive", "Transfer-Encoding": "chunked"});

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  scb | The callback giving the chunked HTTP data to send; this callback must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be sent or simply NOTHING which will close the chunked message
  status_code | the HTTP status code to send (i.e. `200`, `404`, etc)
  status_desc | the descriptive text for the status code.
  http_version | the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
  headers | a hash of additional headers to send (key-value pairs); note that the `"Transfer-Encoding"` header must be set to `"chunked"` manually with this call
  info | An optional reference to an lvalue that can accept a hash that will be used as an output variable with the following hash key: `response-uri`: The response URI as sent in the output message
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Note
  the `"Transfer-Encoding"` header must be set to `"chunked"` manually in the headers argument as in the example

Exceptions

  SOCKET-SENDHTTPRESPONSE-STATUS-ERROR | raised if the status_code (first argument) is < 100 or > 599
  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | send failed

Since
  Qore 0.9.4

## ◆ sendHTTPResponseWithCallback() [2/2]

nothing Qore::Socket::sendHTTPResponseWithCallback | ( | code | scb,
|  | softint | status_code,
|  | string | status_desc,
|  | string | http_version,
|  | hash< auto > | headers,
|  | timeout | timeout_ms = -1 )

Sends an HTTP response with user-defined headers given as a hash and a message body to send with chunked transfer encoding provided by a callback.

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

Example:
  sock.sendHTTPResponseWithCallback(send_callback, 200, "OK", "1.1", {"Connection": "Keep-Alive", "Transfer-Encoding": "chunked"});

Events:
  EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE

Parameters

  scb | The callback giving the chunked HTTP data to send; this callback must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be sent or simply NOTHING which will close the chunked message
  status_code | the HTTP status code to send (i.e. `200`, `404`, etc)
  status_desc | the descriptive text for the status code.
  http_version | the HTTP protocol version (normally `"1.0"` or `"1.1"`, however this method allows any string to be sent)
  headers | a hash of additional headers to send (key-value pairs); note that the `"Transfer-Encoding"` header must be set to `"chunked"` manually with this call
  timeout_ms | the timeout in milliseconds (1/1000 second); If no timeout is passed or is negative, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Note
  the `"Transfer-Encoding"` header must be set to `"chunked"` manually in the headers argument as in the example

Exceptions

  SOCKET-SENDHTTPRESPONSE-STATUS-ERROR | raised if the status_code (first argument) is < 100 or > 599
  SOCKET-NOT-OPEN | the socket is not connected
  SOCKET-TIMEOUT | the data requested was not received in the timeout period
  SOCKET-SEND-ERROR | send failed

Since
  Qore 0.8.10

## ◆ sendi1()

int Qore::Socket::sendi1 | ( | softint | i = 0,
|  | timeout | timeout_ms = -1 )

Sends a 1-byte integer over the socket.

If any errors occur, an exception is thrown

Example:
  sock.sendi1(val, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  i | the integer to send; only the least-significant byte will be sent
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error; this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ sendi2()

int Qore::Socket::sendi2 | ( | softint | i = 0,
|  | timeout | timeout_ms = -1 )

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

If any errors occur, an exception is thrown

Example:
  sock.sendi2(val, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  i | the integer to send; only the least-significant 2 bytes will be sent
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error; this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ sendi2LSB()

int Qore::Socket::sendi2LSB | ( | softint | i = 0,
|  | timeout | timeout_ms = -1 )

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

If any errors occur, an exception is thrown

Example:
  sock.sendi2LSB(val, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  i | the integer to send; only the least-significant 2 bytes will be sent
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error; this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ sendi4()

int Qore::Socket::sendi4 | ( | softint | i = 0,
|  | timeout | timeout_ms = -1 )

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

If any errors occur, an exception is thrown

Example:
  sock.sendi4(val, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  i | the integer to send; only the least-significant 4 bytes will be sent
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error; this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ sendi4LSB()

int Qore::Socket::sendi4LSB | ( | softint | i = 0,
|  | timeout | timeout_ms = -1 )

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

If any errors occur, an exception is thrown

Example:
  sock.sendi4LSB(val, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  i | the integer to send; only the least-significant 4 bytes will be sent
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error; this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ sendi8()

int Qore::Socket::sendi8 | ( | softint | i = 0,
|  | timeout | timeout_ms = -1 )

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

If any errors occur, an exception is thrown

Example:
  sock.sendi8(val, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  i | the integer to send
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error; this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ sendi8LSB()

int Qore::Socket::sendi8LSB | ( | softint | i = 0,
|  | timeout | timeout_ms = -1 )

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

If any errors occur, an exception is thrown

Example:
  sock.sendi8LSB(val, 20s);

Events:
  EVENT_PACKET_SENT

Parameters

  i | the integer to send
  timeout_ms | the timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been sent or the remote end closes the connection; the timeout value is the longest value that a single send() operation can take with non-blocking I/O. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Returns
  always returns 0 for backwards compatibility; if an error occurs, an exception is thrown

Exceptions

  SOCKET-NOT-OPEN | The socket is not connected
  SOCKET-TIMEOUT | a single send() operation exceeded the given timeout period
  SOCKET-SEND-ERROR | an error occurred sending the socket data
  SOCKET-SSL-ERROR | there was an SSL error while writing data to the socket

Since
  Qore 0.8.6 this method takes a timeout value and throws exceptions on error; this change was made because it was not possible to catch SSL errors with this method with the previous implementation

## ◆ setCertificate() [1/3]

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

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

Example:
  sock.setCertificate(cert_der);

Parameters

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

## ◆ setCertificate() [2/3]

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

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

Example:
  sock.setCertificate(cert);

Parameters

  cert | This must be an SSLCertificate object

## ◆ setCertificate() [3/3]

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

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

Example:
  sock.setCertificate(cert_string);

Parameters

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

## ◆ setCertificateAndPrivateKey()

nothing Qore::Socket::setCertificateAndPrivateKey | ( | SSLCertificate | cert,
|  | SSLPrivateKey | key )

Sets the X.509 certificate and private key in one atomic operation to use for negotiating encrypted connections.

Example:
  sock.setCertificateAndPrivateKey(cert, key);

Parameters

  cert | This must be an SSLCertificate object
  key | This must be an QoreSSLPrivateKey object

Since
  Qore 1.11.0

## ◆ setCharset()

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

Sets the character encoding for the socket.

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

Parameters

  encoding | The character encoding for the socket

## ◆ setEncoding()

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

Sets the character encoding for the socket.

Parameters

  encoding | the character encoding for the socket

## ◆ setEventQueue() [1/2]

nothing Qore::Socket::setEventQueue | ( |  | ) |

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

Example:
  sock.setEventQueue();

See also
  I/O Event Handling for more information

## ◆ setEventQueue() [2/2]

nothing Qore::Socket::setEventQueue | ( | Qore::Thread::Queue | queue,
|  | auto | arg,
|  | *bool | with_data )

Sets a Queue object to receive socket events.

Example:
  sock.setEventQueue(queue);

Parameters

  queue | the Queue object to receive socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
  arg | an argument that will be included in each event hash in the arg key
  with_data | if True, then the actual raw data transferred / received is also included in the events

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

See also
  I/O Event Handling for more information

Since
  Qore 0.9.4 added the arg and with_data options

## ◆ setNoDelay()

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

Sets the boolean `TCP_NODELAY` setting for the socket.

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

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

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

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

Parameters

  nd | the boolean `TCP_NODELAY` setting for the socket

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

See also
  Socket::getNoDelay()

## ◆ setPrivateKey() [1/3]

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

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

Example:
  sock.setPrivateKey(key_der);

Parameters

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

## ◆ setPrivateKey() [2/3]

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

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

Example:
  sock.setPrivateKey(key);

Parameters

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

## ◆ setPrivateKey() [3/3]

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

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

Example:
  sock.setPrivateKey(key_pem, password);

Parameters

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

## ◆ setRecvTimeout()

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

sets the receive timeout as a socket option

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

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

Parameters

  timeout_ms | the receive timeout to set with a resolution of milliseconds; Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

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

## ◆ setSendTimeout()

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

sets the send timeout as a socket option

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

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

Parameters

  timeout_ms | the send timeout to set with a resolution of milliseconds

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

## ◆ setSslVerifyMode()

Qore::Socket::setSslVerifyMode | ( | int | mode | ) |

sets the SSL verification mode

Example:
  sock.setSslVerifyMode(SSL_VERIFY_PEER|SSL_VERIFY_FAIL_IF_NO_PEER_CERT);

If there is no SSL connection in place, then the mode is saved and will be used automatically for future SSL sessions automatically.

Parameters

  mode | the SSL verfication mode, see SSL Verification Mode Constants for more information

See also
  - Socket::getAcceptAllCertificates()
  - Socket::getSslVerifyMode()
  - Socket::acceptAllCertificates()

Since
  Qore 0.8.13

## ◆ setWarningQueue()

nothing Qore::Socket::setWarningQueue | ( | int | warning_ms,
|  | int | warning_bs,
|  | Queue | queue,
|  | auto | arg,
|  | timeout | min_ms = 1s )

Sets a Queue object to receive socket warnings.

Example:
  sock.setWarningQueue(5000, 5000, queue, "socket-1");

Parameters

  warning_ms | the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys: `"type"`: a string with the constant value `"SOCKET-OPERATION-WARNING"` `"operation"`: a string giving the operation that caused the warning (ex: `"connect"`) `"us"`: an integer giving the number of microseconds for the operation `"timeout"`: an integer giving the warning threshold in microseconds `"arg"`: if any `"arg"` argument is passed to the Socket::setWarningQueue() method, it will be included in the warning hash here
  warning_bs | value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys: `"type"`: a string with the constant value `"SOCKET-THROUGHPUT-WARNING"` `"dir"`: either `"send"` or `"recv"` depending on the direction of the data flow `"bytes"`: the amount of bytes sent `"us"`: an integer giving the number of microseconds for the operation `"bytes_sec"`: a float giving the transfer speed in bytes per second `"threshold"`: an integer giving the warning threshold in bytes per second `"arg"`: if any `"arg"` argument is passed to the Socket::setWarningQueue() method, it will be included in the warning hash here
  queue | the Queue object to receive warning events
  arg | an optional argument to be placed in the `"arg"` key in each warning hash (could be used to identify the socket for example)
  min_ms | the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set
  SOCKET-SETWARNINGQUEUE-ERROR | at least one of warning_ms and warning_bs must be > 0

See also
  Socket::clearWarningQueue()

Since
  - Qore 0.8.9
  - Qore 0.8.12 the minimum threshold for a warning is a transfer of at least 1024 bytes, smaller transfers will not result in a warning

## ◆ shutdown()

int Qore::Socket::shutdown | ( |  | ) |

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

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

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

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

## ◆ shutdownSSL()

nothing Qore::Socket::shutdownSSL | ( |  | ) |

Shuts down the SSL connection on a secure connection.

If any errors occur, an exception is raised

Example:
  sock.shutdownSSL();

Exceptions

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

## ◆ startPollAccept()

AbstractPollOperation Qore::Socket::startPollAccept | ( |  | ) |

Returns an AbstractPollOperation object to accept a new connection.

Returns
  an AbstractPollOperation object to accept a new connection connection; the AbstractPollOperation::getOutput() method returns the new Socket after a successful poll operation

An SSL connection is automatically negotiated with the new connection if the Socket has a certificate and private key configured.

Since
  Qore 2.0

## ◆ startPollConnect()

AbstractPollOperation Qore::Socket::startPollConnect | ( | string | target | ) |

Returns an AbstractPollOperation object to poll the socket for a standard connection.

Parameters

  target | the URL target

Returns
  an AbstractPollOperation object to poll the socket for a standard connection

Since
  Qore 1.12

## ◆ startPollConnectSsl()

AbstractPollOperation Qore::Socket::startPollConnectSsl | ( | string | target | ) |

Returns an AbstractPollOperation object to poll the socket for an SSL connection.

Parameters

  target | the URL target

Returns
  an AbstractPollOperation object to poll the socket for an SSL connection

The poll operation returned will perform the connection and an immediate upgrade to an SSL/TLS connection

Since
  Qore 1.12

## ◆ startPollReadHttpHeader()

AbstractPollOperation Qore::Socket::startPollReadHttpHeader | ( |  | ) |

Returns an AbstractPollOperation object to read an HTTP header without blocking.

Returns
  an AbstractPollOperation object to read an HTTP header without blocking

The AbstractPollOperation::getOutput() call will return a hash with the following keys after a successful poll for inbound socket data:

- hdr: a hash of header info like that returned from readHTTPHeader():
  - `http_version:` a string giving the HTTP version set in the header
  - `status_code:` (HTTP responses only) an integer giving the status code
  - `status_message:` (HTTP responses only) if present in an HTTP response, this key will be set to the message after the status code
  - `method:` (HTTP requests only) a string giving the HTTP method (i.e. `"GET"`, `"POST"`, etc)
  - `path:` (HTTP requests only) a string giving the path in a request without any decoding; use decode_url() to decode if necessary
- info: a hash of other information:
  - `headers-raw`: the raw headers read without any case conversions or other processing
  - `request-uri`: (only set when parsing a request header) gives the request URI in an HTTP request
  - `response-uri`: (only set when parsing a response header) gives the response URI in an HTTP response
  - `body-content-type`: this is the `"Content-Type"` header without any charset declaration
  - `charset:` if there is a charset declaration in the `"Content-Type"` header, the value is returned in this key
  - `close:` (only set when parsing a request header) set to True if the connection should be closed after responding, False if not; see notes below about how this value is calculated
  - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
  - `accept-encoding`: this key will be set to a list of values from any `"Accept-Encoding"` header

Since
  Qore 2.0

## ◆ startPollRecvBinary()

AbstractPollOperation Qore::Socket::startPollRecvBinary | ( | int | size | ) |

Returns an AbstractPollOperation object to read data in non-blocking mode.

Parameters

  size | the size of the string to receive

Returns
  an AbstractPollOperation object to read data in non-blocking mode

The AbstractPollOperation::getOutput() call will return a binary object after a successful poll for inbound socket data

Since
  Qore 1.12

## ◆ startPollRecvData()

AbstractPollOperation Qore::Socket::startPollRecvData | ( |  | ) |

Returns an AbstractPollOperation object for receiving data in non-blocking mode.

Returns
  an AbstractPollOperation object to read data in non-blocking mode; data will be read until the connection would block or at most 640KB of data has been read

The AbstractPollOperation::getOutput() call will return a binary object after a successful poll for inbound socket data; whatever data can be read will be returned

Since
  Qore 2.0

## ◆ startPollRecvString()

AbstractPollOperation Qore::Socket::startPollRecvString | ( | int | size | ) |

Returns an AbstractPollOperation object to read data in non-blocking mode.

Parameters

  size | the size of the string to receive

Returns
  an AbstractPollOperation object to read data in non-blocking mode

The AbstractPollOperation::getOutput() call will return a string after a successful poll for inbound socket data

Since
  Qore 1.12

## ◆ startPollRecvUntilBytesBinary()

AbstractPollOperation Qore::Socket::startPollRecvUntilBytesBinary | ( | string | pattern | ) |

Returns an AbstractPollOperation object to read data in non-blocking mode.

Parameters

  pattern | the pattern to use to signify the end of the socket data to read

Returns
  an AbstractPollOperation object to read data in non-blocking mode

The AbstractPollOperation::getOutput() call will return a binary object after a successful poll for inbound socket data

Since
  Qore 1.12

## ◆ startPollRecvUntilBytesString()

AbstractPollOperation Qore::Socket::startPollRecvUntilBytesString | ( | string | pattern | ) |

Returns an AbstractPollOperation object to read data in non-blocking mode.

Parameters

  pattern | the pattern to use to signify the end of the socket data to read

Returns
  an AbstractPollOperation object to read data in non-blocking mode

The AbstractPollOperation::getOutput() call will return a string after a successful poll for inbound socket data

Since
  Qore 1.12

## ◆ startPollSend() [1/2]

AbstractPollOperation Qore::Socket::startPollSend | ( | binary | data | ) |

Returns an AbstractPollOperation object to send data in non-blocking mode.

Parameters

  data | the data to send

Returns
  an AbstractPollOperation object to send data in non-blocking mode

Since
  Qore 1.12

## ◆ startPollSend() [2/2]

AbstractPollOperation Qore::Socket::startPollSend | ( | string | data | ) |

Returns an AbstractPollOperation object to send data in non-blocking mode.

Parameters

  data | the data to send

Returns
  an AbstractPollOperation object to send data in non-blocking mode

Since
  Qore 1.12

## ◆ startPollUpgradeClientToSSL()

AbstractPollOperation Qore::Socket::startPollUpgradeClientToSSL | ( |  | ) |

Returns an AbstractPollOperation object to upgrade a connected client socket to SSL.

Returns
  an AbstractPollOperation object to upgrade a connected client socket to SSL

The poll operation returned will upgrade a client connection to an SSL/TLS connection using any certificate and private key set for the socket.

Since
  Qore 1.12

## ◆ startPollUpgradeServerToSSL()

AbstractPollOperation Qore::Socket::startPollUpgradeServerToSSL | ( |  | ) |

Returns an AbstractPollOperation object to upgrade a connected server socket to SSL.

Returns
  an AbstractPollOperation object to upgrade a connected server socket to SSL

The poll operation returned will upgrade a server connection to an SSL/TLS connection using the certificate and private key set on the socket.

Since
  Qore 1.12

## ◆ upgradeClientToSSL()

nothing Qore::Socket::upgradeClientToSSL | ( | timeout | timeout_ms = -1 | ) |

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

Example:
  sock.upgradeClientToSSL();

Parameters

  timeout_ms | If a positive timeout value is passed and the SSL upgrade takes longer to establish than the timeout, an `"SSL-TIMEOUT-ERROR"` exception is thrown. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | the socket must be open before making this call
  SSL-TIMEOUT-ERROR | timeout error negotiating SSL connection

Note
  if an SSL connection has already been established, this method call returns immediately without taking any further action

Since
  Qore 0.8.12 the timeout_ms parameter was added

## ◆ upgradeServerToSSL()

nothing Qore::Socket::upgradeServerToSSL | ( | timeout | timeout_ms = -1 | ) |

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

Example:
  sock.upgradeServerToSSL();

Parameters

  timeout_ms | If a positive timeout value is passed and the SSL upgrade takes longer to establish than the timeout, an `"SSL-TIMEOUT-ERROR"` exception is thrown. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. `2m` = two minutes, etc.)

Exceptions

  SOCKET-NOT-OPEN | the socket must be open before making this call
  SSL-TIMEOUT-ERROR | timeout error negotiating SSL connection

Note
  if an SSL connection has already been established, this method call returns immediately without taking any further action

Since
  Qore 0.8.12 the timeout_ms parameter was added

## ◆ verifyPeerCertificate()

*string Qore::Socket::verifyPeerCertificate | ( |  | ) |

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

Code Flags:
  CONSTANT

Example:
  *string str = sock.verifyPeerCertificate();

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