6.3.2 Data Buffer Meta-Data

Function: char * gpgme_data_get_file_name (gpgme_data_t dh)

SINCE: 1.1.0

The function gpgme_data_get_file_name returns a pointer to a string containing the file name associated with the data object. The file name will be stored in the output when encrypting or signing the data and will be returned to the user when decrypting or verifying the output data.

If no error occurs, the string containing the file name is returned. Otherwise, NULL will be returned.

Function: gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh, const char *file_name)

SINCE: 1.1.0

The function gpgme_data_set_file_name sets the file name associated with the data object. The file name will be stored in the output when encrypting or signing the data and will be returned to the user when decrypting or verifying the output data.

The function returns the error code GPG_ERR_INV_VALUE if dh is not a valid pointer and GPG_ERR_ENOMEM if not enough memory is available.

Data type: enum gpgme_data_encoding_t

The gpgme_data_encoding_t type specifies the encoding of a gpgme_data_t object. For input data objects, the encoding is useful to give the backend a hint on the type of data. For output data objects, the encoding can specify the output data format on certain operations. Please note that not all backends support all encodings on all operations. 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.

GPGME_DATA_ENCODING_MIME

SINCE: 1.7.0

This specifies that the data is encoded as a MIME part.

GPGME_DATA_ENCODING_URL

SINCE: 1.2.0

The data is a list of linefeed delimited URLs. This is only useful with gpgme_op_import.

GPGME_DATA_ENCODING_URL0

SINCE: 1.2.0

The data is a list of binary zero delimited URLs. This is only useful with gpgme_op_import.

GPGME_DATA_ENCODING_URLESC

SINCE: 1.2.0

The data is a list of linefeed delimited URLs with all control and space characters percent escaped. This mode is is not yet implemented.

Function: gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t 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: gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh, gpgme_data_encoding_t enc)

The function gpgme_data_set_encoding changes the encoding of the data object with the handle dh to enc.

Function: gpgme_error_t gpgme_data_set_flag (gpgme_data_t dh, const char *name, const char *value)

SINCE: 1.7.0

Some minor properties of the data object can be controlled with flags set by this function. The properties are identified by the following values for name:

size-hint

The value is a decimal number with the length gpgme shall assume for this data object. This is useful if the data is provided by callbacks or via file descriptors but the applications knows the total size of the data. If this is set the OpenPGP engine may use this to decide on buffer allocation strategies and to provide a total value for its progress information.

io-buffer-size

The value is a decimal number with the length of internal buffers to used for internal I/O operations. The value is capped at 1048576 (1 MiB). In certain environments large buffers can yield a performance boost for callback bases data object, but the details depend a lot on the circumstances and the operating system. This flag may only be set once and must be set before any actual I/O happens ion the data objects.

sensitive

If the numeric value is not 0 the data object is considered to contain sensitive information like passwords or key material. If this is set the internal buffers are securely overwritten with zeroes by gpgme_data_release.

This function returns 0 on success.