I/O Event Handling

Qore supports a simple event-handling mechanism to provide notification and details of socket and network events in higher-level classes. Classes currently supporting events are the Socket, HTTPClient, FtpClient, and File classes.

See Event Constants for a list of all event constants; details about each event are documented in the following sections.

Event information is placed on the event queue (which must be a Queue object) in the form of a hash. Each event has the following standar keys:
Event Hash Common Keys

Key | Value
[`arg`] | This key holds any argument provided when setting the event queue
`event` | This key holds the event code; see information for individual events in the following sections
`source` | This key holds the event source code
`id` | The value of this key is a unique integer that can be used to uniquely identify the object generating the event.

# EVENT_PACKET_READ

Event
  Qore::EVENT_PACKET_READ

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately after a network packet is received.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_PACKET_READ
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object
  `read` | The number of bytes read in the packet.
  `total_read` | The total number of bytes read in the read loop.
  ``[total_to_read] | The total number of bytes to read in the read loop (this key is only present if the total number of bytes to read is known).

# EVENT_PACKET_SENT

Event
  Qore::EVENT_PACKET_SENT

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately after a network packet is sent.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_PACKET_SENT
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object
  `socket` | The file descriptor number of the socket.
  `sent` | The number of bytes sent in the packet.
  `total_sent` | The total number of bytes sent in the send loop.
  `total_to_send` | The total number of bytes to send in the send loop.

# EVENT_HTTP_CONTENT_LENGTH

Event
  Qore::EVENT_HTTP_CONTENT_LENGTH

Source
  Qore::SOURCE_HTTPCLIENT

Description
  This event is raised immediately after an HTTP header is received containing a content length header line, but before the message body is received.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_CONTENT_LENGTH
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class
  `id` | A unique integer ID for the underlying socket object
  `len` | The number of bytes given for the content length.

# EVENT_HTTP_CHUNKED_START

Event
  Qore::EVENT_HTTP_CHUNKED_START

Source
  Qore::SOURCE_HTTPCLIENT

Description
  This event is raised after receiving an HTTP header with the `Transfer-Encoding` header set to `chunked` and before the chunked data is read.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_CHUNKED_START
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class
  `id` | A unique integer ID for the socket object.

# EVENT_HTTP_CHUNKED_END

Event
  Qore::EVENT_HTTP_CHUNKED_END

Source
  Qore::SOURCE_HTTPCLIENT

Description
  This event is raised after all chunked data is read from the socket.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_CHUNKED_END
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class
  `id` | A unique integer ID for the socket object.

# EVENT_HTTP_REDIRECT

Event
  Qore::EVENT_HTTP_REDIRECT

Source
  Qore::SOURCE_HTTPCLIENT

Description
  This event is raised after a redirect response is received from an HTTP server.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_REDIRECT
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class
  `id` | A unique integer ID for the socket object.
  `location` | The redirect location given by the HTTP server
  ``[status_message] | Any status message sent by the HTTP server; if no message was sent, then this key will not be present in the event hash.

# EVENT_CHANNEL_CLOSED

Event
  Qore::EVENT_CHANNEL_CLOSED

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately after the socket is closed.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_CHANNEL_CLOSED
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object

# EVENT_DELETED

Event
  Qore::EVENT_DELETED

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised when the socket object is deleted.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_DELETED
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object

# EVENT_FTP_SEND_MESSAGE

Event
  Qore::EVENT_FTP_SEND_MESSAGE

Source
  Qore::SOURCE_FTPCLIENT

Description
  This event is raised immediately before a message is sent on the FTP control channel.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_FTP_SEND_MESSAGE
  `source` | Qore::SOURCE_FTPCLIENT, indicating the FtpClient class
  `id` | A unique integer ID for the underlying socket object
  `command` | A string giving the FTP command sent (ex: `"RETR"`).
  ``[arg] | The argument to the command; if no argument is sent, then this key will not be present.

# EVENT_FTP_MESSAGE_RECEIVED

Event
  Qore::EVENT_FTP_MESSAGE_RECEIVED

Source
  Qore::SOURCE_FTPCLIENT

Description
  This event is raised immediately after a message is received on the FTP control channel.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_FTP_MESSAGE_RECEIVED
  `source` | Qore::SOURCE_FTPCLIENT, indicating the FtpClient class
  `id` | A unique integer ID for the underlying socket object
  `command` | A string giving the FTP command sent (ex: `"RETR"`).
  ``[arg] | The argument to the command; if no argument is sent, then this key will not be present.

# EVENT_HOSTNAME_LOOKUP

Event
  Qore::EVENT_HOSTNAME_LOOKUP

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately before a hostname lookup is made.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HOSTNAME_LOOKUP
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object
  `name` | A string giving the name to be looked up.

# EVENT_HOSTNAME_RESOLVED

