diff options
| -rw-r--r-- | doc/ChangeLog | 13 | ||||
| -rw-r--r-- | doc/gpgme.texi | 77 |
2 files changed, 51 insertions, 39 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index e06069d1..9b5a1da3 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,16 @@ +2003-07-23 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Key Listing Mode): Remove word duplication. + (Listing Keys): Remove mentioning of force argument. + (Verify): Don't mention r_stat. Fix some typos. + (Decrypt and Verify): Correct info how to get the result. Don't + mention r_stat. + (Manipulating Data Buffers): Fix documentation of return value. + (Listing Keys): Update examples. + (Decrypt): Result might also be available when operation failed. + (Verify): Result might also be available when operation failed. + All spotted by St�phane Corth�sy. + 2003-07-22 Marcus Brinkmann <[email protected]> * gpgme.texi (Error Sources): Fix cut and paste error. diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 3a2ec830..1f518dbc 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -1532,8 +1532,7 @@ from the data object with the handle @var{dh} into the space starting at @var{buffer}. If no error occurs, the actual amount read is returned. If the end of -the data object is reached, the function returns @code{GPG_ERR_EOF} and -sets @var{nread} to zero. +the data object is reached, the function returns 0. In all other cases, the function returns -1 and sets @var{errno}. @end deftypefun @@ -1834,7 +1833,7 @@ is the default. @item GPGME_KEYLIST_MODE_EXTERN The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external -source should be should be searched for keys in the keylisting +source should be searched for keys in the keylisting operation. The type of external source is dependant on the crypto engine used. For example, it can be a remote keyserver or LDAP certificate server. @@ -2326,10 +2325,7 @@ if (!err) err = gpgme_op_keylist_next (ctx, &key); if (err) break; - printf ("%s: %s <%s>\n", - gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0), - gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0), - gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0)); + printf ("%s: %s <%s>\n", key->keyid, key->name, key->email); gpgme_key_release (key); @} gpgme_release (ctx); @@ -2372,10 +2368,8 @@ following function can be used to retrieve a single key. @deftypefun gpgme_error_t gpgme_get_key (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{fpr}}, @w{gpgme_key_t *@var{r_key}}, @w{int @var{secret}}) The function @code{gpgme_get_key} gets the key with the fingerprint (or key ID) @var{fpr} from the crypto backend and return it in -@var{r_key}. If @var{force_update} is true, force a refresh of the -key from the crypto backend and replace the key in the cache, if any. -If @var{secret} is true, get the secret key. The currently active -keylist mode is used to retrieve the key. +@var{r_key}. If @var{secret} is true, get the secret key. The +currently active keylist mode is used to retrieve the key. If the key is not found in the keyring, @code{gpgme_get_key} returns the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to @@ -3330,12 +3324,13 @@ algorithm that is not supported. @deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}}) The function @code{gpgme_op_decrypt_result} returns a -@code{gpgme_decrypt_result_t} pointer to a structure holding the result of -a @code{gpgme_op_decrypt} operation. The pointer is only valid if the -last operation on the context was a @code{gpgme_op_decrypt} or -@code{gpgme_op_decrypt_start} operation, and if this operation -finished successfully. The returned pointer is only valid until the -next operation is started on the context. +@code{gpgme_decrypt_result_t} pointer to a structure holding the +result of a @code{gpgme_op_decrypt} operation. The pointer is only +valid if the last operation on the context was a +@code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation. +If the operation failed this might be a @code{NULL} pointer. The +returned pointer is only valid until the next operation is started on +the context. @end deftypefun @@ -3361,10 +3356,10 @@ with @code{gpgme_op_verify_result}. The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if -@var{ctx}, @var{sig}, @var{plain} or @var{r_stat} is not a valid -pointer, @code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data -to verify, and passes through any errors that are reported by the -crypto engine support routines. +@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, +@code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to +verify, and passes through any errors that are reported by the crypto +engine support routines. @end deftypefun @deftypefun gpgme_error_t gpgme_op_verify_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}}) @@ -3374,9 +3369,9 @@ The function @code{gpgme_op_verify_start} initiates a The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be started successfully, @code{GPG_ERR_INV_VALUE} if -@var{ctx}, @var{sig}, @var{plain} or @var{r_stat} is not a valid -pointer, and @code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does -not contain any data to verify. +@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and +@code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain +any data to verify. @end deftypefun @deftp {Data type} {gpgme_sig_notation_t} @@ -3425,8 +3420,8 @@ The defined bits are: information. Check the other bits. @item GPGME_SIGSUM_RED - The signature is bad. It might be useful to checkother bits and - display moe information, i.e. a revoked certificate might not render a + The signature is bad. It might be useful to check other bits and + display more information, i.e. a revoked certificate might not render a signature invalid when the message was received prior to the cause for the revocation. @@ -3441,7 +3436,7 @@ The defined bits are: The signature has expired. @item GPGME_SIGSUM_KEY_MISSING - Can't verifydue to a missing key o certificate. + Can't verify due to a missing key or certificate. @item GPGME_SIGSUM_CRL_MISSING The CRL (or an equivalent mechanism) is not available. @@ -3503,19 +3498,23 @@ The expiration timestamp of this signature, or 0 if the signature does not expire. @item int wrong_key_usage : 1; +This is true if the key was not used according to its policy. @item gpgme_validity_t validity +The validity of the signature. @item gpgme_error_t validity_reason +If a signature is not valid, this provides a reason why. + @end table @end deftp @deftp {Data type} {gpgme_verify_result_t} This is a pointer to a structure used to store the result of a -@code{gpgme_op_verify} operation. After successfully verifying a -signature, you can retrieve the pointer to the result with -@code{gpgme_op_verify_result}. The structure contains the following -member: +@code{gpgme_op_verify} operation. After verifying a signature, you +can retrieve the pointer to the result with +@code{gpgme_op_verify_result}. If the operation failed this might be +a @code{NULL} pointer. The structure contains the following member: @table @code @item gpgme_signature_t signatures @@ -3780,18 +3779,18 @@ the data object @var{cipher} and stores it into the data object @var{plain}. If @var{cipher} contains signatures, they will be verified. -After the operation completed, @code{gpgme_op_get_sig_status} and -@code{gpgme_op_get_sig_key} can be used to retrieve more information +After the operation completed, @code{gpgme_op_decrypt_result} and +@code{gpgme_op_verify_result} can be used to retrieve more information about the signatures. The function returns the error code @code{GPG_ERR_NO_ERROR} if the ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE} -if @var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid -pointer, @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any -data to decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not -a valid cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase -for the secret key could not be retrieved, and passes through any -errors that are reported by the crypto engine support routines. +if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer, +@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to +decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid +cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the +secret key could not be retrieved, and passes through any errors that +are reported by the crypto engine support routines. @end deftypefun @deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) |