doc/

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

	* gpgme.texi (Key Listing Mode): Update documentation.

gpgme/
2002-02-06  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.c (gpgme_set_keylist_mode): Possibly return an error
	value.
	(gpgme_get_keylist_mode): New function.
	(gpgme_new): Set the default for keylist_mode member of CTX.

	* gpgme.h (gpgme_set_keylist_mode): Fix prototype.
	(gpgme_get_keylist_mode): New prototype.
	(GPGME_KEYLIST_MODE_LOCAL): New macro.
	(GPGME_KEYLIST_MODE_EXTERN): Likewise..

NEWS

@@ -1,5 +1,14 @@
  * There is a Texinfo manual documenting the API.
 
+ * The gpgme_set_keylist_mode function returns an error, and changed
+   its meaning.  It is no longer usable to select between normal and
+   fast mode (newer versions of GnuPG will always be fast), but
+   selects between local keyring, remote keyserver, or both.
+   For this, two new macros are defined, GPGME_KEYLIST_MODE_LOCAL
+   and GPGME_KEYLIST_MODE_EXTERN.  To make it possible to modify the
+   current setting, a fucntion gpgme_get_keylist_mode was added to
+   retrieve the current mode.
+
  * The LENGTH argument to gpgme_data_new_from_filepart changed its
    type from off_t to the unsigned size_t.
 
@@ -18,6 +27,11 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 gpgme_data_new_from_filepart	CHANGED: Type of LENGTH is size_t.
 GpgmePassphraseCb               CHANGED: Type of R_HD is void **.
+gpgme_set_keylist_mode          CHANGED: Type of return value is GpgmeError.
+                                The function has a new meaning!
+gpgme_get_keylist_mode          NEW
+GPGME_KEYLIST_MODE_LOCAL        NEW
+GPGME_KEYLIST_MODE_EXTERN       NEW
 gpgme_op_trustlist_next		NEW
 GpgmeIdleFunc                   NEW
 gpgme_register_idle             NEW

TODO

@@ -1,14 +1,14 @@
+Hey Emacs, this is -*- outline -*- mode!
+
 * ABI's to break:
 ** The resulting error of an operation can not be retrieved
