doc/

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

	* gpgme.texi (Exporting Keys): Change and document prototypes.
	Add new gpgme_op_export_ext and gpgme_op_export_ext_start
	variants.
	(Selecting Recipients): Section removed.
	(Encrypting a Plaintext): Change prototypes and document the
	changes.

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

	* gpgme.h (gpgme_op_export_start): Change second arg to const char *.
	(gpgme_op_export): Likewise.
	(gpgme_op_export_ext_start): New prototype.
	(gpgme_op_export_ext): Likewise.
	* engine.h: Likewise for _gpgme_engine_op_export and
	_gpgme_engine_op_export_ext.
	* engine-backend.h (struct engine_ops): Change second argument of
	prototype of export to const char *, and add reserverd int as
	third argument.  Add prototype for export_ext.
	* engine.c (_gpgme_engine_op_export_ext): New function.
	(_gpgme_engine_op_export): Change second argument of prototype of
	export to const char *, and add reserverd int as third argument.
	* rungpg.c (gpg_export): Change second argument of prototype of
	export to const char *, and add reserverd int as third argument.
	(gpg_export_ext): New function.
	(gpg_keylist_ext): Break loop at error.
	(_gpgme_engine_ops_gpg): Add gpg_export_ext.
	* engine-gpgsm.c (gpgsm_export): Change second argument of
	prototype of export to const char *, and add reserverd int as
	third argument.
	(gpgsm_export_ext): New function.
	(_gpgme_engine_ops_gpgsm): Add gpgsm_export_ext.
	* export.c (export_start): Change second argument of prototype of
	export to const char *, and add reserverd int as third argument.
	(gpgme_op_export_start): Likewise.
	(export_ext_start): New function.
	(gpgme_op_export_ext_start): Likewise.
	(gpgme_op_export_ext): Likewise.

	* gpgme.h (gpgme_keylist_mode_t): New type for anonymous enum.
	(gpgme_sigsum_t): New type for anonymous enum.

	* encrypt-sign.c (encrypt_sign_start): Check for errors earlier,
	and return an error if RECP is not set.

	* Makefile.am (libgpgme_la_SOURCES): Remove user-id.c.
	* user-id.c: Remove file.
	* ops.h: Remove prototype for _gpgme_user_ids_all_valid.
	* gpgme.h (gpgme_encrypt_flags_t): New type.
	(gpgme_op_encrypt_start): Change second parameter to type
	gpgme_key_t[], and add third parameter.
	(gpgme_op_encrypt): Likewise.
	(gpgme_op_encrypt_sign_start): Likewise.
	(gpgme_op_encrypt_sign): Likewise.
	* encrypt.c (encrypt_start): Likewise.
	(gpgme_op_encrypt_start): Likewise.
	(gpgme_op_encrypt): Likewise.  Pass flags to engine.
	* encrypt-sign.c (encrypt_sign_start): Likewise.
	(gpgme_op_encrypt_sign_start): Likewise.
	(gpgme_op_encrypt_sign): Likewise.
	* engine-backend.h (struct engine_ops): Likewise for prototypes of
	encrypt and encrypt_sign.
	* engine.h: Likewise for prototypes of _gpgme_engine_op_encrypt
	and _gpgme_engine_op_encrypt_sign.
	* engine.c (_gpgme_engine_op_encrypt): Likewise.
	(_gpgme_engine_op_encrypt_sign): Likewise.
	* rungpg.c (gpg_encrypt): Likewise.
	(gpg_encrypt_sign): Likewise.
	* rungpg.c (gpg_encrypt): Check flags for always trust option.
	* engine-gpgsm.c (gpgsm_encrypt): Likewise.
	(set_recipients): Rewritten to use keys instead user IDs.
	* rungpg.c (append_args_from_recipients): Rewritten to use keys
	instead user IDs.
	* encrypt.c (_gpgme_encrypt_status_handler): Change errors
	returned to GPGME_Invalid_Key and GPGME_General_Error.

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

	* gpg/t-encrypt-sym.c (main): Adapt to new syntax.
	* gpg/t-encrypt.c (main): Likewise.
	* gpg/t-eventloop.c (main): Likewise.
	* gpg/t-encrypt-sign.c (main): Likewise.
	* gpgsm/t-export.c (main): Likewise.
	* gpgsm/t-encrypt.c (main): Likewise.