Event
  Qore::EVENT_HOSTNAME_RESOLVED

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately after a successful hostname resolution.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HOSTNAME_RESOLVED
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object
  `type` | The type of address for the socket; one of the Network Address Family Constants
  `typename` | A descriptive name for the address family (ex: `"ipv4"`, `"ipv6"`)
  `address` | A string giving the network address the name was resolved to.

# EVENT_HTTP_SEND_MESSAGE

Event
  Qore::EVENT_HTTP_SEND_MESSAGE

Source
  Qore::SOURCE_HTTPCLIENT or Qore::SOURCE_SOCKET

Description
  This event is raised immediately before an HTTP message is sent.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_SEND_MESSAGE
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class, or Qore::SOURCE_SOCKET, indicating the Socket class
  `message` | The first string in the HTTP message (ex: GET / HTTP/1.1).
  `headers` | a hash of all headers to send in the message.

# EVENT_HTTP_MESSAGE_RECEIVED

Event
  Qore::EVENT_HTTP_MESSAGE_RECEIVED

Source
  Qore::SOURCE_HTTPCLIENT or Qore::SOURCE_SOCKET

Description
  This event is raised immediately after an HTTP message is received.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_MESSAGE_RECEIVED
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class, or Qore::SOURCE_SOCKET, indicating the Socket class

  `headers`

  A hash of all headers received in the message, plus the following headers giving additional information about the message:
  - `"http_version"`: giving the HTTP protocol version in the message
  - `"status_code"`: giving the HTTP status code if the message is a response
  - `"status_message"`: giving any HTTP status message if the message is a response
  - `"method"`: giving the HTTP method if the message is a request
  - `"path"`: providing the path in request messages.

# EVENT_HTTP_FOOTERS_RECEIVED

Event
  Qore::EVENT_HTTP_FOOTERS_RECEIVED

Source
  Qore::SOURCE_HTTPCLIENT

Description
  This event is raised immediately after HTTP footers are received after receiving chunked data.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_FOOTERS_RECEIVED
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class
  `headers` | A hash of all footers received in the message.

# EVENT_HTTP_CHUNKED_DATA_RECEIVED

Event
  Qore::EVENT_HTTP_CHUNKED_DATA_RECEIVED

Source
  Qore::SOURCE_HTTPCLIENT

Description
  This event is raised immediately after chunked data is received.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_CHUNKED_DATA_RECEIVED
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class
  `read` | An integer giving the number of bytes read in the chunk.
  `total_read` | An integer giving the total number of bytes of chunked data read in the current message.

# EVENT_HTTP_CHUNK_SIZE

Event
  Qore::EVENT_HTTP_CHUNK_SIZE

Source
  Qore::SOURCE_HTTPCLIENT

Description
  This event is raised immediately after chunk information is received providing the size of the next chunk.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_CHUNK_SIZE
  `source` | Qore::SOURCE_HTTPCLIENT, indicating the HTTPClient class
  `size` | An integer giving the number of bytes in the next chunk.
  `total_read` | An integer giving the total number of bytes of chunked data read in the current message.

# EVENT_CONNECTING

Event
  Qore::EVENT_CONNECTING

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately before a socket connection is attempted.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_CONNECTING
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object
  `type` | The type of address for the socket; one of the Network Address Family Constants
  `typename` | A descriptive name for the address family (ex: `"ipv4"`, `"ipv6"`)
  `address` | A string giving the target address (ex: `"::1"`, `"192.168.20.4"`)
  `target` | The target address for the connection.
  ``[port] | The target port for the connection; if not applicable for the address family then this hash key is not included.

# EVENT_CONNECTED

Event
  Qore::EVENT_CONNECTED

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately after a socket connection is established.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_CONNECTED
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object

# EVENT_START_SSL

Event
  Qore::EVENT_START_SSL

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately before SSL negotiation is attempted.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_START_SSL
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object

# EVENT_SSL_ESTABLISHED

Event
  Qore::EVENT_SSL_ESTABLISHED

Source
  Qore::SOURCE_SOCKET

Description
  This event is raised immediately after SSL negotiation has been successfully established.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_SSL_ESTABLISHED
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class
  `id` | A unique integer ID for the underlying socket object
  `cipher` | A string giving the name of the cipher algorithm used for the connection.
  `cipher_version` | A string giving the version of the cipher algorithm used for the connection.

# EVENT_OPEN_FILE

Event
  Qore::EVENT_OPEN_FILE

Source
  Qore::SOURCE_FILE

Description
  This event is raised immediately before a file is opened.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_OPEN_FILE
  `source` | Qore::SOURCE_FILE, indicating the File class
  `id` | A unique integer ID for the File object
  `filename` | The file's name.
  `flags` | The flags used to open the file.
  `mode` | The mode to open the file with.
  `encoding` | The character encoding given used for reading from or writing to the file.

