doc/

2003-01-29  Marcus Brinkmann  <[email protected]>

	* gpgme.texi (I/O Callback Interface): Document new even
	GPGME_EVENT_START.
	(Waiting For Completion): Document new possible return values.
	(I/O Callback Interface): Document return type of GpgmeIOCb.

gpgme/
2003-01-29  Marcus Brinkmann  <[email protected]>

	* context.h (gpgme_context_s): Remove member ERROR.
	* types.h (GpgmeStatusHandler): Change return type to GpgmeError.
	(GpgmeCommandHandler): Change return type to GpgmeError and add
	new argument RESULT.
	* gpgme.h (GpgmeIOCb): Change return type to GpgmeError.
	(GpgmeEventIO): New event GPGME_EVENT_START.
	(GpgmeIdleFunc): Remove type.
	(gpgme_register_idle): Remove prototype.
	* data.c: Include <assert.h>.
	(_gpgme_data_inbound_handler): Change return type to GpgmeError.
	Return any error instead ignoring it, don't close file descriptor
	on error.
	(_gpgme_data_outbound_handler): Likewise.
	* decrypt.c: Do not include <stdio.h>, <string.h> and <assert.h>.
	(_gpgme_decrypt_status_handler): Change return type to GpgmeError.
	Return error instead setting ctx->error.  Return success at end of
	function.
	(gpgme_op_decrypt): Don't work around the old kludge anymore.
	* decrypt-verify.c (decrypt_verify_status_handler): Change return
	type to GpgmeError.  Return possible errors.
	* delete.c: Do not include <stdio.h>, <string.h>, <time.h> and
	<assert.h>.
	(delete_status_handler): Change return type to GpgmeError.  Return
	error instead setting ctx->error.  Return success at end of
	function.
	* edit.c: Do not include <stdio.h> and <string.h>.
	(_gpgme_edit_status_handler): Change type to GpgmeError,
	make static and rename to ...
	(edit_status_handler): ... this.  Return error directly.
	(command_handler): Change return type to GpgmeError, add result
	argument.  Return error directly.
	* encrypt.c (status_handler_finish): Remove function.
	(_gpgme_encrypt_status_handler): Change return type to GpgmeError.
	Return error directly.
	(_gpgme_encrypt_sym_status_handler): Likewise.
	* encrypt-sign.c (encrypt_sign_status_handler): Likewise.
	* engine-gpgsm.c (close_notify_handler): Do not signal done event
	anymore.
	(status_handler): Change return type to GpgmeError.  Diddle things
	around a bit to return errors directly.
	(start): Send start event.
	* export.c: Do not include <stdio.h>, <string.h> and <assert.h>.
	(export_status_handler): Change return type to GpgmeError.  Don't
	check ctx->error.
	* genkey.c: Do not include <stdio.h> and <assert.h>.
	(genkey_status_handler): Change return type to GpgmeError.  Don't
	check ctx->error.  Return errors directly.
	* gpgme.c (_gpgme_release_result): Do not initialize ctx->error.
	(_gpgme_op_event_cb): Function removed.
	(_gpgme_op_event_cb_user): Likewise.
	* import.c: Do not include <stdio.h>, <string.h> and <assert.h>.
	(import_status_handler): Change return type to GpgmeError.  Don't
	check ctx->error.
	* keylist.c (keylist_colon_handler, keylist_status_handler, finish_key):
	Change return type to GpgmeError, return error directly.
	* Makefile (libgpgme_la_SOURCES): Add wait-global.c,
	wait-private.c and wait-user.c
	* ops.h (test_and_allocate_result): Return error instead setting
	ctx->error.
	(_gpgme_data_inbound_handler, _gpgme_data_outbound_handler,
	_gpgme_verify_status_handler, _gpgme_decrypt_status_handler,
	_gpgme_sign_status_handler, _gpgme_encrypt_staus_handler,
	_gpgme_passphrase_status_handler, _gpgme_progress_status_handler):
	Change return type to GpgmeError.
	(_gpgme_passphease_command_handler): Change return type to
	GpgmeError and add new argument RESULT.
	* op-support.c: Use new callback functions, and change private
	data to ctx everywhere.
	* passphrase.c (_gpgme_passphrase_status_handler): Change return
	type to GpgmeError, return error directly.
	(_gpgme_passphrase_command_handler): Change return type to
	GpgmeError, add result argument.  Return results accordingly.
	* progress.c (_gpgme_progress_status_handler): Change return type
	to GpgmeError, return errors directly.
	* rungpg.c (status_handler): Change return type to GpgmeError.
	Return error directly.
	(close_notify_handler): Don't send done event.
	(colon_line_handler): Change return type to GpgmeError, return
	errors directly.
	* rungpg.c (start): Send start event.
	* sign.c (_gpgme_sign_status_handler): Change return type to
	GpgmeError, return errors directly.
	* trustlist.c (trustlist_status_handler): Change return type to
	GpgmeError.  Return 0.
	(trustlist_colon_handler): Change return type GpgmeError.  Return
	errors directly.
	* verify.c (add_notation): Change return type to GpgmeError,
	return errors directly.
	(_gpgme_verify_status_handler): Likewise.
	* wait.h (struct fd_table): Remove lock member.
	(struct wait_item_s): Moved here from wait.c.
	(struct tag): New structure.
	(_gpgme_wait_event_cb): Remove prototype.
	(_gpgme_wait_private_event_cb, _gpgme_wait_global_event_cb,
	_gpgme_wait_user_add_io_cb, _gpgme_wait_user_remove_io_cb,
	_gpgme_wait_user_event_io_cb): New prototypes.
	* wait.c: Don't include <stdio.h>.
	(ftd_global, ctx_done_list, ctx_done_list_size,
	ctx_done_list_length, ctx_done_list_lock, idle_function): Remove
	global variable.
	(gpgme_register_idle, do_select, _gpgme_wait_event_cb): Remove
	function.
	(gpgme_wait): Move to file wait-global.c.
	(_gpgme_add_io_cb): Take ctx as private argument, initialize ctx
	member in wait item and tag.
	(_gpgme_remove_io_cb): Take ctx from tag.  Don't use FDT lock.
	(_gpgme_wait_one, _gpgme_wait_on_condition): Move to
	wait-private.c.
	(gpgme_fd_table_init): Don't initialize FDT->lock.
	(gpgme_fd_table_deinit): Don't destroy FDT->lock.
	(_gpgme_fd_table_put): Make static and rename to ...
	(fd_table_put): ... this function.  Don't use FDT->lock.
	(struct wait_item_s): Move to wait.h.
	* wait-global.c: New file.
	* wait-private.c: New file.
	* wait-user.c: New file.

