Next: , Previous: , Up: Context Attributes   [Contents][Index]

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:


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.


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.


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.


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


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.


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.


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.


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.


SINCE: 1.2.0

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


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.

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.

Next: , Previous: , Up: Context Attributes   [Contents][Index]