GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc/

Browse Source 
2002-01-29  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.texi (Run Control): New section.
	(Verify): Docuent gpgme_get_notation.
	(More Information): New section describing gpgme_get_op_info.

gpgme/
2002-01-29  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.h: Add new type GpgmeIdleFunc.  Change type of
	gpgme_register_idle to return and accept this type.
	* wait.c (gpgme_register_idle): Fix type.
	Save and return old value of idle_function.
This commit is contained in:
Marcus Brinkmann 2002-01-29 22:58:25 +00:00
parent 1c0317ca79
commit 1513ffd323
6 changed files with 300 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
NEWS
View File

@ -12,11 +12,15 @@
* The CryptPlug modules have been renamed to gpgme-openpgp and * The CryptPlug modules have been renamed to gpgme-openpgp and
gpgme-smime, and they are installed in pkglibdir by `make install'. gpgme-smime, and they are installed in pkglibdir by `make install'.
* An idle function can be registered.
* Interface changes relative to the 0.3.0 release: * Interface changes relative to the 0.3.0 release:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
gpgme_data_new_from_filepart CHANGED: Type of LENGTH is size_t. gpgme_data_new_from_filepart CHANGED: Type of LENGTH is size_t.
GpgmePassphraseCb CHANGED: Type of R_HD is void **. GpgmePassphraseCb CHANGED: Type of R_HD is void **.
gpgme_op_trustlist_next NEW gpgme_op_trustlist_next NEW
GpgmeIdleFunc NEW
gpgme_register_idle NEW
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Noteworthy changes in version 0.3.0 (2001-12-19) Noteworthy changes in version 0.3.0 (2001-12-19)

6
doc/ChangeLog
View File

@ -1,3 +1,9 @@
2002-01-29 Marcus Brinkmann <marcus@g10code.de>
* gpgme.texi (Run Control): New section.
(Verify): Docuent gpgme_get_notation.
(More Information): New section describing gpgme_get_op_info.
2002-01-22 Marcus Brinkmann <marcus@g10code.de> 2002-01-22 Marcus Brinkmann <marcus@g10code.de>
* gpgme.texi (Passphrase callback): Change GpgmePassphraseCb's * gpgme.texi (Passphrase callback): Change GpgmePassphraseCb's

414
doc/gpgme.texi
View File

