From: Marcus Brinkmann Date: Wed, 6 Feb 2002 00:08:47 +0000 (+0000) Subject: doc/ X-Git-Tag: gpgme-1.2.0@1385~1110 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=8d604b47406b2f51b83996305afd3ae4923fcb3e;p=gpgme.git doc/ 2002-02-06 Marcus Brinkmann * gpgme.texi (Key Listing Mode): Update documentation. gpgme/ 2002-02-06 Marcus Brinkmann * 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.. --- diff --git a/trunk/NEWS b/trunk/NEWS index faf755f..5375328 100644 --- a/trunk/NEWS +++ b/trunk/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 diff --git a/trunk/TODO b/trunk/TODO index 1a840f7..7eb7de9 100644 --- a/trunk/TODO +++ b/trunk/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 - by the user, they are not merely convenience, but necessity, while - the op_foobar_start functions for these are unusable (or render the + seperately; the op_foobar operations can't be implemented by the + user, they are not merely convenience, but necessity, while 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 GpgSM ERR messages. +** Map ASSUAN/GpgSM ERR error values in a better way than is done now. ** 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. diff --git a/trunk/doc/ChangeLog b/trunk/doc/ChangeLog index ed854aa..ce4bf44 100644 --- a/trunk/doc/ChangeLog +++ b/trunk/doc/ChangeLog @@ -1,3 +1,7 @@ +2002-02-06 Marcus Brinkmann + + * gpgme.texi (Key Listing Mode): Update documentation. + 2002-01-31 Marcus Brinkmann * gpgme.texi (Generating Keys): Document error at creation diff --git a/trunk/doc/gpgme.texi b/trunk/doc/gpgme.texi index 7e883e3..e2f68ef 100644 --- a/trunk/doc/gpgme.texi +++ b/trunk/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} -are: +behaviour of the key listing functions. The value in @var{mode} is a +bitwise-or combination of one or multiple of the following bit values: @table @code -@item 0 -Normal listing. -@item 1 -Fast listing without information about the key validity. +@item GPGME_KEYLIST_MODE_LOCAL +The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local +keyring should be searched for keys in the keylisting operation. This +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 diff --git a/trunk/gpgme/ChangeLog b/trunk/gpgme/ChangeLog index ef528b3..05cae53 100644 --- a/trunk/gpgme/ChangeLog +++ b/trunk/gpgme/ChangeLog @@ -1,3 +1,15 @@ +2002-02-06 Marcus Brinkmann + + * 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 This patch has gotten a bit large... mmh. The main thing that diff --git a/trunk/gpgme/gpgme.c b/trunk/gpgme/gpgme.c index d4637f0..c727a51 100644 --- a/trunk/gpgme/gpgme.c +++ b/trunk/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. - * Defines values for @mode are: %0 = normal, %1 = fast listing without - * information about key validity. + * This function changes the default behaviour of the keylisting + * functions. mode is a bitwise-OR of the GPGME_KEYLIST_* flags. + * 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; } diff --git a/trunk/gpgme/gpgme.h b/trunk/gpgme/gpgme.h index 8823a7b..60dd975 100644 --- a/trunk/gpgme/gpgme.h +++ b/trunk/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. */