From 4fa30089501b479a5e57086c8ce3de7c90c5dff1 Mon Sep 17 00:00:00 2001 From: Marcus Brinkmann Date: Wed, 6 Feb 2002 00:08:47 +0000 Subject: 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.. --- doc/gpgme.texi | 44 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 6 deletions(-) (limited to 'doc/gpgme.texi') diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 7e883e3c..e2f68ef8 100644 --- a/doc/gpgme.texi +++ b/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 -- cgit v1.2.3