The `GnuPG Made Easy' Reference Manual: Exchanging Data

[ < ] | [ > ] |  | [ << ] | [ 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, 21 2002 using texi2html