1 files changed, 22 insertions, 34 deletions

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index d3c02be8..6b822983 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -105,7 +105,7 @@ Preparation
 * Building the Source::           Compiler options to be used.
 * Using Automake::                Compiler options to be used the easy way.
 * Library Version Check::         Getting and verifying the library version.
-* Multi Threading::               How GPGME can be used in an MT environment.
+* Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
 
 Protocols and Engines
 
@@ -191,7 +191,6 @@ Run Control
 
 * Waiting For Completion::        Waiting until an operation is completed.
 * Cancelling an Operation::       Interrupting a running operation.
-* Hooking Up Into Idle Time::     Doing something when nothing has to be done.
 * Using External Event Loops::    Advanced control over what happens when.
 
 Using External Event Loops
@@ -228,7 +227,7 @@ OpenPGP and the Cryptographic Message Syntax (CMS).
 @node Getting Started
 @section Getting Started
 
-This library documents the @acronym{GPGME} library programming
+This manual documents the @acronym{GPGME} library programming
 interface.  All functions and data types provided by the library are
 explained.
 
@@ -315,7 +314,7 @@ of the library are verified.
 * Building the Source::           Compiler options to be used.
 * Using Automake::                Compiler options to be used the easy way.
 * Library Version Check::         Getting and verifying the library version.
-* Multi Threading::               How GPGME can be used in an MT environment.
+* Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
 @end menu
 
 
@@ -541,12 +540,13 @@ initialize_gpgme (void)
 Any @code{GpgmeData}, @code{GpgmeCtx} and @code{GpgmeRecipients}
 object must only be accessed by one thread at a time.  If multiple
 threads want to deal with the same object, the caller has to make sure
