gpgme/doc (ChangeLog gpgme.texi)
cvs user marcus
cvs at cvs.gnupg.org
Wed Jan 12 12:06:07 CET 2005
Date: Wednesday, January 12, 2005 @ 12:13:17
Author: marcus
Path: /cvs/gpgme/gpgme/doc
Modified: ChangeLog gpgme.texi
2005-01-12 Marcus Brinkmann <marcus at g10code.de>
* gpgme.texi (Engine Configuration): New section.
(Crypto Engine): New subsection.
------------+
ChangeLog | 5 +++
gpgme.texi | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
2 files changed, 91 insertions(+), 2 deletions(-)
Index: gpgme/doc/ChangeLog
diff -u gpgme/doc/ChangeLog:1.134 gpgme/doc/ChangeLog:1.135
--- gpgme/doc/ChangeLog:1.134 Tue Dec 7 22:21:41 2004
+++ gpgme/doc/ChangeLog Wed Jan 12 12:13:17 2005
@@ -1,3 +1,8 @@
+2005-01-12 Marcus Brinkmann <marcus at g10code.de>
+
+ * gpgme.texi (Engine Configuration): New section.
+ (Crypto Engine): New subsection.
+
2004-12-07 Marcus Brinkmann <marcus at g10code.de>
* lesser.texi (Library Copying): Change from @appendixsec to
Index: gpgme/doc/gpgme.texi
diff -u gpgme/doc/gpgme.texi:1.136 gpgme/doc/gpgme.texi:1.137
--- gpgme/doc/gpgme.texi:1.136 Tue Dec 7 22:21:41 2004
+++ gpgme/doc/gpgme.texi Wed Jan 12 12:13:17 2005
@@ -125,6 +125,7 @@
* Engine Version Check:: Verifying the engine version.
* Engine Information:: Obtaining more information about the engines.
+* Engine Configuration:: Changing the engine configuration.
* OpenPGP:: Support for the OpenPGP protocol.
* Cryptographic Message Syntax:: Support for the CMS.
@@ -165,6 +166,7 @@
Context Attributes
* Protocol Selection:: Selecting the protocol used by a context.
+* Crypto Engine:: Configuring the crypto engine.
* ASCII Armor:: Requesting @acronym{ASCII} armored output.
* Text Mode:: Choosing canonical text mode.
* Included Certificates:: Including a number of certificates.
@@ -745,6 +747,7 @@
@menu
* Engine Version Check:: Verifying the engine version.
* Engine Information:: Obtaining more information about the engines.
+* Engine Configuration:: Changing the engine configuration.
* OpenPGP:: Support for the OpenPGP protocol.
* Cryptographic Message Syntax:: Support for the CMS.
@end menu
@@ -789,6 +792,11 @@
engine. Currently, it is never @code{NULL}, but using @code{NULL} is
reserved for future use, so always check before you use it.
+ at item const char *home_dir
+This is a string holding the directory name of the crypto engine's
+configuration directory. If it is @code{NULL}, then the default
+directory is used.
+
@item const char *version
This is a string containing the version number of the crypto engine.
It might be @code{NULL} if the version number can not be determined,
@@ -803,10 +811,10 @@
@end table
@end deftp
- at deftypefun gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *info)
+ at deftypefun gpgme_error_t gpgme_get_engine_info (@w{gpgme_engine_info_t *@var{info}})
The function @code{gpgme_get_engine_info} returns a linked list of
engine info structures in @var{info}. Each info structure describes
-one configured backend.
+the defaults of one configured backend.
The memory for the info structures is allocated the first time this
function is invoked, and must not be freed by the caller.
@@ -850,6 +858,37 @@
@end example
+ at node Engine Configuration
+ at section Engine Configuration
+ at cindex engine, configuration of
+ at cindex configuration of crypto backend
+
+You can change the configuration of a backend engine, and thus change
+the executable program and configuration directory to be used. You
+can make these changes the default or set them for some contexts
+individually.
+
+ at deftypefun gpgme_error_t gpgme_set_engine_info (@w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
+The function @code{gpgme_set_engine_info} changes the default
+configuration of the crypto engine implementing the protocol
+ at var{proto}.
+
+ at var{file_name} is the file name of the executable program
+implementing this protocol, and @var{home_dir} is the directory name
+of the configuration directory for this crypto engine. If
+ at var{home_dir} is @code{NULL}, the engine's default will be used.
+
+The new defaults are not applied to already created GPGME contexts.
+
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, or an eror code on failure.
+ at end deftypefun
+
+The functions @code{gpgme_ctx_get_engine_info} and
+ at code{gpgme_ctx_set_engine_info} can be used to change the engine
+configuration per context. @xref{Crypto Engine}.
+
+
@node OpenPGP
@section OpenPGP
@cindex OpenPGP
@@ -1847,6 +1886,7 @@
@menu
* Protocol Selection:: Selecting the protocol used by a context.
+* Crypto Engine:: Configuring the crypto engine.
* ASCII Armor:: Requesting @acronym{ASCII} armored output.
* Text Mode:: Choosing canonical text mode.
* Included Certificates:: Including a number of certificates.
@@ -1882,6 +1922,50 @@
use with the context @var{ctx}.
@end deftypefun
+
+ at node Crypto Engine
+ at subsection Crypto Engine
+ at cindex context, configuring engine
+ at cindex engine, configuration per context
+
+The following functions can be used to set and retrieve the
+configuration of the crypto engines of a specific context. The
+default can also be retrieved without any particular context.
+ at xref{Engine Information}. The default can also be changed globally.
+ at xref{Engine Configuration}.
+
+ at deftypefun gpgme_engine_info_t gpgme_ctx_get_engine_info (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_ctx_get_engine_info} returns a linked list of
+engine info structures. Each info structure describes the
+configuration of one configured backend, as used by the context
+ at var{ctx}.
+
+The result is valid until the next invocation of
+ at code{gpgme_ctx_set_engine_info} for this particular context.
+
+This function can not fail.
+ at end deftypefun
+
+ at deftypefun gpgme_error_t gpgme_ctx_set_engine_info (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
+The function @code{gpgme_ctx_set_engine_info} changes the
+configuration of the crypto engine implementing the protocol
+ at var{proto} for the context @var{ctx}.
+
+ at var{file_name} is the file name of the executable program
+implementing this protocol, and @var{home_dir} is the directory name
+of the configuration directory for this crypto engine. If
+ at var{home_dir} is @code{NULL}, the engine's default will be used.
+
+Currently this function must be used before starting the first crypto
+operation. It is unspecified if and when the changes will take effect
+if the function is called after starting the first operation on the
+context @var{ctx}.
+
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, or an eror code on failure.
+ at end deftypefun
+
+
@c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
@node ASCII Armor
@subsection @acronym{ASCII} Armor
More information about the Gnupg-commits
mailing list