From ef430d7828d5d9724fa787685662afbd5e248ebb Mon Sep 17 00:00:00 2001 From: Marcus Brinkmann Date: Mon, 28 Jan 2008 19:41:26 +0000 Subject: [PATCH] 2008-01-28 Marcus Brinkmann * gpgme.texi: Document that data encoding affects some output data objects now. --- NEWS | 17 ++++++++++++++++- doc/ChangeLog | 5 +++++ doc/gpgme.texi | 25 ++++++++++++++++--------- 3 files changed, 37 insertions(+), 10 deletions(-) diff --git a/NEWS b/NEWS index 4d420325..84550917 100644 --- 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 24b2abed..607a9a4a 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2008-01-28 Marcus Brinkmann + + * gpgme.texi: Document that data encoding affects some output data + objects now. + 2007-09-27 Marcus Brinkmann * gpgme.texi (Protocols and Engines): Document GPGME_PROTOCOL_UNKNOWN. diff --git a/doc/gpgme.texi b/doc/gpgme.texi index fe0ade23..b62cfc82 100644 --- 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