doc/

2003-05-27  Marcus Brinkmann  <[email protected]>

	* gpgme.texi (Passphrase Callback): Document new prototype.

gpgme/
2003-05-26  Marcus Brinkmann  <[email protected]>

	* engine.h (EngineCommandHandler): Change last argument to int fd.
	* gpgme.h (gpgme_passphrase_cb_t): Rewritten to take parts of the
	description and fd.
	(gpgme_edit_cb_t): Change last argument to int fd.
	* ops.h (_gpgme_passphrase_command_handler_internal): New prototype.
	* passphrase.c: Include <assert.h>.
	(op_data_t): Rename userid_hint to uid_hint, remove last_pw_handle.
	(release_op_data): Check values before calling free.
	(_gpgme_passphrase_status_handler): Likewise.
	(_gpgme_passphrase_command_handler_internal): New function.
	(_gpgme_passphrase_command_handler): Rewritten.
	* edit.c (edit_status_handler): Pass -1 as fd argument.
	(command_handler): Update prototype.  New variable processed.  Use
	it to store return value of
	_gpgme_passphrase_command_handler_internal which is now used
	instead _gpgme_passphrase_command_handler.  Use it also to check
	if we should call the user's edit function.  Pass fd to user's
	edit function.
	* rungpg.c (struct gpg_object_s): Change type of cmd.cb_data to
	void *.
	(gpg_release): Check value before calling free.  Do not release
	cmd.cb_data.
	(command_cb): Function removed.
	(command_handler): New function.  Thus we don't use a data object
	for command handler stuff anymore, but handle it directly.  This
	allows proper error reporting (cancel of passphrase requests, for
	example).  Also all callbacks work via direct writes to the file
	descriptor (so that passphrases are not kept in insecure memory).
	(gpg_set_command_handler): Rewritten to use even more ugly hacks.
	(read_status): Check cmd.keyword before calling free.  Install
	command_handler as the I/O callback handler with GPG as private
	data.

tests/
2003-05-27  Marcus Brinkmann  <[email protected]>

	* (t-decrypt-verify.c, t-decrypt.c, t-edit.c, t-encrypt-sign.c,
	t-encrypt-sym.c, t-sign.c, t-signers.c): Include <unistd.h>.
	(passphrase_cb): Rewritten.
	* t-edit.c (edit_fnc): Rewritten.

2 files changed, 21 insertions, 10 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index a54d202d..bc4abc02 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2003-05-27  Marcus Brinkmann  <[email protected]>
+
+	* gpgme.texi (Passphrase Callback): Document new prototype.
+
 2003-05-18  Marcus Brinkmann  <[email protected]>
 
 	* gpgme.texi (Header): Remove Gpgme as namespace prefix.  Add
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 44edfa9a..ef4896cc 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -1684,21 +1684,28 @@ current mode otherwise.  Note that 0 is not a valid mode value.
 @cindex callback, passphrase
 @cindex passphrase callback
 
-@deftp {Data type} {gpgme_error_t (*gpgme_passphrase_cb_t)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd}, const char **@var{result})}
+@deftp {Data type} {gpgme_error_t (*gpgme_passphrase_cb_t)(void *@var{hook}, const char *@var{uid_hint}, const char *@var{passphrase_info}, @w{int @var{prev_was_bad}}, @w{int @var{fd}})}
 @tindex gpgme_passphrase_cb_t
 The @code{gpgme_passphrase_cb_t} type is the type of functions usable as
 passphrase callback function.
 
-The string @var{desc} contains a text usable to be displayed to the
-user of the application.  The function should return a passphrase for
-the context when invoked with @var{desc} not being @code{NULL} in
-*@var{result}.
+The argument @var{uid_hint} might contain a string that gives an
+indication for which user ID the passphrase is required.  If this is
+not available, or not applicable (in the case of symmetric encryption,
+for example), @var{uid_hint} will be @code{NULL}.
 
-The user may store information about the resources associated with the
-returned passphrase in @var{*r_hd}.  When the passphrase is no longer
-needed by @acronym{GPGME}, the passphrase callback function will be
-called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
-as at the first invocation.
+The argument @var{passphrase_info}, if not @code{NULL}, will give
+further information about the context in which the passphrase is
+required.  This information is engine and operation specific.
+
+If this is the repeated attempt to get the passphrase, because
+previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
+will be 0.
+
+The user must write the passphrase, followed by a newline character,
+to the file descriptor @var{fd}.  If the user does not return 0
+indicating success, the user must at least write a newline character
+before returning from the callback.
 
 If an error occurs, return the corresponding @code{gpgme_error_t} value.
 You can use @code{GPGME_Canceled} to abort the operation.  Otherwise,