From 135185b7ef2225aa5e8c54a6cf1265d3e6cbbe48 Mon Sep 17 00:00:00 2001 From: Justus Winter Date: Tue, 2 Aug 2016 16:51:08 +0200 Subject: [PATCH] doc: Document the Assuan protocol. * doc/gpgme.texi: Document the Assuan protocol. GnuPG-bug-id: 2407 Signed-off-by: Justus Winter --- doc/gpgme.texi | 98 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/doc/gpgme.texi b/doc/gpgme.texi index a5ba9cc6..68f85ece 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -872,9 +872,12 @@ This specifies the OpenPGP protocol. @item GPGME_PROTOCOL_CMS This specifies the Cryptographic Message Syntax. -@item GPGME_PROTOCOL_ASSUAN +@item GPGME_PROTOCOL_GPGCONF Under development. Please ask on @email{gnupg-devel@@gnupg.org} for help. +@item GPGME_PROTOCOL_ASSUAN +This specifies the raw Assuan protocol. + @item GPGME_PROTOCOL_G13 Under development. Please ask on @email{gnupg-devel@@gnupg.org} for help. @@ -905,6 +908,7 @@ allocated string describing the protocol @var{protocol}, or * Engine Configuration:: Changing the engine configuration. * OpenPGP:: Support for the OpenPGP protocol. * Cryptographic Message Syntax:: Support for the CMS. +* Assuan:: Support for the raw Assuan protocol. @end menu @@ -1109,6 +1113,20 @@ GnuPG. The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}. +@node Assuan +@section Assuan +@cindex ASSUAN +@cindex protocol, ASSUAN +@cindex engine, ASSUAN + +Assuan is the RPC library used by the various @acronym{GnuPG} +components. The Assuan protocol allows one to talk to arbitrary +Assuan servers using @acronym{GPGME}. @xref{Using the Assuan +protocol}. + +The ASSUAN protocol is specified by @code{GPGME_PROTOCOL_ASSUAN}. + + @node Algorithms @chapter Algorithms @cindex algorithms @@ -5478,6 +5496,7 @@ Here are some support functions which are sometimes useful. @menu * Running other Programs:: Running other Programs +* Using the Assuan protocol:: Using the Assuan protocol @end menu @@ -5532,6 +5551,83 @@ This is the asynchronous variant of @code{gpgme_op_spawn}. @end deftypefun +@node Using the Assuan protocol +@subsection Using the Assuan protocol + +The Assuan protocol can be used to talk to arbitrary Assuan servers. +By default it is connected to the GnuPG agent, but it may be connected +to arbitrary servers by using @code{gpgme_ctx_set_engine_info}, +passing the location of the servers socket as @var{file_name} +argument, and an empty string as @var{home_dir} argument. + +The Assuan protocol functions use three kinds of callbacks to transfer +data: + +@deftp {Data type} {gpgme_error_t (*gpgme_assuan_data_cb_t) @ + (@w{void *@var{opaque}}, @w{const void *@var{data}}, @ + @w{size_t @var{datalen}})} + +This callback receives any data sent by the server. @var{opaque} is +the pointer passed to @code{gpgme_op_assuan_transact_start}, +@var{data} of length @var{datalen} refers to the data sent. +@end deftp + +@deftp {Data type} {gpgme_error_t (*gpgme_assuan_inquire_cb_t) @ + (@w{void *@var{opaque}}, @w{const char *@var{name}}, @ + @w{const char *@var{args}}, @w{gpgme_data_t *@var{r_data}})} + +This callback is used to provide additional data to the Assuan server. +@var{opaque} is the pointer passed to +@code{gpgme_op_assuan_transact_start}, @var{name} and @var{args} +specify what kind of data the server requested, and @var{r_data} is +used to return the actual data. + +Note: Returning data is currently not implemented in @acronym{GPGME}. +@end deftp + +@deftp {Data type} {gpgme_error_t (*gpgme_assuan_status_cb_t) @ + (@w{void *@var{opaque}}, @w{const char *@var{status}}, @ + @w{const char *@var{args}})} + +This callback receives any status lines sent by the server. +@var{opaque} is the pointer passed to +@code{gpgme_op_assuan_transact_start}, @var{status} and @var{args} +denote the status update sent. +@end deftp + +@deftypefun gpgme_error_t gpgme_op_assuan_transact_start @ + (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{command}}, @ + @w{gpgme_assuan_data_cb_t @var{data_cb}}, @ + @w{void * @var{data_cb_value}}, @ + @w{gpgme_assuan_inquire_cb_t @var{inquire_cb}}, @ + @w{void * @var{inquire_cb_value}}, @ + @w{gpgme_assuan_status_cb_t @var{status_cb}}, @ + @w{void * @var{status_cb_value}}) + +Send the Assuan @var{command} and return results via the callbacks. +Any callback may be @code{NULL}. The result of the operation may be +retrieved using @code{gpgme_wait_ext}. + +Asynchronous variant. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_assuan_transact_ext @ + (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{command}}, @ + @w{gpgme_assuan_data_cb_t @var{data_cb}}, @ + @w{void * @var{data_cb_value}}, @ + @w{gpgme_assuan_inquire_cb_t @var{inquire_cb}}, @ + @w{void * @var{inquire_cb_value}}, @ + @w{gpgme_assuan_status_cb_t @var{status_cb}}, @ + @w{void * @var{status_cb_value}}, @ + @w{gpgme_error_t *@var{op_err}}) + +Send the Assuan @var{command} and return results via the callbacks. +The result of the operation is returned in @var{op_err}. + +Synchronous variant. +@end deftypefun + + @node Run Control @section Run Control @cindex run control