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 at least the following keys:
Event Hash Common Keys

Key | Value
`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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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
  `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 from a file.
  The event hash contains the following keys:

  Key | Value
  `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.