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 symbol specifies that the local
keyring should be searched for keys in the keylisting operation. This
is the default.
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 dependant on the crypto engine used and
whether it is combined with
example, it can be a remote keyserver or LDAP certificate server.
GPGME_KEYLIST_MODE_SIGS symbol specifies that the key
signatures should be included in the listed keys.
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
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_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.
GPGME_KEYLIST_MODE_EPHEMERAL symbol specifies that keys
flagged as ephemeral are included in the listing.
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_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.
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
operation to only affect the desired bits (and leave all others
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.