This is gpgme.info, produced by makeinfo version 6.3 from gpgme.texi.

Copyright © 2002–2008, 2010, 2012–2017 g10 Code GmbH.

     Permission is granted to copy, distribute and/or modify this

     document under the terms of the GNU General Public License as

     published by the Free Software Foundation; either version 3 of the

     License, or (at your option) any later version.  The text of the

     license can be found in the section entitled “Copying”.

   This document is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General

Public License for more details.

INFO-DIR-SECTION GNU Libraries

START-INFO-DIR-ENTRY

* GPGME: (gpgme).          Adding support for cryptography to your program.

END-INFO-DIR-ENTRY

   This file documents the GPGME library.

   This is Edition 1.10.0, last updated 8 December 2017, of ‘The ‘GnuPG

Made Easy’ Reference Manual’, for Version 1.10.0.

   Copyright © 2002–2008, 2010, 2012–2017 g10 Code GmbH.

     Permission is granted to copy, distribute and/or modify this

     document under the terms of the GNU General Public License as

     published by the Free Software Foundation; either version 3 of the

     License, or (at your option) any later version.  The text of the

     license can be found in the section entitled “Copying”.

   This document is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General

Public License for more details.

?

File: gpgme.info,  Node: Debugging,  Next: Deprecated Functions,  Prev: UI Server Protocol,  Up: Top

Appendix B How to solve problems

********************************

Everyone knows that software often does not do what it should do and

thus there is a need to track down problems.  This is in particular true

for applications using a complex library like GPGME and of course also

for the library itself.  Here we give a few hints on how to solve such

problems.

   First of all you should make sure that the keys you want to use are

installed in the GnuPG engine and are usable.  Thus the first test is to

run the desired operation using ‘gpg’ or ‘gpgsm’ on the command line.

If you can’t figure out why things don’t work, you may use GPGME’s built

in trace feature.  This feature is either enabled using the environment

variable ‘GPGME_DEBUG’ or, if this is not possible, by calling the

function ‘gpgme_set_global_flag’.  The value is the trace level and an

optional file name.  If no file name is given the trace output is

printed to ‘stderr’.

For example

     GPGME_DEBUG=9:/home/user/mygpgme.log

(Note that under Windows you use a semicolon in place of the colon to

separate the fields.)

   A trace level of 9 is pretty verbose and thus you may want to start

off with a lower level.  The exact definition of the trace levels and

the output format may change with any release; you need to check the

source code for details.  In any case the trace log should be helpful to

understand what is going going on.  Warning: The trace log may reveal

sensitive details like passphrases or other data you use in your

application.  If you are asked to send a log file, make sure that you

run your tests only with play data.

?

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: void gpgme_trust_item_release (gpgme_trust_item_t ITEM)

     The function ‘gpgme_trust_item_release’ is an alias for

     ‘gpgme_trust_item_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.

          For trust items, the trust item refers to the key with this

          ID.

     ‘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_OTRUST’

          XXX FIXME (also for trust items)

     ‘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.

          For trust items, this is the user ID associated with this

          trust item.

     ‘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.

          For trust items, this is the validity that is associated with

          this trust item.

     ‘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_LEVEL’

          This is the trust level of a trust item.

     ‘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.  It is

          also used for the type of a trust item.

     ‘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’.

   Trust items have attributes which can be queried using the interfaces

below.  The attribute identifiers are shared with those for key

attributes.  *Note Information About Keys::.

 -- Function: const char * gpgme_trust_item_get_string_attr

          (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT,

          const void *RESERVED, int IDX)

     The function ‘gpgme_trust_item_get_string_attr’ returns the value

     of the string-representable attribute WHAT of trust item ITEM.  The

     arguments IDX and RESERVED are reserved for later use and should be

     ‘0’ and ‘NULL’ respectively.

     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: int gpgme_trust_item_get_int_attr

          (gpgme_trust_item_t ITEM, gpgme_attr_t WHAT,

          const void *RESERVED, int IDX)

     The function ‘gpgme_trust_item_get_int_attr’ returns the value of

     the number-representable attribute WHAT of trust item ITEM.  If the

     attribute occurs more than once in the trust item, the index is

     specified by IDX.  However, currently no such attribute exists, so

     IDX should be ‘0’.  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’.

 -- 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 WAHT, 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);

?

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

GNU Lesser General Public License

*********************************

                      Version 2.1, February 1999

     Copyright © 1991, 1999 Free Software Foundation, Inc.

     59 Temple Place – Suite 330, Boston, MA 02111-1307, USA

     Everyone is permitted to copy and distribute verbatim copies

     of this license document, but changing it is not allowed.

     [This is the first released version of the Lesser GPL.  It also counts

     as the successor of the GNU Library Public License, version 2, hence the

     version number 2.1.]

Preamble

========

The licenses for most software are designed to take away your freedom to

share and change it.  By contrast, the GNU General Public Licenses are

intended to guarantee your freedom to share and change free software—to

make sure the software is free for all its users.

   This license, the Lesser General Public License, applies to some