2 files changed, 95 insertions, 91 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index a3981108..0eee29d3 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,12 @@
+2003-05-29  Marcus Brinkmann  <[email protected]>
+
+	* gpgme.texi (Exporting Keys): Change and document prototypes.
+	Add new gpgme_op_export_ext and gpgme_op_export_ext_start
+	variants.
+	(Selecting Recipients): Section removed.
+	(Encrypting a Plaintext): Change prototypes and document the
+	changes.
+
 2003-05-28  Marcus Brinkmann  <[email protected]>
 
 	* gpgme.texi (Exporting Keys): Change argument type from
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 2513f361..c388d365 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -189,7 +189,6 @@ Sign
 
 Encrypt
 
-* Selecting Recipients::          How to choose the recipients.
 * Encrypting a Plaintext::        How to encrypt a plaintext.
 
 Run Control
@@ -1630,7 +1629,7 @@ certificates to include into an S/MIME signed message.
 @cindex key listing mode
 @cindex key listing, mode of
 
-@deftypefun void gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{mode}})
+@deftypefun void gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
 The function @code{gpgme_set_keylist_mode} changes the default
 behaviour of the key listing functions.  The value in @var{mode} is a
 bitwise-or combination of one or multiple of the following bit values:
@@ -1668,7 +1667,7 @@ pointer or @var{mode} is not a valid mode.
 @end deftypefun
 
 
-@deftypefun int gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
+@deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_get_keylist_mode} returns the current key
 listing mode of the context @var{ctx}.  This value can then be
 modified and used in a subsequent @code{gpgme_set_keylist_mode}
@@ -2649,28 +2648,61 @@ operation is started on the context.
 @cindex key, export
 @cindex key ring, export from
 
-@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_user_id_t @var{uids}}, @w{gpgme_data_t @var{keydata}})
-The function @code{gpgme_op_export} extracts the public keys of the
-user IDs in @var{uids} and returns them in the data buffer
-@var{keydata}.  The type of the public keys returned is determined by
-the @acronym{ASCII} armor attribute set for the context @var{ctx}.
+@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export} extracts public keys and returns
+them in the data buffer @var{keydata}.  The output format of the key
+data returned is determined by the @acronym{ASCII} armor attribute set
+for the context @var{ctx}.
+
+If @var{pattern} is @code{NULL}, all available keys are returned.
+Otherwise, @var{pattern} contains an engine specific expression that
+is used to limit the list to all keys matching the pattern.
+
+@var{reserved} is reserved for future use and must be @code{0}.
 
 The function returns @code{GPGME_No_Error} if the operation completed
-successfully, @code{GPGME_Invalid_Value} if @var{uids} is
-@code{NULL} or @var{keydata} is not a valid empty data buffer, and
-passes through any errors that are reported by the crypto engine
-support routines.
+successfully, @code{GPGME_Invalid_Value} if @var{keydata} is not a
+valid empty data buffer, and passes through any errors that are
+reported by the crypto engine support routines.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_user_id_t @var{uids}}, @w{gpgme_data_t @var{keydata}})
+@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export_start} initiates a
 @code{gpgme_op_export} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
 The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, and @code{GPGME_Invalid_Value} if