-that operations on this object are fully synchronized.
+that operations on that object are fully synchronized.
 
 @item
 Only one thread at any time is allowed to call @code{gpgme_wait}.  If
 multiple threads call this function, the caller must make sure that
-all invocations are fully synchronized.
+all invocations are fully synchronized.  It is safe to start
+asynchronous operations while a thread is running in gpgme_wait.
 @end itemize
 
 
@@ -3012,7 +3012,6 @@ time.
 @menu
 * Waiting For Completion::        Waiting until an operation is completed.
 * Cancelling an Operation::       Interrupting a running operation.
-* Hooking Up Into Idle Time::     Doing something when nothing has to be done.
 * Using External Event Loops::    Advanced control over what happens when.
 @end menu
 
@@ -3050,10 +3049,14 @@ and trust item list operations, do not affect @code{gpgme_wait}.
 In a multi-threaded environment, only one thread should ever call
 @code{gpgme_wait} at any time, irregardless if @var{ctx} is specified
 or not.  This means that all calls to this function should be fully
-synchronized by locking primitives.
+synchronized by locking primitives.  It is safe to start asynchronous
+operations while a thread is running in @code{gpgme_wait}.
 
 The function returns the @var{ctx} of the context which has finished
-the operation.
+the operation.  If @var{hang} is false, and the timeout expires,
+@code{NULL} is returned and @code{*status} will be set to 0.  If an
+error occurs, @code{NULL} is returned and the error is returned in
+@code{*status}.
 @end deftypefun
 
 
@@ -3073,30 +3076,6 @@ callback.
 @end deftypefun
 
 
-@node Hooking Up Into Idle Time
-@subsection Hooking Up Into Idle Time
-@cindex idle time
-@cindex idle function
-
-@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
-
-@deftypefun GpgmeIdleFunc gpgme_register_idle (@w{GpgmeIdleFunc @var{idle}})
-The function @code{gpgme_register_idle} can be used to register
-@var{idle} as the idle function.
-
-@var{idle} will be called whenever @acronym{GPGME} thinks that it is
-idle and time can better be spent elsewhere.  Setting @var{idle} to
-@code{NULL} disables use of the idle function (this is the default).
-
-The function returns the old idle function, or @code{NULL} if none was
-registered yet.
-@end deftypefun
-
-
 @node Using External Event Loops
 @subsection Using External Event Loops
 @cindex event loop, external
@@ -3139,7 +3118,7 @@ programs.
 @node I/O Callback Interface
 @subsubsection I/O Callback Interface
 
-@deftp {Data type} {void (*GpgmeIOCb) (@w{void *@var{data}}, @w{int @var{fd}})}
+@deftp {Data type} {GpgmeError (*GpgmeIOCb) (@w{void *@var{data}}, @w{int @var{fd}})}
 @tindex GpgmeIOCb
 The @code{GpgmeIOCb} type is the type of functions which
 @acronym{GPGME} wants to register as I/O callback handlers using the
@@ -3149,6 +3128,9 @@ The @code{GpgmeIOCb} type is the type of functions which
 callback handler is registered, and should be passed through to the
 handler when it is invoked by the user because it noticed activity on
 the file descriptor @var{fd}.
+
+The callback handler always returns @code{0}, but you should consider
+the return value to be reserved for later use.
 @end deftp
 
 @deftp {Data type} {GpgmeError (*GpgmeRegisterIOCb) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{GpgmeIOCb @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
@@ -3198,6 +3180,12 @@ reported to the user by @acronym{GPGME} as a consequence of an I/O
 operation.  The following events are defined:
 
 @table @code
+@item GPGME_EVENT_START
+The operation is fully initialized now, and you can start to run the
+registered I/O callback handlers now.  Note that registered I/O
+callback handlers must not be run before this event is signalled.
+@var{type_data} is @code{NULL} and reserved for later use.
+
 @item GPGME_EVENT_DONE
 The operation is finished, the last I/O callback for this operation
 was removed.  The accompanying @var{type_data} points to a