File: gpgme.info, Node: Data Buffer Meta-Data, Next: Data Buffer Convenience, Prev: Data Buffer I/O Operations, Up: Manipulating Data Buffers 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. If a signed or encrypted archive is created, then the file name will be interpreted as the base directory for the relative paths of the files and directories to put into the archive. This corresponds to the –directory option of gpgtar. 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.