-   seperately; the op_foobar operations can't be implemented
+   seperately; the op_foobar operations can't be implemented by the
-   by the user, they are not merely convenience, but necessity, while
+   user, they are not merely convenience, but necessity, while the
-   the op_foobar_start functions for these are unusable (or render the
+   op_foobar_start functions for these are unusable (or render the
    context unusable, your choice).
 ** string representation of non-secret keys and ATTR_IS_SECRET is NULL,
    which can not be differentiated from the case that it is not
    representable.
-** keylisting mode can go
-** api to specify where to search, lokal and/or remote.
 
 * Implement posix-sema.c
 
@@ -21,8 +21,6 @@
 
 * Add ATTR to return the number of subkeys or uids.
 
-* Return GPGME_Canceled when appropriate
-
 * Factor out common code in _op_*_start functions.
 
 * Documentation
@@ -40,8 +38,7 @@
 ** Genkey should return something more useful than General_Error.
 
 * Error Values
-** Map ASSUAN error values.
+** Map ASSUAN/GpgSM ERR error values in a better way than is done now.
-** Map GpgSM ERR messages.
 ** Verify (and document) if Read_Error, Write_Error, Pipe_Error set errno.
 
 * Tests
@@ -52,6 +49,8 @@
 
 * Build suite
 ** Make sure everything is cleaned correctly (esp. test area).
+** There is a spurious 4/10 tests failed in some conditions.
+   Rebuilding from scratch works around that.
 
 Bugs reported by Stephane Corthesy:
 > - When returning a GpgmeKey GPGME_ATTR_COMMENT attribute, characters  
@@ -74,8 +73,3 @@ Bugs reported by Stephane Corthesy:
 > the  
 > callback has become invalid; if I use a brand new one, the callback  
 > is called recursively, when I ask to enumerate keys.
-
-> Talking about gpgme performances: did anyone make some profiling on
-> gpgme calls and can tell me why it takes so long to enumerate the
-> whole pubring? Listing keys with gpg is very fast, whereas with
-> gpgme_op_keylist_XXX() it's soooooo slow.

doc/ChangeLog

@@ -1,3 +1,7 @@
+2002-02-06  Marcus Brinkmann  <marcus@g10code.de>
+
+	* gpgme.texi (Key Listing Mode): Update documentation.
+
 2002-01-31  Marcus Brinkmann  <marcus@g10code.de>
 
 	* gpgme.texi (Generating Keys): Document error at creation

doc/gpgme.texi

@@ -1042,15 +1042,47 @@ valid pointer.
 
 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
 The function @code{gpgme_set_keylist_mode} changes the default
-behaviour of the key listing functions.  Defined values for @var{mode}
+behaviour of the key listing functions.  The value in @var{mode} is a
-are:
+bitwise-or combination of one or multiple of the following bit values:
 
 @table @code
-@item 0
+@item GPGME_KEYLIST_MODE_LOCAL
-Normal listing.
+The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
-@item 1
+keyring should be searched for keys in the keylisting operation.  This
-Fast listing without information about the key validity.
+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
+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.
 @end table
+
+At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
+@code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
+compatibility, you should get the current mode with
+@code{gpgme_get_keylist_mode} and modify it by setting or clearing the
+appropriate bits, and then using that calulcated value in the
+@code{gpgme_set_keylisting_mode} operation.  This will leave all other
+bits in the mode value intact (in particular those that are not used
+in the current version of the library).
+
+The function returns @code{GPGME_No_Error} if the mode could be set
+correctly, and @code{GPGME_Invalid_Value} if @var{ctx} is not a valid
+pointer or @var{mode} is not a valid mode.
+@end deftypefun
+
+
+@deftypefun int gpgme_get_keylist_mode (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_get_keylist_mode} returns the current key
+listing mode of the context @var{ctx}.  This value can then be
+modified and used in a subsequent @code{gpgme_set_keylist_mode}
+operation to only affect the desired bits (and leave all others
+intact).
+
+The function returns 0 if @var{ctx} is not a valid pointer, and the
+current mode otherwise.  Note that 0 is not a valid mode value.
 @end deftypefun
 
 

gpgme/ChangeLog

@@ -1,3 +1,15 @@
+2002-02-06  Marcus Brinkmann  <marcus@g10code.de>
+
+	* gpgme.c (gpgme_set_keylist_mode): Possibly return an error
+	value.
+	(gpgme_get_keylist_mode): New function.
+	(gpgme_new): Set the default for keylist_mode member of CTX.
+
+	* gpgme.h (gpgme_set_keylist_mode): Fix prototype.
+	(gpgme_get_keylist_mode): New prototype.
+	(GPGME_KEYLIST_MODE_LOCAL): New macro.
+	(GPGME_KEYLIST_MODE_EXTERN): Likewise..
+
 2002-02-02  Marcus Brinkmann  <marcus@g10code.de>
 
 	This patch has gotten a bit large... mmh.  The main thing that

gpgme/gpgme.c

@@ -49,6 +49,7 @@ gpgme_new (GpgmeCtx *r_ctx)
   ctx = xtrycalloc (1, sizeof *ctx);
   if (!ctx)
     return mk_error (Out_Of_Core);
+  ctx->keylist_mode = GPGME_KEYLIST_MODE_LOCAL;
   ctx->verbosity = 1;
   *r_ctx = ctx;
 
@@ -279,16 +280,45 @@ gpgme_get_textmode (GpgmeCtx ctx)
  * @ctx: the context
  * @mode: listing mode
  * 
- * This function changes the default behaviour of the keylisting functions.
+ * This function changes the default behaviour of the keylisting
- * Defines values for @mode are: %0 = normal, %1 = fast listing without
+ * functions.  mode is a bitwise-OR of the GPGME_KEYLIST_* flags.
- * information about key validity.
+ * The default mode is GPGME_KEYLIST_MODE_LOCAL.
+ *
+ * Return value: GPGME_Invalid_Value if ctx is not a context or mode
+ * not a valid mode.
  **/
-void
+GpgmeError
 gpgme_set_keylist_mode (GpgmeCtx ctx, int mode)
 {
   if (!ctx)
-    return;
+    return mk_error (Invalid_Value);
+
+  if (!((mode & GPGME_KEYLIST_MODE_LOCAL)
+	|| (mode & GPGME_KEYLIST_MODE_EXTERN)))
+    return mk_error (Invalid_Value);
+
   ctx->keylist_mode = mode;
+  return 0;
+}
+
+
+/**
+ * gpgme_get_keylist_mode:
+ * @ctx: the context
+ * 
+ * This function ch the default behaviour of the keylisting functions.
+ * Defines values for @mode are: %0 = normal, %1 = fast listing without
+ * information about key validity.
+ *
+ * Return value: 0 if ctx is not a valid context, or the current mode.
+ * Note that 0 is never a valid mode.
+ **/
+int
+gpgme_get_keylist_mode (GpgmeCtx ctx)
+{
+  if (!ctx)
+    return 0;
+  return ctx->keylist_mode;
 }
 
 

gpgme/gpgme.h

@@ -186,6 +186,11 @@ typedef enum
 GpgmeProtocol;
 
 
+/* The available keylist mode flags.  */
+#define GPGME_KEYLIST_MODE_LOCAL 1
+#define GPGME_KEYLIST_MODE_EXTERN 2
+
+
 /* Types for callback functions.  */
 
 /* Request a passphrase from the user.  */
@@ -224,7 +229,10 @@ void gpgme_set_textmode (GpgmeCtx ctx, int yes);
 int gpgme_get_textmode (GpgmeCtx ctx);
 
 /* Set keylist mode in CTX to MODE.  */
-void gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
+GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
+
+/* Get keylist mode in CTX.  */
+int gpgme_get_keylist_mode (GpgmeCtx ctx);
 
 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
    passed as first argument to the passphrase callback function.  */