From 671edce1ae7716d2099a7f502dc560abc024f8ae Mon Sep 17 00:00:00 2001 From: Marcus Brinkmann Date: Thu, 24 Apr 2003 17:16:28 +0000 Subject: doc/ 2003-04-24 Marcus Brinkmann * gpgme.texi (Generating Keys): Document changed gpgme_op_genkey and new gpgme_op_genkey_result function. Document GpgmeGenKeyResult data type. gpgme/ 2003-04-24 Marcus Brinkmann * gpgme.h (struct _gpgme_op_genkey_result): New structure. (GpgmeGenKeyResult): New type. (gpgme_op_genkey): Drop last argument. (gpgme_op_genkey_result): New function. * genkey.c: Do not include "util.h", but "gpgme.h". (struct genkey_result): Replace with ... (op_data_t): ... this new type. (release_genkey_result): Replace with ... (release_op_data): ... this new function. (gpgme_op_genkey_result): New function. (genkey_status_handler): Rewritten using new op_data_t type. (get_key_parameter): New function. (_gpgme_op_genkey_start): Renamed to (genkey_start): ... this and rewritten. (gpgme_op_genkey_start): Use genkey_start instead _gpgme_op_genkey_start. (gpgme_op_genkey): Rewritten. Remove FPR argument. tests/ 2003-04-24 Marcus Brinkmann * gpg/t-genkey.c: Rewritten to match new semantics. --- doc/ChangeLog | 4 ++++ doc/gpgme.texi | 47 ++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 42 insertions(+), 9 deletions(-) (limited to 'doc') diff --git a/doc/ChangeLog b/doc/ChangeLog index e9e1d1fa..a387471a 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,5 +1,9 @@ 2003-04-24 Marcus Brinkmann + * gpgme.texi (Generating Keys): Document changed gpgme_op_genkey + and new gpgme_op_genkey_result function. Document + GpgmeGenKeyResult data type. + * gpgme.texi (Error Values): Rename GPGME_No_Passphrase to GPGME_Bad_Passphrase. * gpgme.texi (Decrypt): Likewise. diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 5edf7b80..105e0314 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -2115,7 +2115,7 @@ The function @code{gpgme_key_release} is an alias for @cindex key, creation @cindex key ring, add -@deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}, @w{char **@var{fpr}}) +@deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}) The function @code{gpgme_op_genkey} generates a new key pair in the context @var{ctx} and puts it into the standard key ring if both @var{pubkey} and @var{seckey} are @code{NULL}. In this case the @@ -2130,8 +2130,8 @@ the data object will contain the secret key. Note that not all crypto engines support this interface equally. GnuPG does not support @var{pubkey} and @var{subkey}, they should be both @code{NULL}, and the key pair will be added to the standard key -ring. GpgSM does only support @var{pubkey}, the secret key will be -stored by @command{gpg-agent}. GpgSM expects @var{pubkey} being not +ring. GpgSM only supports @var{pubkey}, the secret key will be stored +by @command{gpg-agent}. GpgSM expects @var{pubkey} being not @code{NULL}. The argument @var{parms} specifies parameters for the key in an XML @@ -2168,12 +2168,8 @@ for now is ``internal''. The content of the @code{GnupgKeyParms} container is passed verbatim to GnuPG. Control statements are not allowed. -If @var{fpr} is not a null pointer, the function succeeds, and the -crypto engine supports it, *@var{fpr} will contain a string with the -fingerprint of the key, allocated with @code{malloc}. If both a -primary and a sub key was generated, the fingerprint of the primary -key will be returned. If the crypto engine does not provide the -fingerprint, *@var{fpr} will be a null pointer. +After the operation completed successfully, the result can be +retrieved with @code{gpgme_op_genkey_result}. The function returns @code{GPGME_No_Error} if the operation could be started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not @@ -2193,6 +2189,39 @@ a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or @var{seckey} is not @code{NULL}. @end deftypefun +@deftp {Data type} {GpgmeGenKeyResult} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_genkey} operation. After successfully generating a +key, you can retrieve the pointer to the result with +@code{gpgme_op_genkey_result}. The structure contains the following +members: + +@table @code +@item unsigned int primary : 1 +This is a flag that is set to 1 if a primary key was created and to 0 +if not. + +@item unsigned int sub : 1 +This is a flag that is set to 1 if a subkey was created and to 0 +if not. + +@item char *fpr +This is the fingerprint of the key that was created. If both a +primary and a sub key were generated, the fingerprint of the primary +key will be returned. If the crypto engine does not provide the +fingerprint, @code{fpr} will be a null pointer. +@end table +@end deftp + +@deftypefun GpgmeGenKeyResult gpgme_op_genkey_result (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_op_genkey_result} returns a +@code{GpgmeGenKeyResult} pointer to a structure holding the result of +a @code{gpgme_op_genkey} operation. The pointer is only valid if the +last operation on the context was a @code{gpgme_op_genkey} or +@code{gpgme_op_genkey_start} operation, and if this operation finished +successfully. The returned pointer is only valid until the next +operation is started on the context. +@end deftypefun @node Exporting Keys @subsection Exporting Keys -- cgit v1.2.3