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 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
import could be started successfully, @code{GPG_ERR_INV_VALUE} if import could be started successfully, @code{GPG_ERR_INV_VALUE} if
@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer, @var{ctx} or @var{keydata} is not a valid pointer, and
and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer. @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
@end deftypefun @end deftypefun
@deftypefun gpgme_error_t gpgme_op_import_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}}) @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 The function @code{gpgme_op_import_keys} adds the keys described by
@code{NULL} terminated array @var{keys} to the key ring of the crypto the @code{NULL} terminated array @var{keys} to the key ring of the
engine used by @var{ctx}. This function is the general interface to crypto engine used by @var{ctx}. It is used to actually import and
move a key from one crypto engine to another as long as they are make keys permanent which have been retrieved from an external source
compatible. In particular it is used to actually import and make keys (i.e. using @code{GPGME_KEYLIST_MODE_EXTERN}). @footnote{Thus it is a
permanent which have been retrieved from an external source (i.e. using replacement for the usual workaround of exporting and then importing a
@code{GPGME_KEYLIST_MODE_EXTERN}). @footnote{Thus it is a replacement key to make an X.509 key permanent.}
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 Only keys of the currently selected protocol of @var{ctx} are
considered for import. Other keys specified by the @var{keys} are considered for import. Other keys specified by the @var{keys} are
ignored. As of now all considered keys must have been retrieved using 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 After the operation completed successfully, the result can be
retrieved with @code{gpgme_op_import_result}. retrieved with @code{gpgme_op_import_result}.
The function returns the error code @code{GPG_ERR_NO_ERROR} if the The function returns the error code @code{GPG_ERR_NO_ERROR} if the
import was completed successfully, @code{GPG_ERR_INV_VALUE} if import was completed successfully, @code{GPG_ERR_INV_VALUE} if
@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer, @var{ctx} is not a valid pointer, @code{GPG_ERR_CONFLICT} if the key
@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and listing mode does not match, and @code{GPG_ERR_NO_DATA} if no keys are
@code{GPG_ERR_NO_DATA} if no keys are considered for export. considered for export.
@end deftypefun @end deftypefun
@deftypefun gpgme_error_t gpgme_op_import_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}}) @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 /* Import the keys from the array KEYS into the keyring. In
function allows to move a key from one engine to another as long as particular it is used to actually import keys retrieved from an
they are compatible. In particular it is used to actually import external source (i.e. using GPGME_KEYLIST_MODE_EXTERN). It
keys retrieved from an external source (i.e. using replaces the old workaround of exporting and then importing a key
GPGME_KEYLIST_MODE_EXTERN). It replaces the old workaround of as used to make an X.509 key permanent. This function
exporting and then importing a key as used to make an X.509 key automagically does the right thing.
permanent. This function automagically does the right thing.
KEYS is a NULL terminated array of gpgme key objects. The result KEYS is a NULL terminated array of gpgme key objects. The result
is the usual import result structure. Only keys matching the is the usual import result structure. Only keys matching the