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. |
| 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:
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:
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:
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 |
| 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:
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:
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"). |
| 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"). |
| 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:
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:
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:
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:
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:
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. |
| 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:
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:
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:
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:
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:
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:
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:
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:
