diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gpgme.texi | 88 |
2 files changed, 91 insertions, 2 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index b4217dcb..d53f017b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2005-01-12 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Engine Configuration): New section. + (Crypto Engine): New subsection. + 2004-12-07 Marcus Brinkmann <[email protected]> * lesser.texi (Library Copying): Change from @appendixsec to diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 957df64f..f68b41be 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -125,6 +125,7 @@ Protocols and Engines * 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 @@ Contexts 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 @@ allocated string describing the protocol @var{protocol}, or @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 @@ This is a string holding the file name of the executable of the crypto engine. Currently, it is never @code{NULL}, but using @code{NULL} is reserved for future use, so always check before you use it. +@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 @@ reserved for future use, so always check before you use it. @end table @end deftp -@deftypefun gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *info) +@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 @@ if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE) @end example +@node Engine Configuration +@section Engine Configuration +@cindex engine, configuration of +@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. + +@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 +@var{proto}. + +@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 +@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. +@end deftypefun + +The functions @code{gpgme_ctx_get_engine_info} and +@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 @@ The function @code{gpgme_release} destroys the context with the handle @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 @@ The function @code{gpgme_get_protocol} retrieves the protocol currently use with the context @var{ctx}. @end deftypefun + +@node Crypto Engine +@subsection Crypto Engine +@cindex context, configuring engine +@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. +@xref{Engine Information}. The default can also be changed globally. +@xref{Engine Configuration}. + +@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 +@var{ctx}. + +The result is valid until the next invocation of +@code{gpgme_ctx_set_engine_info} for this particular context. + +This function can not fail. +@end deftypefun + +@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 +@var{proto} for the context @var{ctx}. + +@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 +@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. +@end deftypefun + + @c FIXME: Unfortunately, using @acronym here breaks texi2dvi. @node ASCII Armor @subsection @acronym{ASCII} Armor |