6.1.3 Callback Based Data Buffers

If neither memory nor file based data objects are a good fit for your application, you can implement the functions a data object provides yourself and create a data object from these callback functions.

Data type: ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer, size_t size)

The gpgme_data_read_cb_t type is the type of functions which GPGME calls if it wants to read data from a user-implemented data object. The function should read up to size bytes from the current read position into the space starting at buffer. The handle is provided by the user at data object creation time.

Note that GPGME assumes that the read blocks until data is available. Errors during I/O operations, except for EINTR, are usually fatal for crypto operations.

The function should return the number of bytes read, 0 on EOF, and -1 on error. If an error occurs, errno should be set to describe the type of the error.

Data type: ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer, size_t size)

The gpgme_data_write_cb_t type is the type of functions which GPGME calls if it wants to write data to a user-implemented data object. The function should write up to size bytes to the current write position from the space starting at buffer. The handle is provided by the user at data object creation time.

Note that GPGME assumes that the write blocks until data is available. Errors during I/O operations, except for EINTR, are usually fatal for crypto operations.

The function should return the number of bytes written, and -1 on error. If an error occurs, errno should be set to describe the type of the error.

Data type: off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence)

The gpgme_data_seek_cb_t type is the type of functions which GPGME calls if it wants to change the current read/write position in a user-implemented data object, just like the lseek function.

The function should return the new read/write position, and -1 on error. If an error occurs, errno should be set to describe the type of the error.

Data type: void (*gpgme_data_release_cb_t) (void *handle)

The gpgme_data_release_cb_t type is the type of functions which GPGME calls if it wants to destroy a user-implemented data object. The handle is provided by the user at data object creation time.

Data type: struct gpgme_data_cbs

This structure is used to store the data callback interface functions described above. It has the following members:

gpgme_data_read_cb_t read

This is the function called by GPGME to read data from the data object. It is only required for input data object.

gpgme_data_write_cb_t write

This is the function called by GPGME to write data to the data object. It is only required for output data object.

gpgme_data_seek_cb_t seek

This is the function called by GPGME to change the current read/write pointer in the data object (if available). It is optional.

gpgme_data_release_cb_t release

This is the function called by GPGME to release a data object. It is optional.

Function: gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh, gpgme_data_cbs_t cbs, void *handle)

The function gpgme_data_new_from_cbs creates a new gpgme_data_t object and uses the user-provided callback functions to operate on the data object.

The handle handle is passed as first argument to the callback functions. This can be used to identify this data object.

The function returns the error code GPG_ERR_NO_ERROR if the data object was successfully created, and GPG_ERR_ENOMEM if not enough memory is available.