Qore Programming Language Reference Manual  0.8.12.9
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.