From dfb3ca85680534b3885ab04d3fba4752c5a6f998 Mon Sep 17 00:00:00 2001 From: Marcus Brinkmann Date: Thu, 10 Aug 2017 16:50:11 +0200 Subject: [PATCH] doc: Clarify import keys operation. * doc/gpgme.texi (gpgme_op_import_start): Fix grammar. (gpgme_op_import_keys): Clarify some wording and fix result. * src/import.c (gpgme_op_import_keys): Clarify comment. Signed-off-by: Marcus Brinkmann GnuPG-bug-id: 3215 --- doc/gpgme.texi | 28 +++++++++++++--------------- src/import.c | 13 ++++++------- 2 files changed, 19 insertions(+), 22 deletions(-) diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 37760afa..bf846293 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -4449,34 +4449,32 @@ The function @code{gpgme_op_import_start} initiates a The function returns the error code @code{GPG_ERR_NO_ERROR} if the import could be started successfully, @code{GPG_ERR_INV_VALUE} if -@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer, -and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer. +@var{ctx} or @var{keydata} is not a valid pointer, and +@code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer. @end deftypefun @deftypefun gpgme_error_t gpgme_op_import_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}}) -The function @code{gpgme_op_import_keys} adds the keys described by the -@code{NULL} terminated array @var{keys} to the key ring of the crypto -engine used by @var{ctx}. This function is the general interface to -move a key from one crypto engine to another as long as they are -compatible. In particular it is used to actually import and make keys -permanent which have been retrieved from an external source (i.e. using -@code{GPGME_KEYLIST_MODE_EXTERN}). @footnote{Thus it is a replacement -for the usual workaround of exporting and then importing a key to make -an X.509 key permanent.} +The function @code{gpgme_op_import_keys} adds the keys described by +the @code{NULL} terminated array @var{keys} to the key ring of the +crypto engine used by @var{ctx}. It is used to actually import and +make keys permanent which have been retrieved from an external source +(i.e. using @code{GPGME_KEYLIST_MODE_EXTERN}). @footnote{Thus it is a +replacement for the usual workaround of exporting and then importing a +key to make an X.509 key permanent.} Only keys of the currently selected protocol of @var{ctx} are considered for import. Other keys specified by the @var{keys} are ignored. As of now all considered keys must have been retrieved using -the same method, that is the used key listing mode must be identical. +the same method, i.e. the used key listing mode must be identical. After the operation completed successfully, the result can be retrieved with @code{gpgme_op_import_result}. The function returns the error code @code{GPG_ERR_NO_ERROR} if the import was completed successfully, @code{GPG_ERR_INV_VALUE} if -@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer, -@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and -@code{GPG_ERR_NO_DATA} if no keys are considered for export. +@var{ctx} is not a valid pointer, @code{GPG_ERR_CONFLICT} if the key +listing mode does not match, and @code{GPG_ERR_NO_DATA} if no keys are +considered for export. @end deftypefun @deftypefun gpgme_error_t gpgme_op_import_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}}) diff --git a/src/import.c b/src/import.c index 4173fe91..386ca722 100644 --- a/src/import.c +++ b/src/import.c @@ -392,13 +392,12 @@ gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t *keys) } -/* Import the keys from the array KEYS into the keyring. This - function allows to move a key from one engine to another as long as - they are compatible. In particular it is used to actually import - keys retrieved from an external source (i.e. using - GPGME_KEYLIST_MODE_EXTERN). It replaces the old workaround of - exporting and then importing a key as used to make an X.509 key - permanent. This function automagically does the right thing. +/* Import the keys from the array KEYS into the keyring. In + particular it is used to actually import keys retrieved from an + external source (i.e. using GPGME_KEYLIST_MODE_EXTERN). It + replaces the old workaround of exporting and then importing a key + as used to make an X.509 key permanent. This function + automagically does the right thing. KEYS is a NULL terminated array of gpgme key objects. The result is the usual import result structure. Only keys matching the