GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Clarify import keys operation.

Browse Source 
* 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 <mb@g10code.com>
GnuPG-bug-id: 3215
This commit is contained in:
Marcus Brinkmann 2017-08-10 16:50:11 +02:00
parent 274609bace
commit dfb3ca8568
2 changed files with 19 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/gpgme.texi
View File

@ -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}})

13
src/import.c
View File

@ -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