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

doc/

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

	* gpgme.texi: Add all the gpgme_op_*_start functions.
	Fill the concept index with many, many entries.

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

	* gpgme.h: Add lots of comment and fix the formatting.  Add
	gpgme_trustlist_end prototype.
This commit is contained in:
Marcus Brinkmann 2002-01-30 01:17:30 +00:00
parent 89dd219f8d
commit 785991aa9a
4 changed files with 638 additions and 227 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/ChangeLog
View File

@ -1,3 +1,8 @@
2002-01-30 Marcus Brinkmann <marcus@g10code.de>
* gpgme.texi: Add all the gpgme_op_*_start functions.
Fill the concept index with many, many entries.
2002-01-29 Marcus Brinkmann <marcus@g10code.de>
* gpgme.texi (Run Control): New section.

258
doc/gpgme.texi
View File

@ -149,8 +149,8 @@ Key Management
* Manipulating Keys:: Operations on keys.
* Generating Keys:: Creating new key pairs.
* Exporting Keys:: Retrieving key data from the key ring.
* Importing Keys:: Adding keys to the keyring.
* Deleting Keys:: Removing keys from the keyring.
* Importing Keys:: Adding keys to the key ring.
* Deleting Keys:: Removing keys from the key ring.
Trust Item Management
@ -165,7 +165,7 @@ Crypto Operations
* Decrypt and Verify:: Decrypting a signed ciphertext.
* Sign:: Creating a signature.
* Encrypt:: Encrypting a plaintext.
* More Information:: How to obtain more info about the operation.
* Detailed Results:: How to obtain more info about the operation.
Sign
@ -213,7 +213,7 @@ This library documents the @acronym{GPGME} library programming
interface. All functions and data types provided by the library are
explained.
The reader is assumed to posess basic knowledge about cryptography in
The reader is assumed to possess basic knowledge about cryptography in
general, and public key cryptography in particular. The underlying
cryptographic engines that are used by the library are not explained,
but where necessary, special features or requirements by an engine are
@ -277,6 +277,8 @@ including listing keys, querying their attributes, generating,
importing, exporting and deleting keys, and acquiring information
about the trust path.
@cindex thread-safeness
@cindex multi-threading
@strong{Caution:} The @acronym{GPGME} library is not thread-safe. It
will be to some extent in the future, but currently great care has to
be taken if @acronym{GPGME} is used in a multi-threaded environment.
@ -300,6 +302,8 @@ of the library are verified.
@node Header
@section Header
@cindex header file
@cindex include file
All interfaces (data types and functions) of the library are defined
in the header file `gpgme.h'. You must include this in all programs
@ -317,6 +321,8 @@ symbols.
@node Building the Source
@section Building the Source
@cindex compiler options
@cindex compiler flags
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
@ -364,6 +370,7 @@ gcc -o foo foo.c `gpgme-config --cflags --libs`
@node Library Version Check
@section Library Version Check
@cindex version check, of the library
@deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
The function @code{gpgme_check_version} has three purposes. It can be
@ -396,6 +403,11 @@ features are provided by the installed version of the library.
@node Protocols and Engines
@chapter Protocols and Engines
@cindex protocol
@cindex engine
@cindex crypto engine
@cindex backend
@cindex crypto backend
@acronym{GPGME} supports several cryptographic protocols, however, it
does not implement them. Rather it uses backends (also called
@ -409,6 +421,7 @@ necessary, @acronym{GPGME} provides the necessary callback function
hooks and further interfaces.
@deftp {Data type} {enum GpgmeProtocol}
@tindex GpgmeProtocol
The @code{GpgmeProtocol} type specifies the set of possible protocol
values that are supported by @acronym{GPGME}. The following protocols
are supported:
@ -431,6 +444,7 @@ This specifies the Cryptographic Message Syntax.
@node Engine Version Check
@section Engine Version Check
@cindex version check, of the engines
@deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
The function @code{gpgme_engine_check_version} verifies that the
@ -455,6 +469,7 @@ only. It is obsoleted by @code{gpgme_engine_check_version}.
@node Engine Information
@section Engine Information
@cindex engine, information about
@deftypefun {const char *} gpgme_get_engine_info (void)
The function @code{gpgme_get_engine_info} returns an @acronym{XML}
@ -496,6 +511,10 @@ return on your system:
@node OpenPGP
@section OpenPGP
@cindex OpenPGP
@cindex GnuPG
@cindex protocol, GnuPG
@cindex engine, GnuPG
OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
This is the first protocol that was supported by @acronym{GPGME}.
@ -505,6 +524,13 @@ The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
@node Cryptographic Message Syntax
@section Cryptographic Message Syntax
@cindex CMS
@cindex cryptographic message syntax
@cindex GpgSM
@cindex protocol, CMS
@cindex engine, GpgSM
@cindex S/MIME
@cindex protocol, S/MIME
@acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
GnuPG.
@ -514,6 +540,7 @@ The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
@node Error Handling
@chapter Error Handling
@cindex error handling
Many functions in @acronym{GPGME} can return an error if they fail.
For this reason, the application should always catch the error
@ -538,8 +565,10 @@ described in the documentation of those functions.
@node Error Values
@section Error Values
@cindex error values, list of
@deftp {Data type} {enum GpgmeError}
@tindex GpgmeError
The @code{GpgmeError} type specifies the set of all error values that
are used by @acronym{GPGME}. Possible values are:
@ -644,6 +673,8 @@ engine is not installed properly.
@node Error Strings
@section Error Strings
@cindex error values, printing of
@cindex error strings
@deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
The function @code{gpgme_strerror} returns a pointer to a statically
@ -655,6 +686,7 @@ message to the user.
@node Exchanging Data
@chapter Exchanging Data
@cindex data, exchanging
A lot of data has to be exchanged between the user and the crypto
engine, like plaintext messages, ciphertext, signatures and
@ -678,6 +710,7 @@ data, which is used by @acronym{GPGME} to exchange data with the user.
@node Creating Data Buffers
@section Creating Data Buffers
@cindex data buffer, creation
@deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
The function @code{gpgme_data_new} creates a new @code{GpgmeData}
@ -768,6 +801,7 @@ not enough memory is available.
@node Destroying Data Buffers
@section Destroying Data Buffers
@cindex data buffer, destruction
@deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
The function @code{gpgme_data_release} destroys the data object with
@ -791,6 +825,7 @@ be returned to the user, the function will return @code{NULL}.
@node Manipulating Data Buffers
@section Manipulating Data Buffers
@cindex data buffere, manipulation
@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
@ -836,6 +871,7 @@ available.
@end deftypefun
@deftp {Data type} {enum GpgmeDataType}
@tindex GpgmeDataType
The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
The following data types are available:
@ -867,6 +903,7 @@ object with the handle @var{dh}. If @var{dh} is not a valid pointer,
@node Contexts
@chapter Contexts
@cindex context
All cryptograhic operations in @acronym{GPGME} are performed within a
context, which contains the internal state of the operation as well as
@ -893,6 +930,7 @@ cryptographic operations.
@node Creating Contexts
@section Creating Contexts
@cindex context, creation
@deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
@ -905,9 +943,9 @@ available.
@end deftypefun
@node Destroying Contexts
@section Destroying Contexts
@cindex context, destruction
@deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_release} destroys the context with the handle
@ -917,6 +955,7 @@ The function @code{gpgme_release} destroys the context with the handle
@node Context Attributes
@section Context Attributes
@cindex context, attributes
@menu
* Protocol Selection:: Selecting the protocol used by a context.
@ -930,6 +969,8 @@ The function @code{gpgme_release} destroys the context with the handle
@node Protocol Selection
@subsection Protocol Selection
@cindex context, selecting protocol
@cindex protocol, selecting
@deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
The function @code{gpgme_set_protocol} sets the protocol used within
@ -949,6 +990,9 @@ not a valid protocol.
@node @acronym{ASCII} Armor
@subsection @acronym{ASCII} Armor
@cindex context, armor mode
@cindex @acronym{ASCII} armor
@cindex armor mode
@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
@ -968,6 +1012,9 @@ not a valid pointer.
@node Text Mode
@subsection Text Mode
@cindex context, text mode
@cindex text mode
@cindex canonical text mode
@deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
The function @code{gpgme_set_textmode} specifies if canonical text mode
@ -990,6 +1037,8 @@ valid pointer.
@node Key Listing Mode
@subsection Key Listing Mode
@cindex key listing mode
@cindex key listing, mode of
@deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
The function @code{gpgme_set_keylist_mode} changes the default
@ -1007,8 +1056,11 @@ Fast listing without information about the key validity.
@node Passphrase Callback
@subsection Passphrase Callback
@cindex callback, passphrase
@cindex passphrase callback
@deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
@tindex GpgmePassphraseCb
The @code{GpgmePasshraseCb} type is the type of functions usable as
passphrase callback function.
@ -1044,8 +1096,11 @@ calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
@node Progress Meter Callback
@subsection Progress Meter Callback
@cindex callback, progress meter
@cindex 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})}
@tindex GpgmeProgressCb
The @code{GpgmeProgressCb} type is the type of functions usable as
progress callback function.
@ -1074,6 +1129,7 @@ calling @code{gpgme_set_progress_cb} with @var{progfunc} being
@node Key Management
@section Key Management
@cindex key management
Some of the cryptographic operations require that recipients or
signers are specified. This is always done by specifying the
@ -1093,13 +1149,18 @@ A key can contain several user IDs and sub keys.
* Manipulating Keys:: Operations on keys.
* Generating Keys:: Creating new key pairs.
* Exporting Keys:: Retrieving key data from the key ring.
* Importing Keys:: Adding keys to the keyring.
* Deleting Keys:: Removing keys from the keyring.
* Importing Keys:: Adding keys to the key ring.
* Deleting Keys:: Removing keys from the key ring.
@end menu
@node Listing Keys
@subsection Listing Keys
@cindex listing keys
@cindex key listing
@cindex key listing, start
@cindex key ring, list
@cindex key ring, search
@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
@ -1154,6 +1215,9 @@ operation there was not enough memory available.
@node Information About Keys
@subsection Information About Keys
@cindex key, information about
@cindex key, attributes
@cindex attributes, of a key
@deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
The function @code{gpgme_key_get_as_xml} returns a string in
@ -1344,6 +1408,7 @@ or @var{reserved} not @code{NULL}.
@node Manipulating Keys
@subsection Manipulating Keys
@cindex key, manipulation
@deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
The function @code{gpgme_key_ref} acquires an additional reference for
@ -1363,10 +1428,12 @@ The function @code{gpgme_key_release} is an alias for
@node Generating Keys
@subsection Generating Keys
@cindex key, creation
@cindex key ring, add
@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
context @var{ctx} and puts it into the standard keyring if both
context @var{ctx} and puts it into the standard key ring if both
@var{pubkey} and @var{seckey} are @code{NULL}. In this case the
function returns immediately after starting the operation, and does
not wait for it to complete. @var{pubkey} and @var{seckey} are
@ -1377,7 +1444,7 @@ implemented yet).
The argument @var{parms} specifies parameters for the key in an XML
string. The details about the format of @var{parms} are specific to
teh crypto engine used by @var{ctx}. Here is an example for GnuPG as
the crypto engine used by @var{ctx}. Here is an example for GnuPG as
the crypto engine:
@example
@ -1404,14 +1471,27 @@ container is passed verbatim to GnuPG. Control statements are not
allowed.
The function returns @code{GPGME_No_Error} if the operation could be
started, @code{GPGME_Invalid_Value} if @var{parms} is not a valid XML
string, and @code{GPGME_Not_Supported} if @var{pubkey} or @var{seckey}
is not @code{NULL}.
started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
@var{seckey} is not @code{NULL}.
@end deftypefun
@deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
The function @code{gpgme_op_genkey_start} initiates a
@code{gpgme_op_genkey} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
@var{seckey} is not @code{NULL}.
@end deftypefun
@node Exporting Keys
@subsection Exporting Keys
@cindex key, export
@cindex key ring, export from
@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
@ -1426,9 +1506,22 @@ passes through any errors that are reported by the crypto engine
support routines.
@end deftypefun
@deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
The function @code{gpgme_op_export_start} initiates a
@code{gpgme_op_export} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, and @code{GPGME_Invalid_Value} if
@var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
data buffer.
@end deftypefun
@node Importing Keys
@subsection Importing Keys
@cindex key, import
@cindex key ring, import to
@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
@ -1442,9 +1535,22 @@ or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
@var{keydata} is an empty data buffer.
@end deftypefun
@deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
The function @code{gpgme_op_import_start} initiates a
@code{gpgme_op_import} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the import could be
started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
@var{ctx} or @var{keydata} is not a valid pointer, and
@code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
@end deftypefun
@node Deleting Keys
@subsection Deleting Keys
@cindex key, delete
@cindex key ring, delete from
@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
@ -1457,9 +1563,20 @@ successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or @var{key}
is not a valid pointer.
@end deftypefun
@deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
The function @code{gpgme_op_delete_start} initiates a
@code{gpgme_op_delete} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation was
started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
@var{key} is not a valid pointer.
@end deftypefun
@node Trust Item Management
@section Trust Item Management
@cindex trust item
@strong{Caution:} The trust items interface is experimental.
@ -1476,6 +1593,7 @@ The @code{GpgmeTrustItem} type is a handle for a trust item.
@node Listing Trust Items
@subsection Listing Trust Items
@cindex trust item list
@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
@ -1529,6 +1647,9 @@ operation there was not enough memory available.
@node Information About Trust Items
@subsection Information About Trust Items
@cindex trust item, information about
@cindex trust item, attributes
@cindex attributes, of a trust item
Trust items have attributes which can be queried using the interfaces
below. The attribute identifiers are shared with those for key
@ -1565,6 +1686,7 @@ or @var{reserved} not @code{NULL}.
@node Manipulating Trust Items
@subsection Manipulating Trust Items
@cindex trust item, manipulation
@deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
The function @code{gpgme_trust_item_release} destroys a
@ -1573,6 +1695,7 @@ The function @code{gpgme_trust_item_release} destroys a
@node Crypto Operations
@section Crypto Operations
@cindex cryptographic operation
@menu
* Decrypt:: Decrypting a ciphertext.
@ -1580,12 +1703,14 @@ The function @code{gpgme_trust_item_release} destroys a
* Decrypt and Verify:: Decrypting a signed ciphertext.
* Sign:: Creating a signature.
* Encrypt:: Encrypting a plaintext.
* More Information:: How to obtain more info about the operation.
* Detailed Results:: How to obtain more info about the operation.
@end menu
@node Decrypt
@subsection Decrypt
@cindex decryption
@cindex cryptographic operation, decryption
@deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
@ -1602,22 +1727,27 @@ secret key could not be retrieved, and passes through any errors that
are reported by the crypto engine support routines.
@end deftypefun
@c @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
@c The function @code{gpgme_op_decrypt_start} initiates a
@c @code{gpgme_op_decrypt} operation. It can be completed by calling
@c @code{gpgme_wait} on the context.
@deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
The function @code{gpgme_op_decrypt_start} initiates a
@code{gpgme_op_decrypt} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
@c The function returns @code{GPGME_No_Error} if the operation could be
@c started, @code{GPGME_Invalid_Value} if @var{cipher} or @var{plain} is
@c not a valid pointer, and passes through any errors that are reported
@c by the crypto engine support routines.
@c @end deftypefun
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
or @var{plain} is not a valid pointer.
@end deftypefun
@node Verify
@subsection Verify
@cindex verification
@cindex signature, verification
@cindex cryptographic operation, verification
@cindex cryptographic operation, signature check
@cindex signature, status
@deftp {Data type} {enum GpgmeSigStat}
@tindex GpgmeSigStat
The @code{GpgmeSigStat} type holds the result of a signature check, or
the combined result of all signatures. The following results are
possible:
@ -1671,7 +1801,17 @@ data to verify, and passes through any errors that are reported by the
crypto engine support routines.
@end deftypefun
@c GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig, GpgmeData plain);
@deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
The function @code{gpgme_op_verify_start} initiates a
@code{gpgme_op_verify} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
data to verify.
@end deftypefun
@deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
The function @code{gpgme_get_sig_status} receives information about a
@ -1727,6 +1867,10 @@ The function returns a string if the notation data is available or
@node Decrypt and Verify
@subsection Decrypt and Verify
@cindex decryption and verification
@cindex verification and decryption
@cindex signature check
@cindex cryptographic operation, decryption and verification
@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
@ -1748,11 +1892,25 @@ secret key could not be retrieved, and passes through any errors that
are reported by the crypto engine support routines.
@end deftypefun
@c GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, GpgmeData in, GpgmeData out, GpgmeSigStat *r_status);
@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
The function @code{gpgme_op_decrypt_verify_start} initiates a
@code{gpgme_op_decrypt_verify} operation. It can be completed by
calling @code{gpgme_wait} on the context. @xref{Waiting For
Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
@code{GPGME_No_Data} if @var{cipher} does not contain any data to
decrypt.
@end deftypefun
@node Sign
@subsection Sign
@cindex signature, creation
@cindex sign
@cindex cryptographic operation, signing
A signature can contain signatures by one or more keys. The set of
keys used to create a signatures is contained in a context, and is
@ -1767,6 +1925,8 @@ set is changed).
@node Selecting Signers
@subsubsection Selecting Signers
@cindex signature, selecting signers
@cindex signers, selecting
@deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_signers_clear} releases a reference for each
@ -1776,7 +1936,6 @@ context @var{ctx}.
Every context starts with an empty list.
@end deftypefun
@deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
The function @code{gpgme_signers_add} adds the key @var{key} to the
list of signers in the context @var{ctx}.
@ -1797,6 +1956,7 @@ If @var{seq} is out of range, @code{NULL} is returned.
@subsubsection Creating a Signature
@deftp {Data type} {enum GpgmeSigMode}
@tindex GpgmeSigMode
The @code{GpgmeSigMode} type is used to specify the desired type of a
signature. The following modes are available:
@ -1822,7 +1982,7 @@ the data object @var{plain} and returns it in the data object
@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}.
@code{gpgme_get_op_info}. @xref{Detailed Results}.
The function returns @code{GPGME_No_Error} if the signature could be
created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@ -1833,9 +1993,21 @@ through any errors that are reported by the crypto engine support
routines.
@end deftypefun
@deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
The function @code{gpgme_op_sign_start} initiates a
@code{gpgme_op_sign} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
@var{plain} or @var{sig} is not a valid pointer.
@end deftypefun
@node Encrypt
@subsection Encrypt
@cindex encryption
@cindex cryptographic operation, encryption
One plaintext can be encrypted for several recipients at the same
time. The list of recipients is created independently of any context,
@ -1849,6 +2021,8 @@ and then passed to the encryption operation.
@node Selecting Recipients
@subsubsection Selecting Recipients
@cindex encryption, selecting recipients
@cindex recipients
@deftp {Data type} GpgmeRecipients
The @code{GpgmeRecipients} type is a handle for a set of recipients
@ -1937,7 +2111,7 @@ ciphertext created is determined by the @acronym{ASCII} armor and text
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}.
@code{gpgme_get_op_info}. @xref{Detailed Results}.
The function returns @code{GPGME_No_Error} if the ciphertext could be
created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@ -1948,11 +2122,24 @@ secret key could not be retrieved, and passes through any errors that
are reported by the crypto engine support routines.
@end deftypefun
@deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
The function @code{gpgme_op_encrypt_start} initiates a
@code{gpgme_op_encrypt} operation. It can be completed by calling
@code{gpgme_wait} on the context. @xref{Waiting For Completion}.
@node More Information
@subsection More Information
The function returns @code{GPGME_No_Error} if the operation could be
started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
@code{GPGME_No_Recipient} if @var{rset} does not contain any valid
recipients.
@end deftypefun
@deftypefun char *gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
@node Detailed Results
@subsection Detailed Results
@cindex cryptographic operation, detailed results
@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.
@ -1988,6 +2175,8 @@ available.
@node Run Control
@section Run Control
@cindex run control
@cindex cryptographic operation, running
Some basic support for running operations asynchronously is available
in @acronym{GPGME}. You can use it to set up a context completely up
@ -2003,6 +2192,8 @@ later point.
@node Waiting For Completion
@subsection Waiting For Completion
@cindex cryptographic operation, wait for
@cindex wait for completion
@deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{int @var{hang}})
The function @code{gpgme_wait} does continue the pending operation
@ -2020,6 +2211,8 @@ The function returns @var{ctx}.
@node Cancelling an Operation
@subsection Cancelling an Operation
@cindex cancellation
@cindex cryptographic operation, cancel
@deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
The function @code{gpgme_cancel} tries to cancel the pending
@ -2032,8 +2225,11 @@ asking for a passphrase again in the passphrase callback.
@node Hooking Up Into Idle Time
@subsection Hooking Up Into Idle Time
@cindex idle time
@cindex idle function
@deftp {Data type} {void (*GpgmeIdleFnc) (void)}
@deftp {Data type} {void (*GpgmeIdleFunc) (void)}
@tindex GpgmeIdleFunc
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

5
gpgme/ChangeLog
View File

@ -1,3 +1,8 @@
2002-01-30 Marcus Brinkmann <marcus@g10code.de>
* gpgme.h: Add lots of comment and fix the formatting. Add
gpgme_trustlist_end prototype.
2002-01-29 Marcus Brinkmann <marcus@g10code.de>
* gpgme.h: Add new type GpgmeIdleFunc. Change type of

597
gpgme/gpgme.h
View File

@ -22,7 +22,7 @@
#ifndef GPGME_H
#define GPGME_H
#include <stdio.h> /* for FILE * */
#include <stdio.h> /* For FILE *. */
#ifdef _MSC_VER
typedef long off_t;
#else
@ -37,287 +37,492 @@ extern "C" {
#endif
/*
* The version of this header should match the one of the library
* It should not be used by a program because gpgme_check_version(NULL)
* does return the same version. The purpose of this macro is to
* let autoconf (using the AM_PATH_GPGME macro) check that this
* header matches the installed library.
* Warning: Do not edit the next line. configure will do that for you! */
/* The version of this header should match the one of the library. Do
not use this symbol in your application, use gpgme_check_version
instead. The purpose of this macro is to let autoconf (using the
AM_PATH_GPGME macro) check that this header matches the installed
library. Warning: Do not edit the next line. configure will do
that for you! */
#define GPGME_VERSION "0.3.0a-cvs"
/* The opaque data types used by GPGME. */
/* The context holds some global state and configration options as
well as the results of a crypto operation. */
struct gpgme_context_s;
typedef struct gpgme_context_s *GpgmeCtx;
/* The data object used by GPGME to exchange arbitrary data. */
struct gpgme_data_s;
typedef struct gpgme_data_s *GpgmeData;
/* A list of recipients to be used in an encryption operation. */
struct gpgme_recipients_s;
typedef struct gpgme_recipients_s *GpgmeRecipients;
/* A key from the keyring. */
struct gpgme_key_s;
typedef struct gpgme_key_s *GpgmeKey;
/* A trust item. */
struct gpgme_trust_item_s;
typedef struct gpgme_trust_item_s *GpgmeTrustItem;
typedef enum {
GPGME_EOF = -1,
GPGME_No_Error = 0,
GPGME_General_Error = 1,
GPGME_Out_Of_Core = 2,
GPGME_Invalid_Value = 3,
GPGME_Busy = 4,
GPGME_No_Request = 5,
GPGME_Exec_Error = 6,
GPGME_Too_Many_Procs = 7,
GPGME_Pipe_Error = 8,
GPGME_No_Recipients = 9,
GPGME_No_Data = 10,
GPGME_Conflict = 11,
GPGME_Not_Implemented = 12,
GPGME_Read_Error = 13,
GPGME_Write_Error = 14,
GPGME_Invalid_Type = 15,
GPGME_Invalid_Mode = 16,
GPGME_File_Error = 17, /* errno is set in this case */
/* The error numbers used by GPGME. */
typedef enum
{
GPGME_EOF = -1,
GPGME_No_Error = 0,
GPGME_General_Error = 1,
GPGME_Out_Of_Core = 2,
GPGME_Invalid_Value = 3,
GPGME_Busy = 4,
GPGME_No_Request = 5,
GPGME_Exec_Error = 6,
GPGME_Too_Many_Procs = 7,
GPGME_Pipe_Error = 8,
GPGME_No_Recipients = 9,
GPGME_No_Data = 10,
GPGME_Conflict = 11,
GPGME_Not_Implemented = 12,
GPGME_Read_Error = 13,
GPGME_Write_Error = 14,
GPGME_Invalid_Type = 15,
GPGME_Invalid_Mode = 16,
GPGME_File_Error = 17, /* errno is set in this case. */
GPGME_Decryption_Failed = 18,
GPGME_No_Passphrase = 19,
GPGME_Canceled = 20,
GPGME_Invalid_Key = 21,
GPGME_Invalid_Engine = 22
} GpgmeError;
GPGME_No_Passphrase = 19,
GPGME_Canceled = 20,
GPGME_Invalid_Key = 21,
GPGME_Invalid_Engine = 22
}
GpgmeError;
typedef enum {
/* The possible types of GpgmeData objects. */
typedef enum
{
GPGME_DATA_TYPE_NONE = 0,
GPGME_DATA_TYPE_MEM = 1,
GPGME_DATA_TYPE_FD = 2,
GPGME_DATA_TYPE_FILE = 3,
GPGME_DATA_TYPE_CB = 4
} GpgmeDataType;
}
GpgmeDataType;
typedef enum {
GPGME_SIG_STAT_NONE = 0,
GPGME_SIG_STAT_GOOD = 1,
GPGME_SIG_STAT_BAD = 2,
/* The possible signature stati. */
typedef enum
{
GPGME_SIG_STAT_NONE = 0,
GPGME_SIG_STAT_GOOD = 1,
GPGME_SIG_STAT_BAD = 2,
GPGME_SIG_STAT_NOKEY = 3,
GPGME_SIG_STAT_NOSIG = 4,
GPGME_SIG_STAT_ERROR = 5,
GPGME_SIG_STAT_DIFF = 6
} GpgmeSigStat;
}
GpgmeSigStat;
typedef enum {
/* The available signature modes. */
typedef enum
{
GPGME_SIG_MODE_NORMAL = 0,
GPGME_SIG_MODE_DETACH = 1,
GPGME_SIG_MODE_CLEAR = 2
} GpgmeSigMode;
GPGME_SIG_MODE_CLEAR = 2
}
GpgmeSigMode;
typedef enum {
GPGME_ATTR_KEYID = 1,
GPGME_ATTR_FPR = 2,
GPGME_ATTR_ALGO = 3,
GPGME_ATTR_LEN = 4,
GPGME_ATTR_CREATED = 5,
GPGME_ATTR_EXPIRE = 6,
GPGME_ATTR_OTRUST = 7,
GPGME_ATTR_USERID = 8,
GPGME_ATTR_NAME = 9,
GPGME_ATTR_EMAIL = 10,
GPGME_ATTR_COMMENT = 11,
GPGME_ATTR_VALIDITY= 12,
GPGME_ATTR_LEVEL = 13,
GPGME_ATTR_TYPE = 14,
GPGME_ATTR_IS_SECRET= 15,
GPGME_ATTR_KEY_REVOKED = 16,
GPGME_ATTR_KEY_INVALID = 17,
GPGME_ATTR_UID_REVOKED = 18,
GPGME_ATTR_UID_INVALID = 19,
GPGME_ATTR_KEY_CAPS = 20,
GPGME_ATTR_CAN_ENCRYPT = 21,
GPGME_ATTR_CAN_SIGN = 22,
GPGME_ATTR_CAN_CERTIFY = 23,
GPGME_ATTR_KEY_EXPIRED = 24,
GPGME_ATTR_KEY_DISABLED= 25
} GpgmeAttr;
/* The available key attributes. */
typedef enum
{
GPGME_ATTR_KEYID = 1,
GPGME_ATTR_FPR = 2,
GPGME_ATTR_ALGO = 3,
GPGME_ATTR_LEN = 4,
GPGME_ATTR_CREATED = 5,
GPGME_ATTR_EXPIRE = 6,
GPGME_ATTR_OTRUST = 7,
GPGME_ATTR_USERID = 8,
GPGME_ATTR_NAME = 9,
GPGME_ATTR_EMAIL = 10,
GPGME_ATTR_COMMENT = 11,
GPGME_ATTR_VALIDITY = 12,
GPGME_ATTR_LEVEL = 13,
GPGME_ATTR_TYPE = 14,
GPGME_ATTR_IS_SECRET = 15,
GPGME_ATTR_KEY_REVOKED = 16,
GPGME_ATTR_KEY_INVALID = 17,
GPGME_ATTR_UID_REVOKED = 18,
GPGME_ATTR_UID_INVALID = 19,
GPGME_ATTR_KEY_CAPS = 20,
GPGME_ATTR_CAN_ENCRYPT = 21,
GPGME_ATTR_CAN_SIGN = 22,
GPGME_ATTR_CAN_CERTIFY = 23,
GPGME_ATTR_KEY_EXPIRED = 24,
GPGME_ATTR_KEY_DISABLED = 25
}
GpgmeAttr;
typedef enum {
GPGME_VALIDITY_UNKNOWN = 0,
/* The available validities for a trust item or key. */
typedef enum
{
GPGME_VALIDITY_UNKNOWN = 0,
GPGME_VALIDITY_UNDEFINED = 1,
GPGME_VALIDITY_NEVER = 2,
GPGME_VALIDITY_MARGINAL = 3,
GPGME_VALIDITY_FULL = 4,
GPGME_VALIDITY_ULTIMATE = 5
} GpgmeValidity;
GPGME_VALIDITY_NEVER = 2,
GPGME_VALIDITY_MARGINAL = 3,
GPGME_VALIDITY_FULL = 4,
GPGME_VALIDITY_ULTIMATE = 5
}
GpgmeValidity;
/* The available protocols. */
typedef enum
{
GPGME_PROTOCOL_OpenPGP = 0, /* The default mode. */
GPGME_PROTOCOL_CMS = 1,
GPGME_PROTOCOL_AUTO = 2
}
GpgmeProtocol;
typedef enum {
GPGME_PROTOCOL_OpenPGP = 0, /* default */
GPGME_PROTOCOL_CMS = 1,
GPGME_PROTOCOL_AUTO = 2
} GpgmeProtocol;
/* Types for callback functions. */
typedef const char *(*GpgmePassphraseCb)(void*,
const char *desc, void **r_hd);
typedef void (*GpgmeProgressCb)(void *opaque,
const char *what,
int type, int current, int total );
/* Request a passphrase from the user. */
typedef const char *(*GpgmePassphraseCb) (void *hook, const char *desc,
void **r_hd);
/* Context management */
GpgmeError gpgme_new (GpgmeCtx *r_ctx);
void gpgme_release (GpgmeCtx c);
void gpgme_cancel (GpgmeCtx c);
GpgmeCtx gpgme_wait (GpgmeCtx c, int hang);
char *gpgme_get_notation (GpgmeCtx c);
GpgmeError gpgme_set_protocol (GpgmeCtx c, GpgmeProtocol prot);
void gpgme_set_armor (GpgmeCtx c, int yes);
int gpgme_get_armor (GpgmeCtx c);
void gpgme_set_textmode (GpgmeCtx c, int yes);
int gpgme_get_textmode (GpgmeCtx c);
void gpgme_set_keylist_mode ( GpgmeCtx c, int mode );
void gpgme_set_passphrase_cb (GpgmeCtx c,
GpgmePassphraseCb cb, void *cb_value);
void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *cb_value);
void gpgme_signers_clear (GpgmeCtx c);
GpgmeError gpgme_signers_add (GpgmeCtx c, const GpgmeKey key);
GpgmeKey gpgme_signers_enum (const GpgmeCtx c, int seq);
const char *gpgme_get_sig_status (GpgmeCtx c, int idx,
GpgmeSigStat *r_stat, time_t *r_created );
GpgmeError gpgme_get_sig_key (GpgmeCtx c, int idx, GpgmeKey *r_key);
char *gpgme_get_op_info (GpgmeCtx c, int reserved);
/* Inform the user about progress made. */
typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
int type, int current, int total);
/* Functions to handle recipients */
GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
void gpgme_recipients_release ( GpgmeRecipients rset);
GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset,
const char *name);
GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
const char *name,
GpgmeValidity val );
unsigned int gpgme_recipients_count ( const GpgmeRecipients rset );
GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,void **ctx);
const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,void **ctx);
GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,void **ctx);
/* Context management functions. */
/* Create a new context and return it in CTX. */
GpgmeError gpgme_new (GpgmeCtx *ctx);
/* Release the context CTX. */
void gpgme_release (GpgmeCtx ctx);
/* Retrieve more info about performed signature check. */
char *gpgme_get_notation (GpgmeCtx ctx);
/* Set the protocol to be used by CTX to PROTO. */
GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
/* If YES is non-zero, enable armor mode in CTX, disable it otherwise. */
void gpgme_set_armor (GpgmeCtx ctx, int yes);
/* Return non-zero if armor mode is set in CTX. */
int gpgme_get_armor (GpgmeCtx ctx);
/* If YES is non-zero, enable text mode in CTX, disable it otherwise. */
void gpgme_set_textmode (GpgmeCtx ctx, int yes);
/* Return non-zero if text mode is set in CTX. */
int gpgme_get_textmode (GpgmeCtx ctx);
/* Set keylist mode in CTX to MODE. */
void gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
/* Set the passphrase callback function in CTX to CB. HOOK_VALUE is
passed as first argument to the passphrase callback function. */
void gpgme_set_passphrase_cb (GpgmeCtx ctx,
GpgmePassphraseCb cb, void *hook_value);
/* Set the progress callback function in CTX to CB. HOOK_VALUE is
passed as first argument to the progress callback function. */
void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
/* Delete all signers from CTX. */
void gpgme_signers_clear (GpgmeCtx ctx);
/* Add KEY to list of signers in CTX. */
GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
/* Return the SEQth signer's key in CTX. */
GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
/* Retrieve the signature status of signature IDX in CTX after a
successful verify operation in R_STAT (if non-null). The creation
time stamp of the signature is returned in R_CREATED (if non-null).
The function returns a string containing the fingerprint. */
const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
GpgmeSigStat *r_stat, time_t *r_created);
/* Get the key used to create signature IDX in CTX and return it in
R_KEY. */
GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
/* Return a string with more info about the last crypto operating in CTX.
RESERVED should be zero. The user has to free the string. */
char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
/* Functions to handle data sources */
GpgmeError gpgme_data_new ( GpgmeData *r_dh );
GpgmeError gpgme_data_new_from_mem ( GpgmeData *r_dh,
const char *buffer, size_t size,
int copy );
GpgmeError gpgme_data_new_with_read_cb ( GpgmeData *r_dh,
int (*read_cb)(void*,char *,size_t,size_t*),
void *read_cb_value );
/* Run control. */
GpgmeError gpgme_data_new_from_file ( GpgmeData *r_dh,
const char *fname,
int copy );
/* Cancel a pending operation in CTX. */
void gpgme_cancel (GpgmeCtx ctx);
/* Process the pending operation and, if HANG is non-zero, wait for
the pending operation to finish. */
GpgmeCtx gpgme_wait (GpgmeCtx ctx, int hang);
/* Functions to handle recipients. */
/* Create a new recipients set and return it in R_RSET. */
GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
/* Release the recipients set RSET. */
void gpgme_recipients_release (GpgmeRecipients rset);
/* Add NAME to the recipients set RSET. */
GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
/* Add NAME with validity AL to the recipients set RSET. */
GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
const char *name,
GpgmeValidity val);
/* Return the number of recipients in RSET. */
unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
/* Create a new enumeration handle for the recipients set RSET and
return it in ITER. */
GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
void **iter);
/* Return the next recipient from the recipient set RSET in the
enumerator ITER. */
const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
void **iter);
/* Destroy the enumerator ITER for the recipient set RSET. */
GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
void **iter);
/* Functions to handle data objects. */
/* Create a new data buffer and return it in R_DH. */
GpgmeError gpgme_data_new (GpgmeData *r_dh);
/* Create a new data buffer filled with SIZE bytes starting from
BUFFER. If COPY is zero, copying is delayed until necessary, and
the data is taken from the original location when needed. */
GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
const char *buffer, size_t size,
int copy);
/* Create a new data buffer which retrieves the data from the callback
function READ_CB. */
GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
int (*read_cb) (void*,char *,size_t,size_t*),
void *read_cb_value);
/* Create a new data buffer filled with the content of file FNAME.
COPY must be non-zero (delayed reads are not supported yet). */
GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
const char *fname,
int copy);
/* Create a new data buffer filled with LENGTH bytes starting from
OFFSET within the file FNAME or stream FP (exactly one must be
non-zero). */
GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
const char *fname, FILE *fp,
off_t offset, size_t length);
void gpgme_data_release ( GpgmeData dh );
char * gpgme_data_release_and_get_mem ( GpgmeData dh, size_t *r_len );
GpgmeDataType gpgme_data_get_type ( GpgmeData dh );
GpgmeError gpgme_data_rewind ( GpgmeData dh );
GpgmeError gpgme_data_read ( GpgmeData dh,
char *buffer, size_t length, size_t *nread );
GpgmeError gpgme_data_write ( GpgmeData dh,
const char *buffer, size_t length );
/* Destroy the data buffer DH. */
void gpgme_data_release (GpgmeData dh);
/* Destroy the data buffer DH and return a pointer to its content.
The memory has be to released with free by the user. It's size is
returned in R_LEN. */
char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
/* Return the type of the data buffer DH. */
GpgmeDataType gpgme_data_get_type (GpgmeData dh);
/* Reset the read pointer in DH. */
GpgmeError gpgme_data_rewind (GpgmeData dh);
/* Read LENGTH bytes from the data object DH and store them in the
memory starting at BUFFER. The number of bytes actually read is
returned in NREAD. */
GpgmeError gpgme_data_read (GpgmeData dh, char *buffer,
size_t length, size_t *nread);
/* Write LENGTH bytes starting from BUFFER into the data object DH. */
GpgmeError gpgme_data_write (GpgmeData dh, const char *buffer, size_t length);
/* Key and trust functions */
/* Key and trust functions. */
/* Acquire a reference to KEY. */
void gpgme_key_ref (GpgmeKey key);
/* Release a reference to KEY. If this was the last one the key is
destroyed. */
void gpgme_key_unref (GpgmeKey key);
void gpgme_key_release ( GpgmeKey key );
char *gpgme_key_get_as_xml ( GpgmeKey key );
const char *gpgme_key_get_string_attr ( GpgmeKey key, GpgmeAttr what,
const void *reserved, int idx );
unsigned long gpgme_key_get_ulong_attr ( GpgmeKey key, GpgmeAttr what,
const void *reserved, int idx );
void gpgme_key_release (GpgmeKey key);
void gpgme_trust_item_release ( GpgmeTrustItem item );
const char *gpgme_trust_item_get_string_attr ( GpgmeTrustItem item,
GpgmeAttr what,
const void *reserved, int idx );
int gpgme_trust_item_get_int_attr ( GpgmeTrustItem item, GpgmeAttr what,
const void *reserved, int idx );
/* Get the data from key KEY in a XML string, which has to be released
with free by the user. */
char *gpgme_key_get_as_xml (GpgmeKey key);
/* Return the value of the attribute WHAT of KEY, which has to be
representable by a string. IDX specifies a running index if the
attribute appears more than once in the key. */
const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
const void *reserved, int idx);
/* Return the value of the attribute WHAT of KEY, which has to be
representable by an unsigned integer. IDX specifies a running
index if the attribute appears more than once in the key. */
unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
const void *reserved, int idx);
/* Release the trust item ITEM. */
void gpgme_trust_item_release (GpgmeTrustItem item);
/* Return the value of the attribute WHAT of ITEM, which has to be
representable by a string. IDX specifies a running index if the
attribute appears more than once in the key. */
const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
GpgmeAttr what,
const void *reserved, int idx);
/* Return the value of the attribute WHAT of KEY, which has to be
representable by an integer. IDX specifies a running index if the
attribute appears more than once in the key. */
int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
const void *reserved, int idx);
/* Crypto operation function. */
/* Encrypt plaintext PLAIN within CTX for the recipients RECP and
store the resulting ciphertext in CIPHER. */
GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
GpgmeRecipients recp,
GpgmeData plain, GpgmeData cipher);
GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
GpgmeRecipients recp,
GpgmeData plain, GpgmeData cipher);
/* Basic GnuPG functions */
GpgmeError gpgme_op_encrypt_start ( GpgmeCtx c,
GpgmeRecipients recp,
GpgmeData in, GpgmeData out );
GpgmeError gpgme_op_decrypt_start ( GpgmeCtx c,
GpgmeData ciph, GpgmeData plain );
GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx c,
GpgmeData ciph, GpgmeData plain);
GpgmeError gpgme_op_sign_start ( GpgmeCtx c,
GpgmeData in, GpgmeData out,
GpgmeSigMode mode );
GpgmeError gpgme_op_verify_start ( GpgmeCtx c,
GpgmeData sig, GpgmeData text );
GpgmeError gpgme_op_import_start ( GpgmeCtx c, GpgmeData keydata );
GpgmeError gpgme_op_export_start ( GpgmeCtx c, GpgmeRecipients recp,
GpgmeData keydata );
GpgmeError gpgme_op_genkey_start ( GpgmeCtx c, const char *parms,
GpgmeData pubkey, GpgmeData seckey );
GpgmeError gpgme_op_delete_start ( GpgmeCtx c, const GpgmeKey key,
int allow_secret );
/* Decrypt ciphertext CIPHER within CTX and store the resulting
plaintext in PLAIN. */
GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
GpgmeData cipher, GpgmeData plain);
GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
GpgmeData cipher, GpgmeData plain);
/* Decrypt ciphertext CIPHER and make a signature verification within
CTX and store the resulting plaintext in PLAIN. */
GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
GpgmeData cipher, GpgmeData plain);
GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
GpgmeData cipher, GpgmeData plain,
GpgmeSigStat *r_status);
/* Sign the plaintext PLAIN and store the signature in SIG. Only
detached signatures are supported for now. */
GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
GpgmeData plain, GpgmeData sig,
GpgmeSigMode mode);
GpgmeError gpgme_op_sign (GpgmeCtx ctx,
GpgmeData plain, GpgmeData sig,
GpgmeSigMode mode);
/* Verify within CTX that SIG is a valid signature for TEXT. */
GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
GpgmeData sig, GpgmeData text);
GpgmeError gpgme_op_verify (GpgmeCtx ctx,
GpgmeData sig, GpgmeData text,
GpgmeSigStat *r_status);
/* Import the key in KEYDATA into the keyring. */
GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
/* Export the keys listed in RECP into KEYDATA. */
GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
GpgmeData keydata);
GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
GpgmeData keydata);
/* Generate a new keypair and add it to the keyring. PUBKEY and
SECKEY should be null for now. PARMS specifies what keys should be
generated. */
GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
GpgmeData pubkey, GpgmeData seckey);
GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
GpgmeData pubkey, GpgmeData seckey);
/* Delete KEY from the keyring. If ALLOW_SECRET is non-zero, secret
keys are also deleted. */
GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
int allow_secret);
GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
int allow_secret);
/* Key management functions */
/* Start a keylist operation within CTX, searching for keys which
match PATTERN. If SECRET_ONLY is true, only secret keys are
returned. */
GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
const char *pattern, int secret_only);
/* Return the next key from the keylist in R_KEY. */
GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
/* Terminate a pending keylist operation within CTX. */
GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
/* Start a trustlist operation within CTX, searching for trust items
which match PATTERN. */
GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
const char *pattern, int max_level);
/* Return the next trust item from the trustlist in R_ITEM. */
GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
/* Terminate a pending trustlist operation within CTX. */
GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
/* Convenience functions for normal usage */
GpgmeError gpgme_op_encrypt ( GpgmeCtx c, GpgmeRecipients recp,
GpgmeData in, GpgmeData out );
GpgmeError gpgme_op_decrypt ( GpgmeCtx c,
GpgmeData in, GpgmeData out );
GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c,
GpgmeData in, GpgmeData out,
GpgmeSigStat *r_status);
GpgmeError gpgme_op_sign ( GpgmeCtx c, GpgmeData in, GpgmeData out,
GpgmeSigMode mode);
GpgmeError gpgme_op_verify ( GpgmeCtx c, GpgmeData sig, GpgmeData text,
GpgmeSigStat *r_status );
GpgmeError gpgme_op_import ( GpgmeCtx c, GpgmeData keydata );
GpgmeError gpgme_op_export ( GpgmeCtx c, GpgmeRecipients recp,
GpgmeData keydata );
GpgmeError gpgme_op_genkey ( GpgmeCtx c, const char *parms,
GpgmeData pubkey, GpgmeData seckey );
GpgmeError gpgme_op_delete ( GpgmeCtx c, const GpgmeKey key, int allow_secret);
/* Various functions. */
/* miscellaneous functions */
/* Check that the library fulfills the version requirement. */
const char *gpgme_check_version (const char *req_version);
/* Check that the backend engine is available. DEPRECATED. */
GpgmeError gpgme_check_engine (void);
/* Retrieve information about the backend engines. */
const char *gpgme_get_engine_info (void);
/* Return a string describing ERR. */
const char *gpgme_strerror (GpgmeError err);
/* Register an idle function. */
typedef void (*GpgmeIdleFunc)(void);
GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
/* Engine support functions. */
/* Verify that the engine implementing PROTO is installed and
available. */
GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
#ifdef __cplusplus
}
#endif