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.