File: gpgme.info,  Node: Callback Based Data Buffers,  Prev: File Based Data Buffers,  Up: Creating Data Buffers

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.