-@var{uids} is @code{NULL} or @var{keydata} is not a valid empty
-data buffer.
+started successfully, and @code{GPGME_Invalid_Value} if @var{keydata}
+is not a valid empty data buffer.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export} extracts public keys and returns
+them in the data buffer @var{keydata}.  The output format of the key
+data returned is determined by the @acronym{ASCII} armor attribute set
+for the context @var{ctx}.
+
+If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
+are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
+array of strings that are used to limit the list to all keys matching
+at least one of the patterns verbatim.
+
+@var{reserved} is reserved for future use and must be @code{0}.
+
+The function returns @code{GPGME_No_Error} if the operation completed
+successfully, @code{GPGME_Invalid_Value} if @var{keydata} is not a
+valid empty data buffer, and passes through any errors that are
+reported by the crypto engine support routines.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export_ext_start} initiates a
+@code{gpgme_op_export_ext} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, and @code{GPGME_Invalid_Value} if @var{keydata}
+is not a valid empty data buffer.
 @end deftypefun
 
 
@@ -3178,7 +3210,7 @@ following members:
 This is a pointer to the next new signature structure in the linked
 list, or @code{NULL} if this is the last element.
 
-@item unsigned int summary;
+@item gpgme_sigsum_t summary;
 This is a bit vector giving a summary of the signature status.  It
 provides an easy interface to a defined semantic of the signature
 status.  Checking just one bit is sufficient to see whether a
@@ -3746,79 +3778,41 @@ time.  The list of recipients is created independently of any context,
 and then passed to the encryption operation.
 
 @menu
-* Selecting Recipients::          How to choose the recipients.
 * Encrypting a Plaintext::        How to encrypt a plaintext.
 @end menu
 
 
-@node Selecting Recipients
-@subsubsection Selecting Recipients
-@cindex encryption, selecting recipients
-@cindex recipients
-
-@deftypefun gpgme_error_t gpgme_user_ids_append (@w{gpgme_user_id_t *@var{rset_p}}, @w{const char *@var{name}})
-The function @code{gpgme_user_ids_append} creates a new
-@code{gpgme_user_id_t} object, initializes its @code{uid} member with
-a copy of the string pointed to by @var{name}, initializes its
-@code{name}, @code{email}, @code{comment} members to the empty string,
-its @code{validity} member to @code{GPGME_VALIDITY_UNKNOWN} and leaves
-all other fields to 0.
-
-It then appends the user ID at the end of the linked list of user IDs
-that starts at *@var{rset_p}, or it returns it in *@var{rset_p} if
-that is @code{NULL}.  You can then update for example the validity
-information in the user ID directly.
-
-We recommend that you keep a pointer to the last element in your
-linked list.  This is faster and allows you to easily update the
-fields of the last user ID.  Here is an example how to create a linked
-list of user IDs in @var{rset} with full validity from a
-@code{NULL}-terminated array of names:
-
-@example
-  const char *names[] = @{ "Alpha", "Bob", NULL @};
-  gpgme_error_t err;
-  gpgme_user_id_t rset = NULL;
-  gpgme_user_id_t *rset_lastp = &rset;
-
-  do
-    @{
-      err = gpgme_user_ids_append (rset_lastp, *(names++));
-      if (!err)
-        @{
-          (*rset_lastp)->validity = GPGME_VALIDITY_FULL;
-          rset_lastp = &(*rset_lastp)->next;
-        @}
-    @}
-  while (!err && *names);
-@end example
-
-The function returns @code{GPGME_No_Error} if the recipient set could
-be created successfully, and @code{GPGME_Out_Of_Core} if not enough
-memory was available.
-@end deftypefun
-
-@deftypefun void gpgme_user_ids_release (@w{gpgme_user_id_t @var{uids}})
-The function @code{gpgme_user_ids_release} destroys the linked list of
-user IDs @var{uids} and releases all associated resources allocated by
-@acronym{GPGME}..
-@end deftypefun
-
-
 @node Encrypting a Plaintext
 @subsubsection Encrypting a Plaintext
 
-@deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_user_id_t @var{rset}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
+@deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
 The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
