[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Exchanging Data

A lot of data has to be exchanged between the user and the crypto engine, like plaintext messages, ciphertext, signatures and information about the keys. The technical details about exchanging the data information are completely abstracted by GPGME. The user provides and receives the data via GpgmeData objects, regardless of the communication protocol between GPGME and the crypto engine in use.

Data type: GpgmeData
The GpgmeData type is a handle for a container for generic data, which is used by GPGME to exchange data with the user.

5.1 Creating Data Buffers  Creating new data buffers.
5.2 Destroying Data Buffers  Releasing data buffers.
5.3 Manipulating Data Buffers  Operations on data buffers.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Creating Data Buffers

Function: GpgmeError gpgme_data_new (GpgmeData *dh)
The function gpgme_data_new creates a new GpgmeData object and returns a handle for it in dh. The data object is initially empty.

The function returns GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if dh is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.

Function: GpgmeError gpgme_data_new_from_mem (GpgmeData *dh, const char *buffer, size_t size, int copy)
The function gpgme_data_new_from_mem creates a new GpgmeData 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 GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if dh or buffer is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.

Function: GpgmeError gpgme_data_new_from_file (GpgmeData *dh, const char *filename, int copy)
The function gpgme_data_new_from_file creates a new GpgmeData 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 GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if dh or filename is not a valid pointer, GPGME_File_Error if an I/O operation fails, GPGME_Not_Implemented if code is zero, and GPGME_Out_Of_Core if not enough memory is available.

Function: GpgmeError gpgme_data_new_from_filepart (GpgmeData *dh, const char *filename, FILE *fp, off_t offset, size_t length)
The function gpgme_data_new_from_filepart creates a new GpgmeData 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 GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if dh and exactly one of filename and fp is not a valid pointer, GPGME_File_Error if an I/O operation fails, and GPGME_Out_Of_Core if not enough memory is available.

Function: GpgmeError gpgme_data_new_with_read_cb (GpgmeData *dh, int (*readfunc) (void *hook, char *buffer, size_t count, size_t *nread), void *hook_value)
The function gpgme_data_new_with_read_cb creates a new GpgmeData object and uses the callback function readfunc to retrieve the data on demand. As the callback function can supply the data in any way it wants, this is the most flexible data type GPGME provides. However, it can not be used to write data.

The callback function receives hook_value as its first argument whenever it is invoked. It should return up to count bytes in buffer, and return the number of bytes actually read in nread. It may return 0 in nread if no data is currently available. To indicate EOF the function should return with an error code of -1 and set nread to 0. The callback function may support to reset its internal read pointer if it is invoked with buffer and nread being NULL and count being 0.

The function returns GPGME_No_Error if the data object was successfully created, GPGME_Invalid_Value if dh or readfunc is not a valid pointer, and GPGME_Out_Of_Core if not enough memory is available.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Destroying Data Buffers

Function: void gpgme_data_release (GpgmeData dh)
The function gpgme_data_release destroys the data object with the handle dh. It releases all associated resources that were not provided by the user in the first place.

Function: char * gpgme_data_release_and_get_mem (GpgmeData dh, size_t *length)
The function gpgme_data_release_and_get_mem is like gpgme_data_release, except that it returns the data buffer and its length that was provided by the object.

The user has to release the buffer with free. In case the user provided the data buffer in non-copy mode, a copy will be made for this purpose.

In case an error returns, or there is no suitable data buffer that can be returned to the user, the function will return NULL.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 Manipulating Data Buffers

Function: GpgmeError gpgme_data_read (GpgmeData dh, void *buffer, size_t length, size_t *nread)
The function gpgme_data_read reads up to length bytes from the data object with the handle dh into the space starting at buffer. The actual amount read is returned in nread.

If buffer is NULL, the function returns the amount of bytes available in nread without changing the read pointer. This is not supported by all types of data objects. If this function is not supported, GPGME_Invalid_Type is returned.

If the end of the data object is reached, the function returns GPGME_EOF and sets nread to zero.

In all other cases, the function returns GPGME_No_Error if the operation was successfully performed and GPGME_Invalid_Value if dh is not a valid pointer.

Function: GpgmeError gpgme_data_rewind (GpgmeData dh)
The function gpgme_data_rewind resets the read pointer of the data object with the handle dh, so that a subsequent gpgme_data_read operation starts at the beginning of the data.

The function returns GPGME_No_Error if the operation was successfully performed, GPGME_Not_Implemented if the operation is not supported (for example, by a read callback function supplied by the user) and GPGME_Invalid_Value if dh is not a valid pointer.

Function: GpgmeError gpgme_data_write (GpgmeData dh, const void *buffer, size_t length)
The function gpgme_data_write writes length bytes starting from buffer into the data object with the handle dh at the current write position.

The function returns GPGME_No_Error if the operation was successfully performed, GPGME_Invalid_Value if dh or buffer is not a valid pointer, GPGME_Invalid_Type or GPGME_Invalid_Mode if the data object type does not support writing, and GPGME_Out_Of_Core if not enough memory is available.

Data type: enum GpgmeDataType
The GpgmeDataType type specifies the type of a GpgmeData object. The following data types are available:

GPGME_DATA_TYPE_NONE
This specifies that the type is not yet determined.

GPGME_DATA_TYPE_MEM
This specifies that the data is stored in memory.

GPGME_DATA_TYPE_FD
This type is not implemented.

GPGME_DATA_TYPE_FILE
This type is not implemented.

GPGME_DATA_TYPE_CB
This type specifies that the data is provided by a callback function implemented by the user.

Function: GpgmeDataType gpgme_data_get_type (GpgmeData dh)
The function gpgme_data_get_type returns the type of the data object with the handle dh. If dh is not a valid pointer, GPGME_DATA_TYPE_NONE is returned.

Data type: enum GpgmeDataEncoding
The GpgmeDataEncoding type specifies the encoding of a GpgmeData object. This encoding is useful to give the backend a hint on the type of data. The following data types are available:

GPGME_DATA_ENCODING_NONE
This specifies that the encoding is not known. This is the default for a new data object. The backend will try its best to detect the encoding automatically.

GPGME_DATA_ENCODING_BINARY
This specifies that the data is encoding in binary form; i.e. there is no special encoding.

GPGME_DATA_ENCODING_BASE64
This specifies that the data is encoded using the Base-64 encoding scheme as used by MIME and other protocols.

GPGME_DATA_ENCODING_ARMOR
This specifies that the data is encoded in an armored form as used by OpenPGP and PEM.

Function: GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh)
The function gpgme_data_get_encoding returns the encoding of the data object with the handle dh. If dh is not a valid pointer (e.g. NULL) GPGME_DATA_ENCODING_NONE is returned.

Function: GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc)
The function gpgme_data_set_encoding changes the encoding of the data object with the handle dh to enc.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by John Goerzen on November, 19 2002 using texi2html