File: gpgme.info,  Node: Memory Based Data Buffers,  Next: File Based Data Buffers,  Up: Creating Data Buffers

6.1.1 Memory Based Data Buffers
-------------------------------

Memory based data objects store all data in allocated memory.  This is
convenient, but only practical for an amount of data that is a fraction
of the available physical memory.  The data has to be copied from its
source and to its destination, which can often be avoided by using one
of the other data object

 -- Function: gpgme_error_t gpgme_data_new (gpgme_data_t *DH)
     The function ‘gpgme_data_new’ creates a new ‘gpgme_data_t’ object
     and returns a handle for it in DH.  The data object is memory based
     and initially empty.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
     object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH is not a
     valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough memory is
     available.

 -- Function: gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *DH,
          const char *BUFFER, size_t SIZE, int COPY)
     The function ‘gpgme_data_new_from_mem’ creates a new ‘gpgme_data_t’
     object and fills it with SIZE bytes starting from BUFFER.

     If COPY is not zero, a private copy of the data is made.  If COPY
     is zero, the data is taken from the specified buffer as needed, and
     the user has to ensure that the buffer remains valid for the whole
     life span of the data object.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
     object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
     BUFFER is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough
     memory is available.

 -- Function: gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *DH,
          const char *FILENAME, int COPY)
     The function ‘gpgme_data_new_from_file’ creates a new
     ‘gpgme_data_t’ object and fills it with the content of the file
     FILENAME.

     If COPY is not zero, the whole file is read in at initialization
     time and the file is not used anymore after that.  This is the only
     mode supported currently.  Later, a value of zero for COPY might
     cause all reads to be delayed until the data is needed, but this is
     not yet implemented.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
     object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
     FILENAME is not a valid pointer, ‘GPG_ERR_NOT_IMPLEMENTED’ if CODE
     is zero, and ‘GPG_ERR_ENOMEM’ if not enough memory is available.

 -- Function: gpgme_error_t gpgme_data_new_from_filepart
          (gpgme_data_t *DH, const char *FILENAME, FILE *FP,
          off_t OFFSET, size_t LENGTH)
     The function ‘gpgme_data_new_from_filepart’ creates a new
     ‘gpgme_data_t’ object and fills it with a part of the file
     specified by FILENAME or FP.

     Exactly one of FILENAME and FP must be non-zero, the other must be
     zero.  The argument that is not zero specifies the file from which
     LENGTH bytes are read into the data object, starting from OFFSET.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data
     object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH and
     exactly one of FILENAME and FP is not a valid pointer, and
     ‘GPG_ERR_ENOMEM’ if not enough memory is available.