— 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_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. See 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_next 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.

     gpgme_ctx_t ctx;
     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: %s <%s>\n", key->keyid, key->name, key->email);
             gpgme_key_release (key);
           }
         gpgme_release (ctx);
       }
     if (gpg_err_code (err) != GPG_ERR_EOF)
       {
         fprintf (stderr, "%s: can not list keys: %s\n",
                  argv[0], 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.

— 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_NO_ERROR 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.