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.