File: gpgme.info,  Node: Deprecated Functions,  Next: Library Copying,  Prev: Debugging,  Up: Top

Appendix C Deprecated Functions
*******************************

For backward compatibility GPGME has a number of functions, data types
and constants which are deprecated and should not be used anymore.  We
document here those which are really old to help understanding old code
and to allow migration to their modern counterparts.

   *Warning:* These interfaces will be removed in a future version of
GPGME.

 -- Function: void gpgme_key_release (gpgme_key_t KEY)
     The function ‘gpgme_key_release’ is equivalent to
     ‘gpgme_key_unref’.

 -- Function: gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t CTX,
          gpgme_data_t KEYDATA, int *NR)
     SINCE: 0.3.9

     The function ‘gpgme_op_import_ext’ is equivalent to:

            gpgme_error_t err = gpgme_op_import (ctx, keydata);
            if (!err)
              {
                gpgme_import_result_t result = gpgme_op_import_result (ctx);
                *nr = result->considered;
              }

 -- Data type: gpgme_error_t (*gpgme_edit_cb_t) (void *HANDLE,
          gpgme_status_code_t STATUS, const char *ARGS, int FD)
     The ‘gpgme_edit_cb_t’ type is the type of functions which GPGME
     calls if it a key edit operation is on-going.  The status code
     STATUS and the argument line ARGS are passed through by GPGME from
     the crypto engine.  The file descriptor FD is -1 for normal status
     messages.  If STATUS indicates a command rather than a status
     message, the response to the command should be written to FD.  The
     HANDLE is provided by the user at start of operation.

     The function should return ‘GPG_ERR_FALSE’ if it did not handle the
     status code, ‘0’ for success, or any other error value.

 -- Function: gpgme_error_t gpgme_op_edit (gpgme_ctx_t CTX,
          gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
          gpgme_data_t OUT)
     SINCE: 0.3.9

     Note: This function is deprecated, please use ‘gpgme_op_interact’
     instead.

     The function ‘gpgme_op_edit’ processes the key KEY interactively,
     using the edit callback function FNC with the handle HANDLE.  The
     callback is invoked for every status and command request from the
     crypto engine.  The output of the crypto engine is written to the
     data object OUT.

     Note that the protocol between the callback function and the crypto
     engine is specific to the crypto engine and no further support in
     implementing this protocol correctly is provided by GPGME.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the edit
     operation completes successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY
     is not a valid pointer, and any error returned by the crypto engine
     or the edit callback handler.

 -- Function: gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t CTX,
          gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
          gpgme_data_t OUT)

     SINCE: 0.3.9

     Note: This function is deprecated, please use
     ‘gpgme_op_interact_start’ instead.

     The function ‘gpgme_op_edit_start’ initiates a ‘gpgme_op_edit’
     operation.  It can be completed by calling ‘gpgme_wait’ on the
     context.  *Note Waiting For Completion::.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
     operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX
     or KEY is not a valid pointer.

 -- Function: gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t CTX,
          gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
          gpgme_data_t OUT)
     Note: This function is deprecated, please use ‘gpgme_op_interact’
     with the flag ‘GPGME_INTERACT_CARD’ instead.

     The function ‘gpgme_op_card_edit’ is analogous to ‘gpgme_op_edit’,
     but should be used to process the smart card corresponding to the
     key KEY.

 -- Function: gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t CTX,
          gpgme_key_t KEY, gpgme_edit_cb_t FNC, void *HANDLE,
          gpgme_data_t OUT)
     Note: This function is deprecated, please use
     ‘gpgme_op_interact_start’ with the flag ‘GPGME_INTERACT_CARD’
     instead.

     The function ‘gpgme_op_card_edit_start’ initiates a
     ‘gpgme_op_card_edit’ operation.  It can be completed by calling
     ‘gpgme_wait’ on the context.  *Note Waiting For Completion::.

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
     operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX
     or KEY is not a valid pointer.

 -- Function: gpgme_error_t gpgme_data_new_with_read_cb
          (gpgme_data_t *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
     ‘gpgme_data_t’ 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 the error code ‘GPG_ERR_NO_ERROR’ if the data
     object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or
     READFUNC is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough
     memory is available.

 -- Function: gpgme_error_t gpgme_data_rewind (gpgme_data_t DH)
     The function ‘gpgme_data_rewind’ is equivalent to:

            return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
              ? gpgme_error_from_errno (errno) : 0;

 -- Data type: gpgme_attr_t
     The ‘gpgme_attr_t’ type is used to specify a key or trust item
     attribute.  The following attributes are defined:

     ‘GPGME_ATTR_KEYID’
          This is the key ID of a sub key.  It is representable as a
          string.

     ‘GPGME_ATTR_FPR’
          This is the fingerprint of a sub key.  It is representable as
          a string.

     ‘GPGME_ATTR_ALGO’
          This is the crypto algorithm for which the sub key can be
          used.  It is representable as a string and as a number.  The
          numbers correspond to the ‘enum gcry_pk_algos’ values in the
          gcrypt library.

     ‘GPGME_ATTR_LEN’
          This is the key length of a sub key.  It is representable as a
          number.

     ‘GPGME_ATTR_CREATED’
          This is the timestamp at creation time of a sub key.  It is
          representable as a number.

     ‘GPGME_ATTR_EXPIRE’
          This is the expiration time of a sub key.  It is representable
          as a number.

     ‘GPGME_ATTR_USERID’
          This is a user ID. There can be more than one user IDs in a
          GPGME_KEY_T object.  The first one (with index 0) is the
          primary user ID. The user ID is representable as a number.

     ‘GPGME_ATTR_NAME’
          This is the name belonging to a user ID. It is representable
          as a string.

     ‘GPGME_ATTR_EMAIL’
          This is the email address belonging to a user ID. It is
          representable as a string.

     ‘GPGME_ATTR_COMMENT’
          This is the comment belonging to a user ID. It is
          representable as a string.

     ‘GPGME_ATTR_VALIDITY’
          This is the validity belonging to a user ID. It is
          representable as a string and as a number.  See below for a
          list of available validities.

     ‘GPGME_ATTR_UID_REVOKED’
          This specifies if a user ID is revoked.  It is representable
          as a number, and is ‘1’ if the user ID is revoked, and ‘0’
          otherwise.

     ‘GPGME_ATTR_UID_INVALID’
          This specifies if a user ID is invalid.  It is representable
          as a number, and is ‘1’ if the user ID is invalid, and ‘0’
          otherwise.

     ‘GPGME_ATTR_TYPE’
          This returns information about the type of key.  For the
          string function this will eother be "PGP" or "X.509".  The
          integer function returns 0 for PGP and 1 for X.509.

     ‘GPGME_ATTR_IS_SECRET’
          This specifies if the key is a secret key.  It is
          representable as a number, and is ‘1’ if the key is revoked,
          and ‘0’ otherwise.

     ‘GPGME_ATTR_KEY_REVOKED’
          This specifies if a sub key is revoked.  It is representable
          as a number, and is ‘1’ if the key is revoked, and ‘0’
          otherwise.

     ‘GPGME_ATTR_KEY_INVALID’
          This specifies if a sub key is invalid.  It is representable
          as a number, and is ‘1’ if the key is invalid, and ‘0’
          otherwise.

     ‘GPGME_ATTR_KEY_EXPIRED’
          This specifies if a sub key is expired.  It is representable
          as a number, and is ‘1’ if the key is expired, and ‘0’
          otherwise.

     ‘GPGME_ATTR_KEY_DISABLED’
          This specifies if a sub key is disabled.  It is representable
          as a number, and is ‘1’ if the key is disabled, and ‘0’
          otherwise.

     ‘GPGME_ATTR_KEY_CAPS’
          This is a description of the capabilities of a sub key.  It is
          representable as a string.  The string contains the letter “e”
          if the key can be used for encryption, “s” if the key can be
          used for signatures, and “c” if the key can be used for
          certifications.

     ‘GPGME_ATTR_CAN_ENCRYPT’
          This specifies if a sub key can be used for encryption.  It is
          representable as a number, and is ‘1’ if the sub key can be
          used for encryption, and ‘0’ otherwise.

     ‘GPGME_ATTR_CAN_SIGN’
          This specifies if a sub key can be used to create data
          signatures.  It is representable as a number, and is ‘1’ if
          the sub key can be used for signatures, and ‘0’ otherwise.

     ‘GPGME_ATTR_CAN_CERTIFY’
          This specifies if a sub key can be used to create key
          certificates.  It is representable as a number, and is ‘1’ if
          the sub key can be used for certifications, and ‘0’ otherwise.

     ‘GPGME_ATTR_SERIAL’
          The X.509 issuer serial attribute of the key.  It is
          representable as a string.

     ‘GPGME_ATTR_ISSUE’
          The X.509 issuer name attribute of the key.  It is
          representable as a string.

     ‘GPGME_ATTR_CHAINID’
          The X.509 chain ID can be used to build the certification
          chain.  It is representable as a string.

 -- Function: const char * gpgme_key_get_string_attr (gpgme_key_t KEY,
          gpgme_attr_t WHAT, const void *RESERVED, int IDX)
     The function ‘gpgme_key_get_string_attr’ returns the value of the
     string-representable attribute WHAT of key KEY.  If the attribute
     is an attribute of a sub key or an user ID, IDX specifies the sub
     key or user ID of which the attribute value is returned.  The
     argument RESERVED is reserved for later use and should be ‘NULL’.

     The string returned is only valid as long as the key is valid.

     The function returns ‘0’ if an attribute can’t be returned as a
     string, KEY is not a valid pointer, IDX out of range, or RESERVED
     not ‘NULL’.

 -- Function: unsigned long gpgme_key_get_ulong_attr (gpgme_key_t KEY,
          gpgme_attr_t WHAT, const void *RESERVED, int IDX)
     The function ‘gpgme_key_get_ulong_attr’ returns the value of the
     number-representable attribute WHAT of key KEY.  If the attribute
     is an attribute of a sub key or an user ID, IDX specifies the sub
     key or user ID of which the attribute value is returned.  The
     argument RESERVED is reserved for later use and should be ‘NULL’.

     The function returns ‘0’ if the attribute can’t be returned as a
     number, KEY is not a valid pointer, IDX out of range, or RESERVED
     not ‘NULL’.

   The signatures on a key are only available if the key was retrieved
via a listing operation with the ‘GPGME_KEYLIST_MODE_SIGS’ mode enabled,
because it is expensive to retrieve all signatures of a key.

   So, before using the below interfaces to retrieve the signatures on a
key, you have to make sure that the key was listed with signatures
enabled.  One convenient, but blocking, way to do this is to use the
function ‘gpgme_get_key’.

 -- Data type: gpgme_attr_t
     The ‘gpgme_attr_t’ type is used to specify a key signature
     attribute.  The following attributes are defined:

     ‘GPGME_ATTR_KEYID’
          This is the key ID of the key which was used for the
          signature.  It is representable as a string.

     ‘GPGME_ATTR_ALGO’
          This is the crypto algorithm used to create the signature.  It
          is representable as a string and as a number.  The numbers
          correspond to the ‘enum gcry_pk_algos’ values in the gcrypt
          library.

     ‘GPGME_ATTR_CREATED’
          This is the timestamp at creation time of the signature.  It
          is representable as a number.

     ‘GPGME_ATTR_EXPIRE’
          This is the expiration time of the signature.  It is
          representable as a number.

     ‘GPGME_ATTR_USERID’
          This is the user ID associated with the signing key.  The user
          ID is representable as a number.

     ‘GPGME_ATTR_NAME’
          This is the name belonging to a user ID. It is representable
          as a string.

     ‘GPGME_ATTR_EMAIL’
          This is the email address belonging to a user ID. It is
          representable as a string.

     ‘GPGME_ATTR_COMMENT’
          This is the comment belonging to a user ID. It is
          representable as a string.

     ‘GPGME_ATTR_KEY_REVOKED’
          This specifies if a key signature is a revocation signature.
          It is representable as a number, and is ‘1’ if the key is
          revoked, and ‘0’ otherwise.

     ‘GPGME_ATTR_SIG_CLASS’
          This specifies the signature class of a key signature.  It is
          representable as a number.  The meaning is specific to the
          crypto engine.

     ‘GPGME_ATTR_SIG_CLASS’
          This specifies the signature class of a key signature.  It is
          representable as a number.  The meaning is specific to the
          crypto engine.

     ‘GPGME_ATTR_SIG_STATUS’
          This is the same value as returned by ‘gpgme_get_sig_status’.

 -- Function: const char * gpgme_key_sig_get_string_attr
          (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT,
          const void *RESERVED, int IDX)
     The function ‘gpgme_key_sig_get_string_attr’ returns the value of
     the string-representable attribute WHAT of the signature IDX on the
     user ID UID_IDX in the key KEY.  The argument RESERVED is reserved
     for later use and should be ‘NULL’.

     The string returned is only valid as long as the key is valid.

     The function returns ‘0’ if an attribute can’t be returned as a
     string, KEY is not a valid pointer, UID_IDX or IDX out of range, or
     RESERVED not ‘NULL’.

 -- Function: unsigned long gpgme_key_sig_get_ulong_attr
          (gpgme_key_t KEY, int UID_IDX, gpgme_attr_t WHAT,
          const void *RESERVED, int IDX)
     The function ‘gpgme_key_sig_get_ulong_attr’ returns the value of
     the number-representable attribute WHAT of the signature IDX on the
     user ID UID_IDX in the key KEY.  The argument RESERVED is reserved
     for later use and should be ‘NULL’.

     The function returns ‘0’ if an attribute can’t be returned as a
     string, KEY is not a valid pointer, UID_IDX or IDX out of range, or
     RESERVED not ‘NULL’.

 -- Data type: enum gpgme_sig_stat_t
     The ‘gpgme_sig_stat_t’ type holds the result of a signature check,
     or the combined result of all signatures.  The following results
     are possible:

     ‘GPGME_SIG_STAT_NONE’
          This status should not occur in normal operation.

     ‘GPGME_SIG_STAT_GOOD’
          This status indicates that the signature is valid.  For the
          combined result this status means that all signatures are
          valid.

     ‘GPGME_SIG_STAT_GOOD_EXP’
          This status indicates that the signature is valid but expired.
          For the combined result this status means that all signatures
          are valid and expired.

     ‘GPGME_SIG_STAT_GOOD_EXPKEY’
          This status indicates that the signature is valid but the key
          used to verify the signature has expired.  For the combined
          result this status means that all signatures are valid and all
          keys are expired.

     ‘GPGME_SIG_STAT_BAD’
          This status indicates that the signature is invalid.  For the
          combined result this status means that all signatures are
          invalid.

     ‘GPGME_SIG_STAT_NOKEY’
          This status indicates that the signature could not be verified
          due to a missing key.  For the combined result this status
          means that all signatures could not be checked due to missing
          keys.

     ‘GPGME_SIG_STAT_NOSIG’
          This status indicates that the signature data provided was not
          a real signature.

     ‘GPGME_SIG_STAT_ERROR’
          This status indicates that there was some other error which
          prevented the signature verification.

     ‘GPGME_SIG_STAT_DIFF’
          For the combined result this status means that at least two
          signatures have a different status.  You can get each key’s
          status with ‘gpgme_get_sig_status’.

 -- Function: const char * gpgme_get_sig_status (gpgme_ctx_t CTX,
          int IDX, gpgme_sig_stat_t *R_STAT, time_t *R_CREATED)
     The function ‘gpgme_get_sig_status’ is equivalent to:

            gpgme_verify_result_t result;
            gpgme_signature_t sig;

            result = gpgme_op_verify_result (ctx);
            sig = result->signatures;

            while (sig && idx)
              {
                sig = sig->next;
                idx--;
              }
            if (!sig || idx)
              return NULL;

            if (r_stat)
              {
                switch (gpg_err_code (sig->status))
          	{
          	case GPG_ERR_NO_ERROR:
          	  *r_stat = GPGME_SIG_STAT_GOOD;
          	  break;

          	case GPG_ERR_BAD_SIGNATURE:
          	  *r_stat = GPGME_SIG_STAT_BAD;
          	  break;

          	case GPG_ERR_NO_PUBKEY:
          	  *r_stat = GPGME_SIG_STAT_NOKEY;
          	  break;

          	case GPG_ERR_NO_DATA:
          	  *r_stat = GPGME_SIG_STAT_NOSIG;
          	  break;

          	case GPG_ERR_SIG_EXPIRED:
          	  *r_stat = GPGME_SIG_STAT_GOOD_EXP;
          	  break;

          	case GPG_ERR_KEY_EXPIRED:
          	  *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
          	  break;

          	default:
          	  *r_stat = GPGME_SIG_STAT_ERROR;
          	  break;
          	}
              }
            if (r_created)
              *r_created = sig->timestamp;
            return sig->fpr;

 -- Function: const char * gpgme_get_sig_string_attr (gpgme_ctx_t CTX,
          int IDX, gpgme_attr_t WHAT, int WHATIDX)
     The function ‘gpgme_get_sig_string_attr’ is equivalent to:

            gpgme_verify_result_t result;
            gpgme_signature_t sig;

            result = gpgme_op_verify_result (ctx);
            sig = result->signatures;

            while (sig && idx)
              {
                sig = sig->next;
                idx--;
              }
            if (!sig || idx)
              return NULL;

            switch (what)
              {
              case GPGME_ATTR_FPR:
                return sig->fpr;

              case GPGME_ATTR_ERRTOK:
                if (whatidx == 1)
                  return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
                else
          	return "";
              default:
                break;
              }

            return NULL;

 -- Function: const char * gpgme_get_sig_ulong_attr (gpgme_ctx_t CTX,
          int IDX, gpgme_attr_t WHAT, int WHATIDX)
     The function ‘gpgme_get_sig_ulong_attr’ is equivalent to:

            gpgme_verify_result_t result;
            gpgme_signature_t sig;

            result = gpgme_op_verify_result (ctx);
            sig = result->signatures;

            while (sig && idx)
              {
                sig = sig->next;
                idx--;
              }
            if (!sig || idx)
              return 0;

            switch (what)
              {
              case GPGME_ATTR_CREATED:
                return sig->timestamp;

              case GPGME_ATTR_EXPIRE:
                return sig->exp_timestamp;

              case GPGME_ATTR_VALIDITY:
                return (unsigned long) sig->validity;

              case GPGME_ATTR_SIG_STATUS:
                switch (sig->status)
          	{
          	case GPG_ERR_NO_ERROR:
          	  return GPGME_SIG_STAT_GOOD;

          	case GPG_ERR_BAD_SIGNATURE:
          	  return GPGME_SIG_STAT_BAD;

          	case GPG_ERR_NO_PUBKEY:
          	  return GPGME_SIG_STAT_NOKEY;

          	case GPG_ERR_NO_DATA:
          	  return GPGME_SIG_STAT_NOSIG;

          	case GPG_ERR_SIG_EXPIRED:
          	  return GPGME_SIG_STAT_GOOD_EXP;

          	case GPG_ERR_KEY_EXPIRED:
          	  return GPGME_SIG_STAT_GOOD_EXPKEY;

          	default:
          	  return GPGME_SIG_STAT_ERROR;
          	}

              case GPGME_ATTR_SIG_SUMMARY:
                return sig->summary;

              default:
                break;
              }
            return 0;

 -- Function: const char * gpgme_get_sig_key (gpgme_ctx_t CTX, int IDX,
          gpgme_key_t *R_KEY)
     The function ‘gpgme_get_sig_key’ is equivalent to:

            gpgme_verify_result_t result;
            gpgme_signature_t sig;

            result = gpgme_op_verify_result (ctx);
            sig = result->signatures;

            while (sig && idx)
              {
                sig = sig->next;
                idx--;
              }
            if (!sig || idx)
              return gpg_error (GPG_ERR_EOF);

            return gpgme_get_key (ctx, sig->fpr, r_key, 0);