2008-01-28 Marcus Brinkmann <marcus@g10code.de>

	* gpgme.texi: Document that data encoding affects some output data
	objects now.

diff --git a/NEWS b/NEWS
index 4d420325e7b804ef44a4244d7ec0e3fb7f5642a3..845509176ee7b6473670034dad94ec90cc12a88d 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,10 +1,25 @@
 Noteworthy changes in version 1.1.7 (unreleased)
 ------------------------------------------------
 
- * 
+ * The encoding of gpgme_data_t objects can affect the output encoding
+   of export, sign and encrypt operations now (the same operations
+   that are also affected by the ASCII mode switch).  We believe this
+   change in the ABI is innocent enough not to break existing
+   applications (it only affects the S/MIME backend on certain
+   operations).
 
  * Interface changes relative to the 1.1.6 release:
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+gpgme_op_encrypt               CHANGED: Output encoding can affect result.
+gpgme_op_encrypt_start         CHANGED: Output encoding can affect result.
+gpgme_op_encrypt_sign          CHANGED: Output encoding can affect result.
+gpgme_op_encrypt_sign_start    CHANGED: Output encoding can affect result.
+gpgme_op_sign                  CHANGED: Output encoding can affect result.
+gpgme_op_sign_start            CHANGED: Output encoding can affect result.
+gpgme_op_export                        CHANGED: Output encoding can affect result.
+gpgme_op_export_start          CHANGED: Output encoding can affect result.
+gpgme_op_export_ext            CHANGED: Output encoding can affect result.
+gpgme_op_export_ext_start      CHANGED: Output encoding can affect result.
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 24b2abedf9bbad94f29af61788800f67f98109dc..607a9a4a995c2acb0ccf42556534a2c2f627395b 100644 (file)
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2008-01-28  Marcus Brinkmann  <marcus@g10code.de>
+
+       * gpgme.texi: Document that data encoding affects some output data
+       objects now.
+
 2007-09-27  Marcus Brinkmann  <marcus@g10code.de>
 
        * gpgme.texi (Protocols and Engines): Document GPGME_PROTOCOL_UNKNOWN.

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index fe0ade238f03654b0a45eaddaf42f71109d84ebb..b62cfc8201aac43a9b0d4082c4027cf42508de6f 100644 (file)
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -1868,8 +1868,11 @@ enough memory is available.
 @deftp {Data type} {enum gpgme_data_encoding_t}
 @tindex gpgme_data_encoding_t
 The @code{gpgme_data_encoding_t} type specifies the encoding of a
-@code{gpgme_data_t} object.  This encoding is useful to give the backend
-a hint on the type of data.  The following data types are available:
+@code{gpgme_data_t} object.  For input data objects, the encoding is
+useful to give the backend a hint on the type of data.  For output
+data objects, the encoding can specify the output data format on
+certain operations.  Please note that not all backends support all
+encodings on all operations.  The following data types are available:
 
 @table @code
 @item GPGME_DATA_ENCODING_NONE
@@ -3264,7 +3267,8 @@ operation is started on the context.
 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}.
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
 
 If @var{pattern} is @code{NULL}, all available keys are returned.
 Otherwise, @var{pattern} contains an engine specific expression that
@@ -3292,7 +3296,8 @@ if @var{keydata} is not a valid empty data buffer.
 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}.
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
 
 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
@@ -4490,7 +4495,8 @@ mode settings of the context are ignored.
 The function @code{gpgme_op_sign} creates a signature for the text in
 the data object @var{plain} and returns it in the data object
 @var{sig}.  The type of the signature created is determined by the
-@acronym{ASCII} armor and text mode attributes set for the context
+@acronym{ASCII} armor (or, if that is not set, by the encoding
+specified for @var{sig}), the text mode attributes set for the context
 @var{ctx} and the requested signature mode @var{mode}.
 
 After the operation completed successfully, the result can be
@@ -4650,11 +4656,12 @@ and then passed to the encryption operation.
 @subsubsection Encrypting a Plaintext
 
 @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{recp} and stores the
+The function @code{gpgme_op_encrypt} encrypts the plaintext in the
+data 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}.
+ciphertext created is determined by the @acronym{ASCII} armor (or, if
+that is not set, by the encoding specified for @var{cipher}) and the
+text mode attributes set for the context @var{ctx}.
 
 @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