2002-03-06 Marcus Brinkmann <marcus@g10code.de>

	* gpgme.texi (Error Strings): Add example.
	* gpgme.texi (Listing Keys): Likewise.

diff --git a/doc/ChangeLog b/doc/ChangeLog
index a4c733ea293a98e520b2b65fabfec1ec3723890a..bdd5f29265e81b71a1b3f158546fcc5c98a48363 100644 (file)
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2002-03-06  Marcus Brinkmann  <marcus@g10code.de>
+
+       * gpgme.texi (Error Strings): Add example.
+       * gpgme.texi (Listing Keys): Likewise.
+
 2002-03-03  Marcus Brinkmann  <marcus@g10code.de>
 
        * gpgme.texi (Information About Keys): Document GPGME_ATTR_EXPIRE.

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index fb3cbe3d732f9b3324a94ee62ed1badcb59b66b5..0c2d4136635a14f6a745b6f2f4563220e1b17004 100644 (file)
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -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
@@ -2431,5 +2472,3 @@ registered yet.
 @summarycontents
 @contents
 @bye
-
-@c  LocalWords:  GPGME gpgme