@ -2,13 +2,6 @@
@setfilename gpgme.info @setfilename gpgme.info
@settitle The `GnuPG Made Easy' Reference Manual @settitle The `GnuPG Made Easy' Reference Manual
@c TODO:
@c char *gpgme_get_op_info (GpgmeCtx c, int reserved);
@c void gpgme_cancel (GpgmeCtx c);
@c GpgmeCtx gpgme_wait (GpgmeCtx c, int hang);
@c char *gpgme_get_notation (GpgmeCtx c);
@c void gpgme_register_idle (void (*fnc)(void));
@dircategory GNU Libraries @dircategory GNU Libraries
@direntry @direntry
* @acronym{GPGME}: (gpgme) Adding support for cryptography to your program. * @acronym{GPGME}: (gpgme) Adding support for cryptography to your program.
@ -109,79 +102,86 @@ Introduction
Preperation Preperation
* Header:: What header file you need to include. * Header:: What header file you need to include.
* Building the source:: Compiler options to be used. * Building the Source:: Compiler options to be used.
* Library version check:: Getting and verifying the library version. * Library Version Check:: Getting and verifying the library version.
Protocols and Engines Protocols and Engines
* Engine version check:: Verifying the engine version. * Engine Version Check:: Verifying the engine version.
* Engine information:: Obtaining more information about the engines. * Engine Information:: Obtaining more information about the engines.
* OpenPGP:: Support for the OpenPGP protocol. * OpenPGP:: Support for the OpenPGP protocol.
* Cryptographic Message Syntax:: Support for the CMS. * Cryptographic Message Syntax:: Support for the CMS.
Error Handling Error Handling
* Error values:: A list of all error values used. * Error Values:: A list of all error values used.
* Error strings:: How to get a descriptive string from a value. * Error Strings:: How to get a descriptive string from a value.
Exchanging Data Exchanging Data
* Creating data buffers:: Creating new data buffers. * Creating Data Buffers:: Creating new data buffers.
* Destroying data buffers:: Releasing data buffers. * Destroying Data Buffers:: Releasing data buffers.
* Manipulating data buffers:: Operations on data buffers. * Manipulating Data Buffers:: Operations on data buffers.
Contexts Contexts
* Creating contexts:: Creating new @acronym{GPGME} contexts. * Creating Contexts:: Creating new @acronym{GPGME} contexts.
* Destroying contexts:: Releasing @acronym{GPGME} contexts. * Destroying Contexts:: Releasing @acronym{GPGME} contexts.
* Context attributes:: Setting properties of a context. * Context Attributes:: Setting properties of a context.
* Key Management:: Managing keys with @acronym{GPGME}. * Key Management:: Managing keys with @acronym{GPGME}.
* Trust Item Management:: Managing trust items with @acronym{GPGME}. * Trust Item Management:: Managing trust items with @acronym{GPGME}.
* Crypto Operations:: Using a context for cryptography. * Crypto Operations:: Using a context for cryptography.
* Run Control:: Controlling how operations are run.
Context attributes Context Attributes
* Protocol selection:: Selecting the protocol used by a context. * Protocol Selection:: Selecting the protocol used by a context.
* @acronym{ASCII} armor:: Requesting @acronym{ASCII} armored output. * @acronym{ASCII} Armor:: Requesting @acronym{ASCII} armored output.
* Text mode:: Choosing canonical text mode. * Text Mode:: Choosing canonical text mode.
* Key listing mode:: Selecting key listing mode. * Key Listing Mode:: Selecting key listing mode.
* Passphrase callback:: Getting the passphrase from the user. * Passphrase Callback:: Getting the passphrase from the user.
* Progress meter callback:: Being informed about the progress. * Progress Meter Callback:: Being informed about the progress.
Key Management Key Management
* Listing keys:: Browsing the list of available keys. * Listing Keys:: Browsing the list of available keys.
* Information about keys:: Requesting detailed information about keys. * Information About Keys:: Requesting detailed information about keys.
* Manipulating keys:: Operations on keys. * Manipulating Keys:: Operations on keys.
* Generating keys:: Creating new key pairs. * Generating Keys:: Creating new key pairs.
* Exporting keys:: Retrieving key data from the key ring. * Exporting Keys:: Retrieving key data from the key ring.
* Importing keys:: Adding keys to the keyring. * Importing Keys:: Adding keys to the keyring.
* Deleting keys:: Removing keys from the keyring. * Deleting Keys:: Removing keys from the keyring.
Trust Item Management Trust Item Management
* Listing trust items:: Browsing the list of available trust items. * Listing Trust Items:: Browsing the list of available trust items.
* Information about trust items:: Requesting detailed information about trust items. * Information About Trust Items:: Requesting detailed information about trust items.
* Manipulating trust items:: Operations on trust items. * Manipulating Trust Items:: Operations on trust items.
Crypto Operations Crypto Operations
* Decrypt:: Decrypting a ciphertext. * Decrypt:: Decrypting a ciphertext.
* Verify:: Verifying a signature. * Verify:: Verifying a signature.
* Decrypt and verify:: Decrypting a signed ciphertext. * Decrypt and Verify:: Decrypting a signed ciphertext.
* Sign:: Creating a signature. * Sign:: Creating a signature.
* Encrypt:: Encrypting a plaintext. * Encrypt:: Encrypting a plaintext.
* More Information:: How to obtain more info about the operation.
Sign Sign
* Selecting signers:: How to choose the keys to sign with. * Selecting Signers:: How to choose the keys to sign with.
* Creating a signature:: How to create a signature. * Creating a Signature:: How to create a signature.
Encrypt Encrypt
* Selecting recipients:: How to choose the recipients. * Selecting Recipients:: How to choose the recipients.
* Encrypting a plaintext:: How to encrypt a plaintext. * Encrypting a Plaintext:: How to encrypt a plaintext.
Run Control
* Waiting For Completion:: Waiting until an operation is completed.
* Cancelling an Operation:: Interrupting a running operation.
* Hooking Up Into Idle Time:: Doing something when nothing has to be done.
@end detailmenu @end detailmenu
@end menu @end menu
@ -293,8 +293,8 @@ of the library are verified.
@menu @menu
* Header:: What header file you need to include. * Header:: What header file you need to include.
* Building the source:: Compiler options to be used. * Building the Source:: Compiler options to be used.
* Library version check:: Getting and verifying the library version. * Library Version Check:: Getting and verifying the library version.
@end menu @end menu
@ -315,8 +315,8 @@ names, @code{Gpgme*} for data types and @code{GPGME_*} for other
symbols. symbols.
@node Building the source @node Building the Source
@section Building the source @section Building the Source
If you want to compile a source file including the `gpgme.h' header If you want to compile a source file including the `gpgme.h' header
file, you must make sure that the compiler can find it in the file, you must make sure that the compiler can find it in the
@ -362,8 +362,8 @@ gcc -o foo foo.c `gpgme-config --cflags --libs`
@end example @end example
@node Library version check @node Library Version Check
@section Library version check @section Library Version Check
@deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}}) @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
The function @code{gpgme_check_version} has three purposes. It can be The function @code{gpgme_check_version} has three purposes. It can be
@ -422,15 +422,15 @@ This specifies the Cryptographic Message Syntax.
@end deftp @end deftp
@menu @menu
* Engine version check:: Verifying the engine version. * Engine Version Check:: Verifying the engine version.
* Engine information:: Obtaining more information about the engines. * Engine Information:: Obtaining more information about the engines.
* OpenPGP:: Support for the OpenPGP protocol. * OpenPGP:: Support for the OpenPGP protocol.
* Cryptographic Message Syntax:: Support for the CMS. * Cryptographic Message Syntax:: Support for the CMS.
@end menu @end menu
@node Engine version check @node Engine Version Check
@section Engine version check @section Engine Version Check
@deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}}) @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
The function @code{gpgme_engine_check_version} verifies that the The function @code{gpgme_engine_check_version} verifies that the
@ -453,8 +453,8 @@ only. It is obsoleted by @code{gpgme_engine_check_version}.
@end deftypefun @end deftypefun
@node Engine information @node Engine Information
@section Engine information @section Engine Information
@deftypefun {const char *} gpgme_get_engine_info (void) @deftypefun {const char *} gpgme_get_engine_info (void)
The function @code{gpgme_get_engine_info} returns an @acronym{XML} The function @code{gpgme_get_engine_info} returns an @acronym{XML}
@ -531,13 +531,13 @@ specific meanings if returned by a specific function. Such cases are
described in the documentation of those functions. described in the documentation of those functions.
@menu @menu
* Error values:: A list of all error values used. * Error Values:: A list of all error values used.
* Error strings:: How to get a descriptive string from a value. * Error Strings:: How to get a descriptive string from a value.
@end menu @end menu
@node Error values @node Error Values
@section Error values @section Error Values
@deftp {Data type} {enum GpgmeError} @deftp {Data type} {enum GpgmeError}
The @code{GpgmeError} type specifies the set of all error values that The @code{GpgmeError} type specifies the set of all error values that
@ -642,8 +642,8 @@ engine is not installed properly.
@end deftp @end deftp
@node Error strings @node Error Strings
@section Error strings @section Error Strings
@deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}}) @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
The function @code{gpgme_strerror} returns a pointer to a statically The function @code{gpgme_strerror} returns a pointer to a statically
@ -670,14 +670,14 @@ data, which is used by @acronym{GPGME} to exchange data with the user.
@end deftp @end deftp
@menu @menu
* Creating data buffers:: Creating new data buffers. * Creating Data Buffers:: Creating new data buffers.
* Destroying data buffers:: Releasing data buffers. * Destroying Data Buffers:: Releasing data buffers.
* Manipulating data buffers:: Operations on data buffers. * Manipulating Data Buffers:: Operations on data buffers.
@end menu @end menu
@node Creating data buffers @node Creating Data Buffers
@section Creating data buffers @section Creating Data Buffers
@deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}}) @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
The function @code{gpgme_data_new} creates a new @code{GpgmeData} The function @code{gpgme_data_new} creates a new @code{GpgmeData}
@ -766,8 +766,8 @@ not enough memory is available.
@end deftypefun @end deftypefun
@node Destroying data buffers @node Destroying Data Buffers
@section Destroying data buffers @section Destroying Data Buffers
@deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}}) @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
The function @code{gpgme_data_release} destroys the data object with The function @code{gpgme_data_release} destroys the data object with
@ -789,8 +789,8 @@ be returned to the user, the function will return @code{NULL}.
@end deftypefun @end deftypefun
@node Manipulating data buffers @node Manipulating Data Buffers
@section Manipulating data buffers @section Manipulating Data Buffers
@deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}}) @deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}})
The function @code{gpgme_data_read} reads up to @var{length} bytes The function @code{gpgme_data_read} reads up to @var{length} bytes
@ -881,17 +881,18 @@ cryptographic operations.
@end deftp @end deftp
@menu @menu
* Creating contexts:: Creating new @acronym{GPGME} contexts. * Creating Contexts:: Creating new @acronym{GPGME} contexts.
* Destroying contexts:: Releasing @acronym{GPGME} contexts. * Destroying Contexts:: Releasing @acronym{GPGME} contexts.
* Context attributes:: Setting properties of a context. * Context Attributes:: Setting properties of a context.
* Key Management:: Managing keys with @acronym{GPGME}. * Key Management:: Managing keys with @acronym{GPGME}.
* Trust Item Management:: Managing trust items with @acronym{GPGME}. * Trust Item Management:: Managing trust items with @acronym{GPGME}.
* Crypto Operations:: Using a context for cryptography. * Crypto Operations:: Using a context for cryptography.
* Run Control:: Controlling how operations are run.
@end menu @end menu
@node Creating contexts @node Creating Contexts
@section Creating contexts @section Creating Contexts
@deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}}) @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
The function @code{gpgme_data_new} creates a new @code{GpgmeCtx} The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
@ -905,8 +906,8 @@ available.
@node Destroying contexts @node Destroying Contexts
@section Destroying contexts @section Destroying Contexts
@deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}}) @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_release} destroys the context with the handle The function @code{gpgme_release} destroys the context with the handle
@ -914,21 +915,21 @@ The function @code{gpgme_release} destroys the context with the handle
@end deftypefun @end deftypefun
@node Context attributes @node Context Attributes
@section Context attributes @section Context Attributes
@menu @menu
* Protocol selection:: Selecting the protocol used by a context. * Protocol Selection:: Selecting the protocol used by a context.
* @acronym{ASCII} armor:: Requesting @acronym{ASCII} armored output. * @acronym{ASCII} Armor:: Requesting @acronym{ASCII} armored output.
* Text mode:: Choosing canonical text mode. * Text Mode:: Choosing canonical text mode.
* Key listing mode:: Selecting key listing mode. * Key Listing Mode:: Selecting key listing mode.
* Passphrase callback:: Getting the passphrase from the user. * Passphrase Callback:: Getting the passphrase from the user.
* Progress meter callback:: Being informed about the progress. * Progress Meter Callback:: Being informed about the progress.
@end menu @end menu
@node Protocol selection @node Protocol Selection
@subsection Protocol selection @subsection Protocol Selection
@deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}}) @deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
The function @code{gpgme_set_protocol} sets the protocol used within The function @code{gpgme_set_protocol} sets the protocol used within
@ -938,7 +939,7 @@ performed by the crypto engine configured for that protocol.
Setting the protocol with @code{gpgme_set_protocol} does not check if Setting the protocol with @code{gpgme_set_protocol} does not check if
the crypto engine for that protocol is available and installed the crypto engine for that protocol is available and installed
correctly. @xref{Engine version check}. correctly. @xref{Engine Version Check}.
The function returns @code{GPGME_No_Error} if the protocol could be The function returns @code{GPGME_No_Error} if the protocol could be
set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
@ -946,8 +947,8 @@ not a valid protocol.
@end deftypefun @end deftypefun
@node @acronym{ASCII} armor @node @acronym{ASCII} Armor
@subsection @acronym{ASCII} armor @subsection @acronym{ASCII} Armor
@deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}}) @deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
The function @code{gpgme_set_armor} specifies if the output should be The function @code{gpgme_set_armor} specifies if the output should be
@ -965,8 +966,8 @@ not a valid pointer.
@end deftypefun @end deftypefun
@node Text mode @node Text Mode
@subsection Text mode @subsection Text Mode
@deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}}) @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
The function @code{gpgme_set_textmode} specifies if canonical text mode The function @code{gpgme_set_textmode} specifies if canonical text mode
@ -987,8 +988,8 @@ valid pointer.
@end deftypefun @end deftypefun
@node Key listing mode @node Key Listing Mode
@subsection Key listing mode @subsection Key Listing Mode
@deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}}) @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
The function @code{gpgme_set_keylist_mode} changes the default The function @code{gpgme_set_keylist_mode} changes the default
@ -1004,8 +1005,8 @@ Fast listing without information about the key validity.
@end deftypefun @end deftypefun
@node Passphrase callback @node Passphrase Callback
@subsection Passphrase callback @subsection Passphrase Callback
@deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})} @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
The @code{GpgmePasshraseCb} type is the type of functions usable as The @code{GpgmePasshraseCb} type is the type of functions usable as
@ -1041,8 +1042,8 @@ calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
@end deftypefun @end deftypefun
@node Progress meter callback @node Progress Meter Callback
@subsection Progress meter callback @subsection Progress Meter Callback
@deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})} @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
The @code{GpgmeProgressCb} type is the type of functions usable as The @code{GpgmeProgressCb} type is the type of functions usable as
@ -1087,18 +1088,18 @@ A key can contain several user IDs and sub keys.
@end deftp @end deftp
@menu @menu
* Listing keys:: Browsing the list of available keys. * Listing Keys:: Browsing the list of available keys.
* Information about keys:: Requesting detailed information about keys. * Information About Keys:: Requesting detailed information about keys.
* Manipulating keys:: Operations on keys. * Manipulating Keys:: Operations on keys.
* Generating keys:: Creating new key pairs. * Generating Keys:: Creating new key pairs.
* Exporting keys:: Retrieving key data from the key ring. * Exporting Keys:: Retrieving key data from the key ring.
* Importing keys:: Adding keys to the keyring. * Importing Keys:: Adding keys to the keyring.
* Deleting keys:: Removing keys from the keyring. * Deleting Keys:: Removing keys from the keyring.
@end menu @end menu
@node Listing keys @node Listing Keys
@subsection Listing keys @subsection Listing Keys
@deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}}) @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
The function @code{gpgme_op_keylist_start} initiates a key listing The function @code{gpgme_op_keylist_start} initiates a key listing
@ -1126,7 +1127,7 @@ crypto engine support routines.
The function @code{gpgme_op_keylist_next} returns the next key in the The function @code{gpgme_op_keylist_next} returns the next key in the
list created by a previous @code{gpgme_op_keylist_start} operation in list created by a previous @code{gpgme_op_keylist_start} operation in
the context @var{ctx}. The key will have one reference for the user. the context @var{ctx}. The key will have one reference for the user.
@xref{Manipulating keys}. @xref{Manipulating Keys}.
This is the only way to get at @code{GpgmeKey} objects in This is the only way to get at @code{GpgmeKey} objects in
@acronym{GPGME}. @acronym{GPGME}.
@ -1151,8 +1152,8 @@ operation there was not enough memory available.
@end deftypefun @end deftypefun
@node Information about keys @node Information About Keys
@subsection Information about keys @subsection Information About Keys
@deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}}) @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
The function @code{gpgme_key_get_as_xml} returns a string in The function @code{gpgme_key_get_as_xml} returns a string in
@ -1341,8 +1342,8 @@ or @var{reserved} not @code{NULL}.
@end deftypefun @end deftypefun
@node Manipulating keys @node Manipulating Keys
@subsection Manipulating keys @subsection Manipulating Keys
@deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}}) @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
The function @code{gpgme_key_ref} acquires an additional reference for The function @code{gpgme_key_ref} acquires an additional reference for
@ -1360,8 +1361,8 @@ The function @code{gpgme_key_release} is an alias for
@end deftypefun @end deftypefun
@node Generating keys @node Generating Keys
@subsection Generating keys @subsection Generating Keys
@deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}) @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
The function @code{gpgme_op_genkey} generates a new key pair in the The function @code{gpgme_op_genkey} generates a new key pair in the
@ -1409,8 +1410,8 @@ is not @code{NULL}.
@end deftypefun @end deftypefun
@node Exporting keys @node Exporting Keys
@subsection Exporting keys @subsection Exporting Keys
@deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}}) @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
The function @code{gpgme_op_export} extracts the public keys of the The function @code{gpgme_op_export} extracts the public keys of the
@ -1426,8 +1427,8 @@ support routines.
@end deftypefun @end deftypefun
@node Importing keys @node Importing Keys
@subsection Importing keys @subsection Importing Keys
@deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}) @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
The function @code{gpgme_op_import} adds the keys in the data buffer The function @code{gpgme_op_import} adds the keys in the data buffer
@ -1442,8 +1443,8 @@ or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
@end deftypefun @end deftypefun
@node Deleting keys @node Deleting Keys
@subsection Deleting keys @subsection Deleting Keys
@deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}}) @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
The function @code{gpgme_op_delete} deletes the key @var{key} from the The function @code{gpgme_op_delete} deletes the key @var{key} from the
@ -1467,14 +1468,14 @@ The @code{GpgmeTrustItem} type is a handle for a trust item.
@end deftp @end deftp
@menu @menu
* Listing trust items:: Browsing the list of available trust items. * Listing Trust Items:: Browsing the list of available trust items.
* Information about trust items:: Requesting detailed information about trust items. * Information About Trust Items:: Requesting detailed information about trust items.
* Manipulating trust items:: Operations on trust items. * Manipulating Trust Items:: Operations on trust items.
@end menu @end menu
@node Listing trust items @node Listing Trust Items
@subsection Listing trust items @subsection Listing Trust Items
@deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}}) @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
The function @code{gpgme_op_trustlist_start} initiates a trust item The function @code{gpgme_op_trustlist_start} initiates a trust item
@ -1501,7 +1502,7 @@ crypto engine support routines.
The function @code{gpgme_op_trustlist_next} returns the next trust The function @code{gpgme_op_trustlist_next} returns the next trust
item in the list created by a previous @code{gpgme_op_trustlist_start} item in the list created by a previous @code{gpgme_op_trustlist_start}
operation in the context @var{ctx}. The trust item can be destroyed operation in the context @var{ctx}. The trust item can be destroyed
with @code{gpgme_trust_item_release}. @xref{Manipulating trust items}. with @code{gpgme_trust_item_release}. @xref{Manipulating Trust Items}.
This is the only way to get at @code{GpgmeTrustItem} objects in This is the only way to get at @code{GpgmeTrustItem} objects in
@acronym{GPGME}. @acronym{GPGME}.
@ -1526,12 +1527,12 @@ operation there was not enough memory available.
@end deftypefun @end deftypefun
@node Information about trust items @node Information About Trust Items
@subsection Information about trust items @subsection Information About Trust Items
Trust items have attributes which can be queried using the interfaces Trust items have attributes which can be queried using the interfaces
below. The attribute identifiers are shared with those for key below. The attribute identifiers are shared with those for key
attributes. @xref{Information about keys}. attributes. @xref{Information About Keys}.
@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}}) @deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
The function @code{gpgme_trust_item_get_string_attr} returns the value The function @code{gpgme_trust_item_get_string_attr} returns the value
@ -1562,8 +1563,8 @@ or @var{reserved} not @code{NULL}.
@end deftypefun @end deftypefun
@node Manipulating trust items @node Manipulating Trust Items
@subsection Manipulating trust items @subsection Manipulating Trust Items
@deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}}) @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
The function @code{gpgme_trust_item_release} destroys a The function @code{gpgme_trust_item_release} destroys a
@ -1576,9 +1577,10 @@ The function @code{gpgme_trust_item_release} destroys a
@menu @menu
* Decrypt:: Decrypting a ciphertext. * Decrypt:: Decrypting a ciphertext.
* Verify:: Verifying a signature. * Verify:: Verifying a signature.
* Decrypt and verify:: Decrypting a signed ciphertext. * Decrypt and Verify:: Decrypting a signed ciphertext.
* Sign:: Creating a signature. * Sign:: Creating a signature.
* Encrypt:: Encrypting a plaintext. * Encrypt:: Encrypting a plaintext.
* More Information:: How to obtain more info about the operation.
@end menu @end menu
@ -1708,9 +1710,23 @@ pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
if a problem occured requesting the key. if a problem occured requesting the key.
@end deftypefun @end deftypefun
@deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_get_notation} can be used to retrieve
notation data from the last signature check in the context @var{ctx}.
@node Decrypt and verify If there is notation data available from the last signature check,
@subsection Decrypt and verify this function may be used to return this notation data as a string.
The string is an XML represantaton of that data embedded in a
<notation> container. The user has to release the string with
@code{free}.
The function returns a string if the notation data is available or
@code{NULL} if there is no such data available.
@end deftypefun
@node Decrypt and Verify
@subsection Decrypt and Verify
@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}}) @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
@ -1744,13 +1760,13 @@ applied to all following signing operations in this context (until the
set is changed). set is changed).
@menu @menu
* Selecting signers:: How to choose the keys to sign with. * Selecting Signers:: How to choose the keys to sign with.
* Creating a signature:: How to create a signature. * Creating a Signature:: How to create a signature.
@end menu @end menu
@node Selecting signers @node Selecting Signers
@subsubsection Selecting signers @subsubsection Selecting Signers
@deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}}) @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_signers_clear} releases a reference for each The function @code{gpgme_signers_clear} releases a reference for each
@ -1777,8 +1793,8 @@ If @var{seq} is out of range, @code{NULL} is returned.
@end deftypefun @end deftypefun
@node Creating a signature @node Creating a Signature
@subsubsection Creating a signature @subsubsection Creating a Signature
@deftp {Data type} {enum GpgmeSigMode} @deftp {Data type} {enum GpgmeSigMode}
The @code{GpgmeSigMode} type is used to specify the desired type of a The @code{GpgmeSigMode} type is used to specify the desired type of a
@ -1805,6 +1821,9 @@ the data object @var{plain} and returns it in the data object
@acronym{ASCII} armor and text mode attributes set for the context @acronym{ASCII} armor and text mode attributes set for the context
@var{ctx} and the requested signature mode @var{mode}. @var{ctx} and the requested signature mode @var{mode}.
More information about the signatures is available with
@code{gpgme_get_op_info}. @xref{More Information}.
The function returns @code{GPGME_No_Error} if the signature could be The function returns @code{GPGME_No_Error} if the signature could be
created successfully, @code{GPGME_Invalid_Value} if @var{ctx}, created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data} @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
@ -1823,13 +1842,13 @@ time. The list of recipients is created independently of any context,
and then passed to the encryption operation. and then passed to the encryption operation.
@menu @menu
* Selecting recipients:: How to choose the recipients. * Selecting Recipients:: How to choose the recipients.
* Encrypting a plaintext:: How to encrypt a plaintext. * Encrypting a Plaintext:: How to encrypt a plaintext.
@end menu @end menu
@node Selecting recipients @node Selecting Recipients
@subsubsection Selecting recipients @subsubsection Selecting Recipients
@deftp {Data type} GpgmeRecipients @deftp {Data type} GpgmeRecipients
The @code{GpgmeRecipients} type is a handle for a set of recipients The @code{GpgmeRecipients} type is a handle for a set of recipients
@ -1867,7 +1886,7 @@ The function @code{gpgme_recipients_add_name_with_validity} adds the
recipient @var{name} with the validity @var{val} to the set of recipient @var{name} with the validity @var{val} to the set of
recipients @var{rset}. If the validity is not known, the function recipients @var{rset}. If the validity is not known, the function
@code{gpgme_recipients_add_name} can be used. @code{gpgme_recipients_add_name} can be used.
@xref{Information about keys}, for the possible values for @var{val}. @xref{Information About Keys}, for the possible values for @var{val}.
The function returns @code{GPGME_No_Error} if the recipient was added The function returns @code{GPGME_No_Error} if the recipient was added
successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name} successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
@ -1907,8 +1926,8 @@ The function @code{gpgme_recipients_enum_close} releases the iterator
@end deftypefun @end deftypefun
@node Encrypting a plaintext @node Encrypting a Plaintext
@subsubsection Encrypting a plaintext @subsubsection Encrypting a Plaintext
@deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}}) @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
The function @code{gpgme_op_crypt} encrypts the plaintext in the data The function @code{gpgme_op_crypt} encrypts the plaintext in the data
@ -1917,6 +1936,9 @@ ciphertext in the data object @var{cipher}. The type of the
ciphertext created is determined by the @acronym{ASCII} armor and text ciphertext created is determined by the @acronym{ASCII} armor and text
mode attributes set for the context @var{ctx}. mode attributes set for the context @var{ctx}.
More information about the encrypted text is available with
@code{gpgme_get_op_info}. @xref{More Information}.
The function returns @code{GPGME_No_Error} if the ciphertext could be The function returns @code{GPGME_No_Error} if the ciphertext could be
created successfully, @code{GPGME_Invalid_Value} if @var{ctx}, created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
@ -1927,6 +1949,108 @@ are reported by the crypto engine support routines.
@end deftypefun @end deftypefun
@node More Information
@subsection More Information
@deftypefun char *gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
The function @code{gpgme_get_op_info} retrieves more informaton about
the last crypto operation.
The function returns a string in the XML format. The user has to
release the string with @code{free}.
Here is a sample of the information that might be returned:
@example
<literal>
<![CDATA[
<GnupgOperationInfo>
<signature>
<detached/> <!-- or cleartext or standard -->
<algo>17</algo>
<hashalgo>2</hashalgo>
<micalg>pgp-sha1</micalg>
<sigclass>01</sigclass>
<created>9222222</created>
<fpr>121212121212121212</fpr>
</signature>
</GnupgOperationInfo>
]]>
</literal>
@end example
Currently, the only operations that return additional information are
encrypt and sign. @xref{Encrypt}, @xref{Sign}.
The function returns a string or @code{NULL} if no such data is
available.
@end deftypefun
@node Run Control
@section Run Control
Some basic support for running operations asynchronously is available
in @acronym{GPGME}. You can use it to set up a context completely up
to initiating the desired operation, but delay performing it to a
later point.
@menu
* Waiting For Completion:: Waiting until an operation is completed.
* Cancelling an Operation:: Interrupting a running operation.
* Hooking Up Into Idle Time:: Doing something when nothing has to be done.
@end menu
@node Waiting For Completion
@subsection Waiting For Completion
@deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{int @var{hang}})
The function @code{gpgme_wait} does continue the pending operation
within the context @var{ctx}. In particular, it ensures the data
exchange between @acronym{GPGME} and the crypto backend and watches
over the run time status of the backend process.
If @var{hang} is true, the function does not return until the
operation is completed or cancelled. Otherwise the function will not
block for a long time.
The function returns @var{ctx}.
@end deftypefun
@node Cancelling an Operation
@subsection Cancelling an Operation
@deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_cancel} tries to cancel the pending
operation. The function @code{gpgme_wait} might notice the
cancellation flag and return. It is currently not guaranteed to work
under all circumstances. It's current primary purpose is to prevent
asking for a passphrase again in the passphrase callback.
@end deftypefun
@node Hooking Up Into Idle Time
@subsection Hooking Up Into Idle Time
@deftp {Data type} {void (*GpgmeIdleFnc) (void)}
The @code{GpgmeIdleFunc} type is the type of functions usable as
an idle function that can be registered with @code{gpgme_register_idle}.
@end deftp
@deftypefun GpgmeIdleFunc gpgme_register_idle (@w{GpgmeIdleFunc @var{idle}})
The function @code{gpgme_register_idle} can be used to register
@var{idle} as the idle function.
@var{idle} will be called whenever @acronym{GPGME} thinks that it is
idle and time can better be spent elsewhere. Setting @var{idle} to
@code{NULL} disables use of the idle function (this is the default).
The function returns the old idle function, or @code{NULL} if none was
registered yet.
@end deftypefun
@include gpl.texi @include gpl.texi

