File: gpgme.info,  Node: Key Listing Mode,  Next: Passphrase Callback,  Prev: Included Certificates,  Up: Context Attributes

7.4.9 Key Listing Mode
----------------------

 -- Function: gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t CTX,
          gpgme_keylist_mode_t MODE)
     The function ‘gpgme_set_keylist_mode’ changes the default behaviour
     of the key listing functions.  The value in MODE is a bitwise-or
     combination of one or multiple of the following bit values:

     ‘GPGME_KEYLIST_MODE_LOCAL’
          The ‘GPGME_KEYLIST_MODE_LOCAL’ symbol specifies that the local
          keyring should be searched for keys in the keylisting
          operation.  This is the default.

          Using only this option results in a ‘--list-keys’.

     ‘GPGME_KEYLIST_MODE_EXTERN’
          The ‘GPGME_KEYLIST_MODE_EXTERN’ symbol specifies that an
          external source should be searched for keys in the keylisting
          operation.  The type of external source is dependent on the
          crypto engine used and whether it is combined with
          ‘GPGME_KEYLIST_MODE_LOCAL’.  For example, it can be a remote
          keyserver or LDAP certificate server.

          Using only this option results in a ‘--search-keys’ for
          ‘GPGME_PROTOCOL_OpenPGP’ and something similar to
          ‘--list-external-keys’ for ‘GPGME_PROTOCOL_CMS’.

     ‘GPGME_KEYLIST_MODE_LOCATE’
          This is a shortcut for the combination of
          ‘GPGME_KEYLIST_MODE_LOCAL’ and ‘GPGME_KEYLIST_MODE_EXTERN’,
          which results in a ‘--locate-keys’ for
          ‘GPGME_PROTOCOL_OpenPGP’.

     ‘GPGME_KEYLIST_MODE_SIGS’
          The ‘GPGME_KEYLIST_MODE_SIGS’ symbol specifies that the key
          signatures should be included in the listed keys.

     ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’
          SINCE: 1.1.1

          The ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’ symbol specifies that
          the signature notations on key signatures should be included
          in the listed keys.  This only works if
          ‘GPGME_KEYLIST_MODE_SIGS’ is also enabled.

     ‘GPGME_KEYLIST_MODE_WITH_TOFU’
          SINCE: 1.7.0

          The ‘GPGME_KEYLIST_MODE_WITH_TOFU’ symbol specifies that
          information pertaining to the TOFU trust model should be
          included in the listed keys.

     ‘GPGME_KEYLIST_MODE_WITH_KEYGRIP’
          SINCE: 1.14.0

          The ‘GPGME_KEYLIST_MODE_WITH_KEYRIP’ symbol specifies that the
          keygrip is always included in the listing.  The default
          depends on the version of the backend and the used protocol.

     ‘GPGME_KEYLIST_MODE_WITH_SECRET’
          SINCE: 1.5.1

          The ‘GPGME_KEYLIST_MODE_WITH_SECRET’ returns information about
          the presence of a corresponding secret key in a public key
          listing.  A public key listing with this mode is slower than a
          standard listing but can be used instead of a second run to
          list the secret keys.  This is only supported for GnuPG
          versions >= 2.1.  Note that using this option also makes sure
          that the keygrip is available in the output.

     ‘GPGME_KEYLIST_MODE_EPHEMERAL’
          SINCE: 1.2.0

          The ‘GPGME_KEYLIST_MODE_EPHEMERAL’ symbol specifies that keys
          flagged as ephemeral are included in the listing.

     ‘GPGME_KEYLIST_MODE_WITH_V5FPR’
          SINCE: 1.23.0

          The ‘GPGME_KEYLIST_MODE_WITH_V5FPR’ symbol specifies that key
          listings shall also provide v5 style fingerprints for v4
          OpenPGp keys.

     ‘GPGME_KEYLIST_MODE_VALIDATE’
          SINCE: 0.4.5

          The ‘GPGME_KEYLIST_MODE_VALIDATE’ symbol specifies that the
          backend should do key or certificate validation and not just
          get the validity information from an internal cache.  This
          might be an expensive operation and is in general not useful.
          Currently only implemented for the S/MIME backend and ignored
          for other backends.

     ‘GPGME_KEYLIST_MODE_FORCE_EXTERN’
          SINCE: 1.18.0

          The ‘GPGME_KEYLIST_MODE_FORCE_EXTERN’ symbol specifies that
          only external sources should be searched for keys in the
          keylisting operation.  If used in combination with
          ‘GPGME_KEYLIST_MODE_LOCATE’, the keylisting results in a
          ‘--locate-external-keys’ for ‘GPGME_PROTOCOL_OpenPGP’.  The
          combination with ‘GPGME_KEYLIST_MODE_LOCAL’, but without
          ‘GPGME_KEYLIST_MODE_EXTERN’ is not allowed.  Currently only
          implemented for the OpenPGP backend and ignored for other
          backends.

     ‘GPGME_KEYLIST_MODE_LOCATE_EXTERNAL’
          SINCE: 1.18.0

          This is a shortcut for the combination of
          ‘GPGME_KEYLIST_MODE_LOCATE’ and
          ‘GPGME_KEYLIST_MODE_FORCE_EXTERN’, which results in a
          ‘--locate-external-keys’ for ‘GPGME_PROTOCOL_OpenPGP’.

     At least one of ‘GPGME_KEYLIST_MODE_LOCAL’ and
     ‘GPGME_KEYLIST_MODE_EXTERN’ must be specified.  For future binary
     compatibility, you should get the current mode with
     ‘gpgme_get_keylist_mode’ and modify it by setting or clearing the
     appropriate bits, and then using that calculated value in the
     ‘gpgme_set_keylisting_mode’ operation.  This will leave all other
     bits in the mode value intact (in particular those that are not
     used in the current version of the library).

     The function returns the error code ‘GPG_ERR_NO_ERROR’ if the mode
     could be set correctly, and ‘GPG_ERR_INV_VALUE’ if CTX is not a
     valid pointer or MODE is not a valid mode.

 -- Function: gpgme_keylist_mode_t gpgme_get_keylist_mode
          (gpgme_ctx_t CTX)
     The function ‘gpgme_get_keylist_mode’ returns the current key
     listing mode of the context CTX.  This value can then be modified
     and used in a subsequent ‘gpgme_set_keylist_mode’ operation to only
     affect the desired bits (and leave all others intact).

     The function returns 0 if CTX is not a valid pointer, and the
     current mode otherwise.  Note that 0 is not a valid mode value.