[svn] gpgme - r1217 - trunk/doc

[svn author marcus]

Author: marcus
Date: 2007-06-05 16:47:18 +0200 (Tue, 05 Jun 2007)
New Revision: 1217

Modified:
   trunk/doc/ChangeLog
   trunk/doc/gpgme.texi
Log:
2007-06-05  Marcus Brinkmann  <marcus at g10code.de>

        * gpgme.texi (Advanced Key Editing): New section.



Modified: trunk/doc/ChangeLog
===================================================================
--- trunk/doc/ChangeLog	2007-05-18 22:30:42 UTC (rev 1216)
+++ trunk/doc/ChangeLog	2007-06-05 14:47:18 UTC (rev 1217)
@@ -1,3 +1,7 @@
+2007-06-05  Marcus Brinkmann  <marcus at g10code.de>
+
+	* gpgme.texi (Advanced Key Editing): New section.
+
 2007-05-18  Marcus Brinkmann  <marcus at g10code.de>
 
 	* gpgme.texi (Error Strings): Fix documentation of

Modified: trunk/doc/gpgme.texi
===================================================================
--- trunk/doc/gpgme.texi	2007-05-18 22:30:42 UTC (rev 1216)
+++ trunk/doc/gpgme.texi	2007-06-05 14:47:18 UTC (rev 1217)
@@ -1,4 +1,4 @@
-\input texinfo                  @c -*- Texinfo -*-
+()\input texinfo                  @c -*- Texinfo -*-
 @setfilename gpgme.info
 @settitle The `GnuPG Made Easy' Reference Manual
 
@@ -190,6 +190,7 @@
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Advanced Key Editing::          Advanced key edit operation.
 
 Trust Item Management
 
@@ -2617,6 +2618,7 @@
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Advanced Key Editing::          Advanced key edit operation.
 @end menu
 
 
@@ -3492,6 +3494,68 @@
 @end deftypefun
 
 
+ at node Advanced Key Editing
+ at subsection Advanced Key Editing
+ at cindex key, edit
+
+ at deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})}
+ at tindex gpgme_edit_cb_t
+The @code{gpgme_edit_cb_t} type is the type of functions which
+ at acronym{GPGME} calls if it a key edit operation is on-going.  The
+status code @var{status} and the argument line @var{args} are passed
+through by @acronym{GPGME} from the crypto engine.  The file
+descriptor @var{fd} is -1 for normal status messages.  If @var{status}
+indicates a command rather than a status message, the response to the
+command should be written to @var{fd}.  The @var{handle} is provided
+by the user at start of operation.
+
+The function should return @code{GPG_ERR_NO_ERROR} or an error value.
+ at end deftp
+
+ at deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_edit} processes the key @var{KEY}
+interactively, using the edit callback function @var{FNC} with the
+handle @var{HANDLE}.  The callback is invoked for every status and
+command request from the crypto engine.  The output of the crypto
+engine is written to the data object @var{out}.
+
+Note that the protocol between the callback function and the crypto
+engine is specific to the crypto engine and no further support in
+implementing this protocol correctly is provided by @acronym{GPGME}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
+ at var{ctx} or @var{key} is not a valid pointer, and any error returned
+by the crypto engine or the edit callback handler.
+ at end deftypefun
+
+ at deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_edit_start} initiates a
+ at code{gpgme_op_edit} operation.  It can be completed by calling
+ at code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+ at var{ctx} or @var{key} is not a valid pointer.
+ at end deftypefun
+
+
+ at deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_card_edit} is analogous to
+ at code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
+ at end deftypefun
+
+ at deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_card_edit_start} initiates a
+ at code{gpgme_op_card_edit} operation.  It can be completed by calling
+ at code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+ at var{ctx} or @var{key} is not a valid pointer.
+ at end deftypefun
+
+
 @node Trust Item Management
 @section Trust Item Management
 @cindex trust item