2.24. Event Handling

Qore supports a simple event-handling mechanism to provide notification and details of socket and network events in higher-level classes. Classes curerntly supporting events are the Socket, HTTPClient, and FtpClient 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:

Table 2.96. 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.


2.24.1. EVENT_PACKET_READ

Event

EVENT_PACKET_READ

Source

SOURCE_SOCKET

Description

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

Table 2.97. EVENT_PACKET_READ Event Hash

Key

Value

event

EVENT_PACKET_READ

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the 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).


2.24.2. EVENT_PACKET_SENT

Event

EVENT_PACKET_SENT

Source

SOURCE_SOCKET

Description

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

Table 2.98. EVENT_PACKET_SENT Event Hash

Key

Value

event

EVENT_PACKET_SENT

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the 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.


2.24.3. EVENT_HTTP_CONTENT_LENGTH

Event

EVENT_HTTP_CONTENT_LENGTH

Source

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:

Table 2.99. EVENT_HTTP_CONTENT_LENGTH Event Hash

Key

Value

event

EVENT_HTTP_CONTENT_LENGTH

source

SOURCE_HTTPCLIENT, indicating the HTTPClient class

id

A unique integer ID for the socket object.

len

The number of bytes given for the content length.


2.24.4. EVENT_HTTP_CHUNKED_START

Event

EVENT_HTTP_CHUNKED_START

Source

SOURCE_HTTPCLIENT

Description

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

Table 2.100. EVENT_HTTP_CHUNKED_START Event Hash

Key

Value

event

EVENT_HTTP_CHUNKED_START

source

SOURCE_HTTPCLIENT, indicating the HTTPClient class

id

A unique integer ID for the socket object.


2.24.5. EVENT_HTTP_CHUNKED_END

Event

EVENT_HTTP_CHUNKED_END

Source

SOURCE_HTTPCLIENT

Description

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

Table 2.101. EVENT_HTTP_CHUNKED_END Event Hash

Key

Value

event

EVENT_HTTP_CHUNKED_END

source

SOURCE_HTTPCLIENT, indicating the HTTPClient class

id

A unique integer ID for the socket object.


2.24.6. EVENT_HTTP_REDIRECT

Event

EVENT_HTTP_REDIRECT

Source

SOURCE_HTTPCLIENT

Description

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

Table 2.102. EVENT_HTTP_REDIRECT Event Hash

Key

Value

event

EVENT_HTTP_REDIRECT

source

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.


2.24.7. EVENT_CHANNEL_CLOSED

Event

EVENT_CHANNEL_CLOSED

Source

SOURCE_SOCKET

Description

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

Table 2.103. EVENT_CHANNEL_CLOSED Event Hash

Key

Value

event

EVENT_CHANNEL_CLOSED

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the socket object.


2.24.8. EVENT_DELETED

Event

EVENT_DELETED

Source

SOURCE_SOCKET

Description

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

Table 2.104. EVENT_DELETED Event Hash

Key

Value

event

EVENT_DELETED

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the socket object.


2.24.9. EVENT_FTP_SEND_MESSAGE

Event

EVENT_FTP_SEND_MESSAGE

Source

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:

Table 2.105. EVENT_FTP_SEND_MESSAGE Event Hash

Key

Value

event

EVENT_FTP_SEND_MESSAGE

source

SOURCE_FTPCLIENT, indicating the FtpClient class

id

A unique integer ID for the 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.


2.24.10. EVENT_FTP_MESSAGE_RECEIVED

Event

EVENT_FTP_MESSAGE_RECEIVED

Source

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:

Table 2.106. EVENT_FTP_MESSAGE_RECEIVED Event Hash

Key

Value

event

EVENT_FTP_MESSAGE_RECEIVED

source

SOURCE_FTPCLIENT, indicating the FtpClient class

id

A unique integer ID for the 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.


2.24.11. EVENT_HOSTNAME_LOOKUP

Event

EVENT_HOSTNAME_LOOKUP

Source

SOURCE_SOCKET

Description

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

Table 2.107. EVENT_HOSTNAME_LOOKUP Event Hash

Key

Value

event

EVENT_HOSTNAME_LOOKUP

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the socket object.

name

A string giving the name to be looked up.


2.24.12. EVENT_HOSTNAME_RESOLVED

Event

EVENT_HOSTNAME_RESOLVED

Source

SOURCE_SOCKET

Description

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

Table 2.108. EVENT_HOSTNAME_RESOLVED Event Hash

Key

Value

event

EVENT_HOSTNAME_RESOLVED

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the socket object.

address

