removed all the .cvsignre files - they should be local
[gpgme.git] / doc / gpgme.texi
index a012abb..573742f 100644 (file)
@@ -686,6 +686,19 @@ The function @code{gpgme_strerror} returns a pointer to a statically
 allocated string containing a description of the error with the error
 value @var{err}.  This string can be used to output a diagnostic
 message to the user.
+
+The following example illustrates the use of @code{gpgme_strerror}:
+
+@example
+GpgmeCtx ctx;
+GpgmeError err = gpgme_new (&ctx);
+if (err)
+  @{
+    fprintf (stderr, "%s: creating GpgME context failed: %s\n",
+             argv[0], gpgme_strerror (err));
+    exit (1);
+  @}
+@end example
 @end deftypefun
 
 
@@ -779,7 +792,6 @@ exactly one of @var{filename} and @var{fp} is not a valid pointer,
 @code{GPGME_Out_Of_Core} if not enough memory is available.
 @end deftypefun
 
-
 @deftypefun GpgmeError gpgme_data_new_with_read_cb (@w{GpgmeData *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
 The function @code{gpgme_data_new_with_read_cb} creates a new
 @code{GpgmeData} object and uses the callback function @var{readfunc}
@@ -1314,6 +1326,35 @@ operation, @code{GPGME_Out_Of_Core} if at some time during the
 operation there was not enough memory available.
 @end deftypefun
 
+The following example illustrates how all keys containing a certain
+string (@code{g10code}) can be listed with their key ID and the name
+and e-mail address of the main user ID:
+
+@example
+GpgmeCtx ctx;
+GpgmeError err = gpgme_new (&ctx);
+
+if (!err)
+  @{
+    err = gpgme_op_keylist_start (ctx, "g10code", 0);
+    while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF)
+      @{
+        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));
+        gpgme_key_release (key);
+      @}
+    gpgme_release (ctx);
+  @}
+if (err)
+  @{
+    fprintf (stderr, "%s: can not list keys: %s\n",
+             argv[0], gpgme_strerror (err));
+    exit (1);
+  @}
+@end example
+
 
 @node Information About Keys
 @subsection Information About Keys
@@ -1358,7 +1399,8 @@ This is the timestamp at creation time of a sub key.  It is
 representable as a number.
 
 @item GPGME_ATTR_EXPIRE
-XXX FIXME
+This is the expiration time of a sub key.  It is representable as a
+number.
 
 @item GPGME_ATTR_OTRUST
 XXX FIXME  (also for trust items)
@@ -1907,9 +1949,14 @@ have a different status.  You can get each key's status with
 @end deftp
 
 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
-The function @code{gpgme_op_verify} verifies that the detached
-signature in the data object @var{sig} is a valid signature for the
-plaintext in the data object @var{plain}.
+The function @code{gpgme_op_verify} verifies that the signature in the
+data object @var{sig} is a valid signature.  If @var{plain} is
+initialized with plaintext data, it is assumed that @var{sig} is a
+detached signature, and its validity for the plaintext given in
+@var{plain} is verified.  If @var{plain} is an uninitialized data
+object, it is assumed that @var{sig} is a normal (or cleartext)
+signature, and the plaintext is available in @var{plain} after
+successful verification.
 
 The combined status of all signatures is returned in @var{r_stat}.
 The results of the individual signature verifications can be retrieved
@@ -1918,9 +1965,9 @@ with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
 The function returns @code{GPGME_No_Error} if the operation could be
 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
-@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
-data to verify, and passes through any errors that are reported by the
-crypto engine support routines.
+@code{GPGME_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 GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
@@ -2242,6 +2289,13 @@ encrypted for all valid recipients and returned in @var{cipher}.  More
 information about the invalid recipients is available with
 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
 
+If @var{recp} is @code{NULL}, symmetric rather than public key
+encryption is performed.  Symmetrically encrypted cipher text can be
+deciphered with @code{gpgme_op_decrypt}.  Note that in this case the
+crypto backend needs to retrieve a passphrase from the user.
+Symmetric encryption is currently only supported for the OpenPGP
+crypto backend.
+
 The function returns @code{GPGME_No_Error} if the ciphertext could be
 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
@@ -2316,7 +2370,7 @@ Here is a sample of the information that might be returned:
 @end example
 
 Currently, the only operations that return additional information are
-encrypt and sign.  @xref{Encrypt}, @xref{Sign}.
+encrypt, sign and import.  @xref{Encrypt}, @xref{Sign}, @xref(Importing Keys}.
 
 The function returns a string or @code{NULL} if no such data is
 available.
@@ -2425,5 +2479,3 @@ registered yet.
 @summarycontents
 @contents
 @bye
-
-@c  LocalWords:  GPGME gpgme