specially designated software—typically libraries—of the Free Software

Foundation and other authors who decide to use it.  You can use it too,

but we suggest you first think carefully about whether this license or

the ordinary General Public License is the better strategy to use in any

particular case, based on the explanations below.

   When we speak of free software, we are referring to freedom of use,

not price.  Our General Public Licenses are designed to make sure that

you have the freedom to distribute copies of free software (and charge

for this service if you wish); that you receive source code or can get

it if you want it; that you can change the software and use pieces of it

in new free programs; and that you are informed that you can do these

things.

   To protect your rights, we need to make restrictions that forbid

distributors to deny you these rights or to ask you to surrender these

rights.  These restrictions translate to certain responsibilities for

you if you distribute copies of the library or if you modify it.

   For example, if you distribute copies of the library, whether gratis

or for a fee, you must give the recipients all the rights that we gave

you.  You must make sure that they, too, receive or can get the source

code.  If you link other code with the library, you must provide

complete object files to the recipients, so that they can relink them

with the library after making changes to the library and recompiling it.

And you must show them these terms so they know their rights.

   We protect your rights with a two-step method: (1) we copyright the

library, and (2) we offer you this license, which gives you legal

permission to copy, distribute and/or modify the library.

   To protect each distributor, we want to make it very clear that there

is no warranty for the free library.  Also, if the library is modified

by someone else and passed on, the recipients should know that what they

have is not the original version, so that the original author’s

reputation will not be affected by problems that might be introduced by

others.

   Finally, software patents pose a constant threat to the existence of

any free program.  We wish to make sure that a company cannot

effectively restrict the users of a free program by obtaining a

restrictive license from a patent holder.  Therefore, we insist that any

patent license obtained for a version of the library must be consistent

with the full freedom of use specified in this license.

   Most GNU software, including some libraries, is covered by the

ordinary GNU General Public License.  This license, the GNU Lesser

General Public License, applies to certain designated libraries, and is

quite different from the ordinary General Public License.  We use this

license for certain libraries in order to permit linking those libraries

into non-free programs.

   When a program is linked with a library, whether statically or using

a shared library, the combination of the two is legally speaking a

combined work, a derivative of the original library.  The ordinary

General Public License therefore permits such linking only if the entire

combination fits its criteria of freedom.  The Lesser General Public

License permits more lax criteria for linking other code with the

library.

   We call this license the “Lesser” General Public License because it

does _Less_ to protect the user’s freedom than the ordinary General

Public License.  It also provides other free software developers Less of

an advantage over competing non-free programs.  These disadvantages are

the reason we use the ordinary General Public License for many

libraries.  However, the Lesser license provides advantages in certain

special circumstances.

   For example, on rare occasions, there may be a special need to

encourage the widest possible use of a certain library, so that it

becomes a de-facto standard.  To achieve this, non-free programs must be

allowed to use the library.  A more frequent case is that a free library

does the same job as widely used non-free libraries.  In this case,

there is little to gain by limiting the free library to free software

only, so we use the Lesser General Public License.

   In other cases, permission to use a particular library in non-free

programs enables a greater number of people to use a large body of free

software.  For example, permission to use the GNU C Library in non-free

programs enables many more people to use the whole GNU operating system,

as well as its variant, the GNU/Linux operating system.

   Although the Lesser General Public License is Less protective of the

users’ freedom, it does ensure that the user of a program that is linked

with the Library has the freedom and the wherewithal to run that program

using a modified version of the Library.

   The precise terms and conditions for copying, distribution and

modification follow.  Pay close attention to the difference between a

“work based on the library” and a “work that uses the library”.  The

former contains code derived from the library, whereas the latter must

be combined with the library in order to run.

                   GNU LESSER GENERAL PUBLIC LICENSE

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License Agreement applies to any software library or other

     program which contains a notice placed by the copyright holder or

     other authorized party saying it may be distributed under the terms

     of this Lesser General Public License (also called “this License”).

     Each licensee is addressed as “you”.

     A “library” means a collection of software functions and/or data

     prepared so as to be conveniently linked with application programs

     (which use some of those functions and data) to form executables.

     The “Library”, below, refers to any such software library or work

     which has been distributed under these terms.  A “work based on the

     Library” means either the Library or any derivative work under

     copyright law: that is to say, a work containing the Library or a

     portion of it, either verbatim or with modifications and/or

     translated straightforwardly into another language.  (Hereinafter,

     translation is included without limitation in the term

     “modification”.)

     “Source code” for a work means the preferred form of the work for

     making modifications to it.  For a library, complete source code

     means all the source code for all modules it contains, plus any

     associated interface definition files, plus the scripts used to

     control compilation and installation of the library.

     Activities other than copying, distribution and modification are

     not covered by this License; they are outside its scope.  The act

     of running a program using the Library is not restricted, and

     output from such a program is covered only if its contents

     constitute a work based on the Library (independent of the use of

     the Library in a tool for writing it).  Whether that is true

     depends on what the Library does and what the program that uses the