Next: , Up: Using External Event Loops


7.7.2.1 I/O Callback Interface
— Data type: gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd)

The gpgme_io_cb_t type is the type of functions which GPGME wants to register as I/O callback handlers using the gpgme_register_io_cb_t functions provided by the user.

data and fd are provided by GPGME when the I/O callback handler is registered, and should be passed through to the handler when it is invoked by the user because it noticed activity on the file descriptor fd.

The callback handler always returns 0, but you should consider the return value to be reserved for later use.

— Data type: gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data, void **tag)

The gpgme_register_io_cb_t type is the type of functions which can be called by GPGME to register an I/O callback function fnc for the file descriptor fd with the user. fnc_data should be passed as the first argument to fnc when the handler is invoked (the second argument should be fd). If dir is 0, fnc should be called by the user when fd is ready for writing. If dir is 1, fnc should be called when fd is ready for reading.

data was provided by the user when registering the gpgme_register_io_cb_t function with GPGME and will always be passed as the first argument when registering a callback function. For example, the user can use this to determine the event loop to which the file descriptor should be added.

GPGME will call this function when a crypto operation is initiated in a context for which the user has registered I/O callback handler functions with gpgme_set_io_cbs. It can also call this function when it is in an I/O callback handler for a file descriptor associated to this context.

The user should return a unique handle in tag identifying this I/O callback registration, which will be passed to the gpgme_register_io_cb_t function without interpretation when the file descriptor should not be monitored anymore.

— Data type: void (*gpgme_remove_io_cb_t) (void *tag)

The gpgme_remove_io_cb_t type is the type of functions which can be called by GPGME to remove an I/O callback handler that was registered before. tag is the handle that was returned by the gpgme_register_io_cb_t for this I/O callback.

GPGME can call this function when a crypto operation is in an I/O callback. It will also call this function when the context is destroyed while an operation is pending.

— Data type: enum gpgme_event_io_t

The gpgme_event_io_t type specifies the type of an event that is reported to the user by GPGME as a consequence of an I/O operation. The following events are defined:

GPGME_EVENT_START
The operation is fully initialized now, and you can start to run the registered I/O callback handlers now. Note that registered I/O callback handlers must not be run before this event is signalled. type_data is NULL and reserved for later use.
GPGME_EVENT_DONE
The operation is finished, the last I/O callback for this operation was removed. The accompanying type_data points to a gpgme_error_t variable that contains the status of the operation that finished. This event is signalled after the last I/O callback has been removed.
GPGME_EVENT_NEXT_KEY
In a gpgme_op_keylist_start operation, the next key was received from the crypto engine. The accompanying type_data is a gpgme_key_t variable that contains the key with one reference for the user.
GPGME_EVENT_NEXT_TRUSTITEM
In a gpgme_op_trustlist_start operation, the next trust item was received from the crypto engine. The accompanying type_data is a gpgme_trust_item_t variable that contains the trust item with one reference for the user.

— Data type: void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type, void *type_data)

The gpgme_event_io_cb_t type is the type of functions which can be called by GPGME to signal an event for an operation running in a context which has I/O callback functions registered by the user.

data was provided by the user when registering the gpgme_event_io_cb_t function with GPGME and will always be passed as the first argument when registering a callback function. For example, the user can use this to determine the context in which this event has occured.

type will specify the type of event that has occured. type_data specifies the event further, as described in the above list of possible gpgme_event_io_t types.

GPGME can call this function in an I/O callback handler.