A string giving the network address the name was resolved to.


2.24.13. EVENT_HTTP_SEND_MESSAGE

Event

EVENT_HTTP_SEND_MESSAGE

Source

SOURCE_HTTPCLIENT or SOURCE_SOCKET

Description

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

Table 2.109. EVENT_HTTP_SEND_MESSAGE Event Hash

Key

Value

event

EVENT_HTTP_SEND_MESSAGE

source

SOURCE_HTTPCLIENT, indicating the HTTPClient class, or 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.


2.24.14. EVENT_HTTP_MESSAGE_RECEIVED

Event

EVENT_HTTP_MESSAGE_RECEIVED

Source

SOURCE_HTTPCLIENT or SOURCE_SOCKET

Description

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

Table 2.110. EVENT_HTTP_MESSAGE_RECEIVED Event Hash

Key

Value

event

EVENT_HTTP_MESSAGE_RECEIVED

source

SOURCE_HTTPCLIENT, indicating the HTTPClient class, or 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.


2.24.15. EVENT_HTTP_FOOTERS_RECEIVED

Event

EVENT_HTTP_FOOTERS_RECEIVED

Source

SOURCE_HTTPCLIENT

Description

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

Table 2.111. EVENT_HTTP_FOOTERS_RECEIVED Event Hash

Key

Value

event

EVENT_HTTP_FOOTERS_RECEIVED

source

SOURCE_HTTPCLIENT, indicating the HTTPClient class

headers

A hash of all footers received in the message.


2.24.16. EVENT_HTTP_CHUNKED_DATA_RECEIVED

Event

EVENT_HTTP_CHUNKED_DATA_RECEIVED

Source

SOURCE_HTTPCLIENT

Description

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

Table 2.112. EVENT_HTTP_CHUNKED_DATA_RECEIVED Event Hash

Key

Value

event

EVENT_HTTP_CHUNKED_DATA_RECEIVED

source

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.


2.24.17. EVENT_HTTP_CHUNK_SIZE

Event

EVENT_HTTP_CHUNK_SIZE

Source

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:

Table 2.113. EVENT_HTTP_CHUNK_SIZE_RECEIVED Event Hash

Key

Value

event

EVENT_HTTP_CHUNK_SIZE_RECEIVED

source

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.


2.24.18. EVENT_CONNECTING

Event

EVENT_CONNECTING

Source

SOURCE_SOCKET

Description

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

Table 2.114. EVENT_CONNECTING Event Hash

Key

Value

event

EVENT_CONNECTING

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the socket object.

type

The type of address for the socket; one of the Network Address Constants.

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.


2.24.19. EVENT_CONNECTED

Event

EVENT_CONNECTED

Source

SOURCE_SOCKET

Description

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

Table 2.115. EVENT_CONNECTED Event Hash

Key

Value

event

EVENT_CONNECTED

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the socket object.


2.24.20. EVENT_START_SSL

Event

EVENT_START_SSL

Source

SOURCE_SOCKET

Description

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

Table 2.116. EVENT_START_SSL Event Hash

Key

Value

event

EVENT_START_SSL

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the socket object.


2.24.21. EVENT_SSL_ESTABLISHED

Event

EVENT_SSL_ESTABLISHED

Source

SOURCE_SOCKET

Description

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

Table 2.117. EVENT_SSL_ESTABLISHED Event Hash

Key

Value

event

EVENT_SSL_ESTABLISHED

source

SOURCE_SOCKET, indicating the Socket class

id

A unique integer ID for the 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.


2.24.22. EVENT_OPEN_FILE

Event

EVENT_OPEN_FILE

Source

SOURCE_FILE

Description

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

Table 2.118. EVENT_OPEN_FILE Event Hash

Key

Value

event

EVENT_OPEN_FILE

source

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.


2.24.23. EVENT_FILE_OPENED

Event

EVENT_FILE_OPENED

Source

SOURCE_FILE

Description

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

Table 2.119. EVENT_FILE_OPENED Event Hash

Key

Value

event

EVENT_FILE_OPENED

source

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.


2.24.24. EVENT_DATA_READ

Event

EVENT_DATA_READ

Source

SOURCE_FILE

Description

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

Table 2.120. EVENT_DATA_READ Event Hash

Key

Value

event

EVENT_DATA_READ

source

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.


2.24.25. EVENT_DATA_WRITTEN

Event

EVENT_DATA_WRITTEN

Source

SOURCE_FILE

Description

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

Table 2.121. EVENT_DATA_WRITTEN Event Hash

Key

Value

event

EVENT_DATA_WRITTEN

source

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.