-object @var{plain} for the recipients @var{rset} and stores the
+object @var{plain} for the recipients @var{recp} and stores the
 ciphertext in the data object @var{cipher}.  The type of the
 ciphertext created is determined by the @acronym{ASCII} armor and text
 mode attributes set for the context @var{ctx}.
 
-If @code{GPGME_Invalid_UserID} is returned, some recipients in
-@var{rset} are invalid, but not all.  In this case the plaintext is
-encrypted for all valid recipients and returned in @var{cipher}.  More
-information about the invalid recipients is available with
+@var{key} must be a @code{NULL}-terminated array of keys.  The user
+must keep references for all keys during the whole duration of the
+call (but see @code{gpgme_op_encrypt_start} for the requirements with
+the asynchronous variant).
+
+The value in @var{flags} is a bitwise-or combination of one or
+multiple of the following bit values:
+
+@table @code
+@item GPGME_ENCRYPT_ALWAYS_TRUST
+The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
+recipients in @var{recp} should be trusted, even if the keys do not
+have a high enough validity in the keyring.  This flag should be used
+with care; in general it is not a good idea to use any untrusted keys.
+@end table
+
+If @code{GPGME_Invalid_Key} is returned, some recipients in @var{recp}
+are invalid, but not all.  In this case the plaintext might be
+encrypted for all valid recipients and returned in @var{cipher} (if
+this happens depends on the crypto engine).  More information about
+the invalid recipients is available with
 @code{gpgme_op_encrypt_result}.
 
 If @var{recp} is @code{NULL}, symmetric rather than public key
@@ -3830,19 +3824,22 @@ crypto backend.
 
 The function returns @code{GPGME_No_Error} if the ciphertext could be
 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
-@code{GPGME_No_UserID} if @var{rset} does not contain any valid
-recipients, @code{GPGME_Invalid_UserID} if @var{rset} contains some
-invalid recipients, @code{GPGME_Bad_Passphrase} if the passphrase for
-the secret key could not be retrieved, and passes through any errors
-that are reported by the crypto engine support routines.
+@var{recp}, @var{plain} or @var{cipher} is not a valid pointer,
+@code{GPGME_Invalid_Key} if @var{recp} contains some invalid
+recipients, @code{GPGME_Bad_Passphrase} if the passphrase for the
+secret key could not be retrieved, and passes through any errors that
+are reported by the crypto engine support routines.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_encrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_user_id_t @var{rset}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
+@deftypefun gpgme_error_t gpgme_op_encrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
 The function @code{gpgme_op_encrypt_start} initiates a
 @code{gpgme_op_encrypt} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
+References to the keys only need to be held for the duration of this
+call.  The user can release its references to the keys after this
+function returns, even if the operation is not yet finished.
+
 The function returns @code{GPGME_No_Error} if the operation could be
 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
@@ -3875,7 +3872,7 @@ next operation is started on the context.
 @end deftypefun
 
 
-@deftypefun gpgme_error_t gpgme_op_encrypt_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_user_id_t @var{rset}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
+@deftypefun gpgme_error_t gpgme_op_encrypt_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
 The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
 sign operation.  It is used like @code{gpgme_op_encrypt}, but the
 ciphertext also contains signatures for the signers listed in
@@ -3885,17 +3882,15 @@ The combined encrypt and sign operation is currently only available
 for the OpenPGP crypto engine.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_user_id_t @var{rset}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
+@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
 The function @code{gpgme_op_encrypt_sign_start} initiates a
 @code{gpgme_op_encrypt_sign} operation.  It can be completed by
 calling @code{gpgme_wait} on the context.  @xref{Waiting For
 Completion}.
 
 The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
-@code{GPGME_No_UserID} if @var{rset} does not contain any valid
-recipients.
+started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
+@var{rset}, @var{plain} or @var{cipher} is not a valid pointer.
 @end deftypefun