7
gpgme/ChangeLog
View File

@ -1,3 +1,10 @@
2002-01-29 Marcus Brinkmann <marcus@g10code.de>
* gpgme.h: Add new type GpgmeIdleFunc. Change type of
gpgme_register_idle to return and accept this type.
* wait.c (gpgme_register_idle): Fix type.
Save and return old value of idle_function.
2002-01-29 Werner Koch <wk@gnupg.org> 2002-01-29 Werner Koch <wk@gnupg.org>
* engine-gpgsm.c (_gpgme_gpgsm_op_keylist): Implement secret only mode. * engine-gpgsm.c (_gpgme_gpgsm_op_keylist): Implement secret only mode.

11
gpgme/gpgme.h
View File

@ -311,7 +311,9 @@ const char *gpgme_check_version (const char *req_version);
GpgmeError gpgme_check_engine (void); GpgmeError gpgme_check_engine (void);
const char *gpgme_get_engine_info (void); const char *gpgme_get_engine_info (void);
const char *gpgme_strerror (GpgmeError err); const char *gpgme_strerror (GpgmeError err);
void gpgme_register_idle (void (*fnc)(void));
typedef void (*GpgmeIdleFunc)(void);
GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
/* Engine support functions. */ /* Engine support functions. */
GpgmeError gpgme_engine_check_version (GpgmeProtocol proto); GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
@ -320,10 +322,3 @@ GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
} }
#endif #endif
#endif /* GPGME_H */ #endif /* GPGME_H */

15
gpgme/wait.c
View File

@ -46,7 +46,7 @@ static int fd_table_size;
static struct io_select_fd_s *fd_table; static struct io_select_fd_s *fd_table;
DEFINE_STATIC_LOCK (fd_table_lock); DEFINE_STATIC_LOCK (fd_table_lock);
static void (*idle_function) (void); static GpgmeIdleFunc idle_function;
struct proc_s { struct proc_s {
@ -401,11 +401,18 @@ _gpgme_thaw_fd (int fd)
* *
* Register a function with GPGME called by GPGME whenever it feels * Register a function with GPGME called by GPGME whenever it feels
* that is is idle. NULL may be used to remove this function. * that is is idle. NULL may be used to remove this function.
*
* Return value: The idle function pointer that was passed to the
* function at the last time it was invoked, or NULL if the function
* is invoked the first time.
**/ **/
void GpgmeIdleFunc
gpgme_register_idle (void (*fnc)(void)) gpgme_register_idle (GpgmeIdleFunc idle)
{ {
idle_function = fnc; GpgmeIdleFunc old_idle = idle_function;
idle_function = idle;
return old_idle;
} }