# EVENT_FILE_OPENED

Event
  Qore::EVENT_FILE_OPENED

Source
  Qore::SOURCE_FILE

Description
  This event is raised immediately after a file has been successfully opened.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_FILE_OPENED
  `source` | Qore::SOURCE_FILE, indicating the File class
  `id` | A unique integer ID for the File object
  `filename` | The file's name.
  `flags` | The flags used to open the file.
  `mode` | The mode to open the file with.
  `encoding` | The character encoding given used for reading from or writing to the file.

# EVENT_DATA_READ

Event
  Qore::EVENT_DATA_READ

Source
  Qore::SOURCE_FILE

Description
  This event is raised immediately after data is read from a file.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_DATA_READ
  `source` | Qore::SOURCE_FILE, indicating the File class
  `id` | A unique integer ID for the File object
  `read` | The number of bytes read from the file.
  `total_read` | The total number of bytes read in the read loop.
  `total_to_read` | The total number of bytes to read in the read loop.

# EVENT_DATA_WRITTEN

Event
  Qore::EVENT_DATA_WRITTEN

Source
  Qore::SOURCE_FILE

Description
  This event is raised immediately after data is written to a file.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_DATA_WRITTEN
  `source` | Qore::SOURCE_FILE, indicating the File class
  `id` | A unique integer ID for the File object
  `written` | The number of bytes written to the file.
  `total_written` | The total number of bytes written in the write loop.
  `total_to_write` | The total number of bytes to write in the write loop.

# EVENT_HTTP_CHUNKED_DATA_READ

Source
  Qore::SOURCE_SOCKET, Qore::SOURCE_HTTPCLIENT

Event
  Qore::EVENT_HTTP_CHUNKED_DATA_READ

Description
  This event is raised when HTTP chunked data is read if the event data flag is set in the call to set the event queue.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_CHUNKED_DATA_READ
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class or Qore::SOURCE_HTTPCLIENT, indicating the Qore::HTTPClient class "HTTPClient class"
  `data` | a string or binary value

# EVENT_HTTP_CHUNKED_DATA_SENT

Event
  Qore::EVENT_HTTP_CHUNKED_DATA_SENT

Source
  Qore::SOURCE_SOCKET, Qore::SOURCE_HTTPCLIENT

Description
  This event is raised when HTTP chunked data is sent if the event data flag is set in the call to set the event queue.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_CHUNKED_DATA_SENT
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class or Qore::SOURCE_HTTPCLIENT, indicating the Qore::HTTPClient class "HTTPClient class"
  `data` | a string or binary value

# EVENT_HTTP_CHUNKED_FOOTERS_SENT

Event
  Qore::EVENT_HTTP_CHUNKED_FOOTERS_SENT

Source
  Qore::SOURCE_SOCKET, Qore::SOURCE_HTTPCLIENT

Description
  This event is raised when HTTP footers are sent at the end of a chunked data transfer if the event data flag is set in the call to set the event queue.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_CHUNKED_FOOTERS_SENT
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class or Qore::SOURCE_HTTPCLIENT, indicating the Qore::HTTPClient class "HTTPClient class"
  `headers` | a hash of chunked footers sent

# EVENT_SOCKET_DATA_READ

Event
  Qore::EVENT_SOCKET_DATA_READ

Source
  Qore::SOURCE_SOCKET, Qore::SOURCE_HTTPCLIENT

Description
  This event is raised when socket data is read if the event data flag is set in the call to set the event queue.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_SOCKET_DATA_READ
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class or Qore::SOURCE_HTTPCLIENT, indicating the Qore::HTTPClient class "HTTPClient class"
  `data` | a string or binary value

# EVENT_SOCKET_DATA_SENT

Event
  Qore::EVENT_SOCKET_DATA_SENT

Source
  Qore::SOURCE_SOCKET, Qore::SOURCE_HTTPCLIENT

Description
  This event is raised when socket data is sent if the event data flag is set in the call to set the event queue.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_SOCKET_DATA_SENT
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class or Qore::SOURCE_HTTPCLIENT, indicating the Qore::HTTPClient class "HTTPClient class"
  `data` | a string or binary value

# EVENT_HTTP_HEADERS_READ

Event
  Qore::EVENT_HTTP_HEADERS_READ

Source
  Qore::SOURCE_SOCKET, Qore::SOURCE_HTTPCLIENT

Description
  This event is raised when HTTP header data is read if the event data flag is set in the call to set the event queue.
  The event hash contains the following keys:

  Key | Value
  [`arg`] | This key holds any argument provided when setting the event queue
  `event` | Qore::EVENT_HTTP_HEADERS_READ
  `source` | Qore::SOURCE_SOCKET, indicating the Socket class or Qore::SOURCE_HTTPCLIENT, indicating the Qore::HTTPClient class "HTTPClient class"
  `data` | a string value