File: gpgme.info, Node: Listing Keys, Next: Information About Keys, Prev: Key objects, Up: Key Management 7.5.2 Listing Keys ------------------ -- Function: gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t CTX, const char *PATTERN, int SECRET_ONLY) The function ‘gpgme_op_keylist_start’ initiates a key listing operation inside the context CTX. It sets everything up so that subsequent invocations of ‘gpgme_op_keylist_next’ return the keys in the list. If PATTERN is ‘NULL’, all available keys are returned. Otherwise, PATTERN contains an engine specific expression that is used to limit the list to all keys matching the pattern. Note that the total length of the pattern is restricted to an engine-specific maximum (a couple of hundred characters are usually accepted). The pattern should be used to restrict the search to a certain common name or user, not to list many specific keys at once by listing their fingerprints or key IDs. If SECRET_ONLY is not ‘0’, the list is restricted to secret keys only. The context will be busy until either all keys are received (and ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or ‘gpgme_op_keylist_end’ is called to finish the operation. The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is not a valid pointer, and passes through any errors that are reported by the crypto engine support routines. -- Function: gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t CTX, const char *PATTERN[], int SECRET_ONLY, int RESERVED) The function ‘gpgme_op_keylist_ext_start’ initiates an extended key listing operation inside the context CTX. It sets everything up so that subsequent invocations of ‘gpgme_op_keylist_next’ return the keys in the list. If PATTERN or *PATTERN is ‘NULL’, all available keys are returned. Otherwise, PATTERN is a ‘NULL’ terminated array of strings that are used to limit the list to all keys matching at least one of the patterns verbatim. Note that the total length of all patterns is restricted to an engine-specific maximum (the exact limit also depends on the number of patterns and amount of quoting required, but a couple of hundred characters are usually accepted). Patterns should be used to restrict the search to a certain common name or user, not to list many specific keys at once by listing their fingerprints or key IDs. If SECRET_ONLY is not ‘0’, the list is restricted to secret keys only. The value of RESERVED must be ‘0’. The context will be busy until either all keys are received (and ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or ‘gpgme_op_keylist_end’ is called to finish the operation. The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is not a valid pointer, and passes through any errors that are reported by the crypto engine support routines. -- Function: gpgme_error_t gpgme_op_keylist_from_data_start (gpgme_ctx_t CTX, gpgme_data_t DATA, int RESERVED) SINCE: 1.8.0 The function ‘gpgme_op_keylist_from_data_start’ initiates a key listing operation inside the context CTX. In contrast to the other key listing operation the keys are read from the supplied DATA and not from the local key database. The keys are also not imported into the local key database. The function sets everything up so that subsequent invocations of ‘gpgme_op_keylist_next’ return the keys from DATA. The value of RESERVED must be ‘0’. This function requires at least GnuPG version 2.1.14 and currently works only with OpenPGP keys. The context will be busy until either all keys are received (and ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or ‘gpgme_op_keylist_end’ is called to finish the operation. While the context is busy DATA may not be released. The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is not a valid pointer, and passes through any errors that are reported by the crypto engine support routines. -- Function: gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t CTX, gpgme_key_t *R_KEY) The function ‘gpgme_op_keylist_next’ returns the next key in the list created by a previous ‘gpgme_op_keylist_start’ operation in the context CTX. The key will have one reference for the user. *Note Manipulating Keys::. This is the only way to get at ‘gpgme_key_t’ objects in GPGME. If the last key in the list has already been returned, ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’. The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or R_KEY is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if there is not enough memory for the operation. -- Function: gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t CTX) The function ‘gpgme_op_keylist_end’ ends a pending key list operation in the context CTX. After the operation completed successfully, the result of the key listing operation can be retrieved with ‘gpgme_op_keylist_result’. The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if at some time during the operation there was not enough memory available. The following example illustrates how all keys containing a certain string (‘g10code’) can be listed with their key ID and the name and email address of the main user ID: gpgme_ctx_t ctx; gpgme_key_t key; gpgme_error_t err = gpgme_new (&ctx); if (!err) { err = gpgme_op_keylist_start (ctx, "g10code", 0); while (!err) { err = gpgme_op_keylist_next (ctx, &key); if (err) break; printf ("%s:", key->subkeys->keyid); if (key->uids && key->uids->name) printf (" %s", key->uids->name); if (key->uids && key->uids->email) printf (" <%s>", key->uids->email); putchar ('\n'); gpgme_key_release (key); } gpgme_release (ctx); } if (gpg_err_code (err) != GPG_ERR_EOF) { fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err)); exit (1); } -- Data type: gpgme_keylist_result_t This is a pointer to a structure used to store the result of a ‘gpgme_op_keylist_*’ operation. After successfully ending a key listing operation, you can retrieve the pointer to the result with ‘gpgme_op_keylist_result’. The structure contains the following member: ‘unsigned int truncated : 1’ This is true if the crypto backend had to truncate the result, and less than the desired keys could be listed. -- Function: gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t CTX) The function ‘gpgme_op_keylist_result’ returns a ‘gpgme_keylist_result_t’ pointer to a structure holding the result of a ‘gpgme_op_keylist_*’ operation. The pointer is only valid if the last operation on the context was a key listing operation, and if this operation finished successfully. The returned pointer is only valid until the next operation is started on the context. In a simple program, for which a blocking operation is acceptable, the following function can be used to retrieve a single key. -- Function: gpgme_error_t gpgme_get_key (gpgme_ctx_t CTX, const char *FPR, gpgme_key_t *R_KEY, int SECRET) The function ‘gpgme_get_key’ gets the key with the fingerprint (or key ID) FPR from the crypto backend and return it in R_KEY. If SECRET is true, get the secret key. The currently active keylist mode is used to retrieve the key. The key will have one reference for the user. If the key is not found in the keyring, ‘gpgme_get_key’ returns the error code ‘GPG_ERR_EOF’ and *R_KEY will be set to ‘NULL’. The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or R_KEY is not a valid pointer or FPR is not a fingerprint or key ID, ‘GPG_ERR_AMBIGUOUS_NAME’ if the key ID was not a unique specifier for a key, and ‘GPG_ERR_ENOMEM’ if at some time during the operation there was not enough memory available.