Next: Information About Keys, Previous: Key objects, Up: Key Management [Contents][Index]
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.
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.
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.
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.
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);
}
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 : 1This is true if the crypto backend had to truncate the result, and less than the desired keys could be listed.
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.
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.
Next: Information About Keys, Previous: Key objects, Up: Key Management [Contents][Index]