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.