doc: Update NEWS and API documentation

--

GnuPG-bug-id: 6342

2 files changed, 66 insertions, 8 deletions

diff --git a/NEWS b/NEWS
index 824faeb7..365d4f95 100644
--- a/NEWS
+++ b/NEWS
@@ -11,8 +11,8 @@ Noteworthy changes in version 1.18.1 (unreleased)
    gpgme_op_sign* to allow creating an encrypted and/or signed
    archive.  [T6342]
 
- * Extended gpgme_op_decrypt* and gpgme_op_decrypt_verify* to allow
-   extracting an encrypted and/or signed archive.  [T6342]
+ * Extended gpgme_op_decrypt*, gpgme_op_decrypt_verify*, and gpgme_op_verify*
+   to allow extracting an encrypted and/or signed archive.  [T6342]
 
  * cpp: Handle error when trying to sign expired keys.  [T6155]
 
@@ -36,6 +36,10 @@ Noteworthy changes in version 1.18.1 (unreleased)
  GPGME_DECRYPT_ARCHIVE                      NEW.
  GPGME_ENCRYPT_ARCHIVE                      NEW.
  GPGME_SIG_MODE_ARCHIVE                     NEW.
+ GPGME_VERIFY_ARCHIVE                       NEW.
+ gpgme_verify_flags_t                       NEW.
+ gpgme_op_verify_ext_start                  NEW.
+ gpgme_op_verify_ext                        NEW.
  cpp: GpgGenCardKeyInteractor::Curve        NEW.
  cpp: GpgGenCardKeyInteractor::setCurve     NEW.
  qt: ListAllKeysJob::Option                 NEW.
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 184b1afe..d7c38f82 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -5589,12 +5589,6 @@ The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
 data object @var{cipher} and stores it into the data object
 @var{plain}.
 
-If the flag @code(GPGME_DECRYPT_ARCHIVE) is set, then an encrypted
-archive in the data object @var{cipher} is decrypted and extracted.
-The content of the archive is extracted into a directory named
-@code{GPGARCH_n_} (where @code{n} is a number) or into the directory
-set with @code{gpgme_data_set_file_name} for the data object @var{plain}.
-
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
@@ -5628,6 +5622,12 @@ The function @code{gpgme_op_decrypt_ext} is the same as
 @code{gpgme_op_decrypt} but has an additional argument
 @var{flags}.  If @var{flags} is 0 both function behave identically.
 
+If the flag @code(GPGME_DECRYPT_ARCHIVE) is set, then an encrypted
+archive in the data object @var{cipher} is decrypted and extracted.
+The content of the archive is extracted into a directory named
+@code{GPGARCH_n_} (where @code{n} is a number) or into the directory
+set with @code{gpgme_data_set_file_name} for the data object @var{plain}.
+
 The value in @var{flags} is a bitwise-or combination of one or
 multiple of the following bit values:
 
@@ -5824,6 +5824,60 @@ operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
 any data to verify.
 @end deftypefun
 
+
+@deftypefun gpgme_error_t gpgme_op_verify_ext ( @
+            @w{gpgme_ctx_t @var{ctx}}, @
+            @w{gpgme_verify_flags_t @var{flags}}, @
+            @w{gpgme_data_t @var{sig}}, @
+            @w{gpgme_data_t @var{signed_text}}, @
+            @w{gpgme_data_t @var{plain}})
+
+The function @code{gpgme_op_verify_ext} is the same as
+@code{gpgme_op_verify} but has an additional argument
+@var{flags}.  If @var{flags} is 0 both function behave identically.
+
+If the flag @code(GPGME_VERIFY_ARCHIVE) is set, then a signed archive
+in the data object @var{sig} is verified and extracted. The content of
+the archive is extracted into a directory named @code{GPGARCH_n_}
+(where @code{n} is a number) or into the directory set with
+@code{gpgme_data_set_file_name} for the data object @var{plain}.
+
+The value in @var{flags} is a bitwise-or combination of one or
+multiple of the following bit values:
+
+@table @code
+@item GPGME_VERIFY_ARCHIVE
+@since{1.19.0}
+
+The @code{GPGME_VERIFY_ARCHIVE} symbol specifies that the input is a
+signed archive that shall be verified and extracted.  This feature
+is currently only supported for the OpenPGP crypto engine.
+
+@end table
+
+The function returns the error codes as descriped for
+@code{gpgme_op_decrypt} respective @code{gpgme_op_encrypt}.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_verify_ext_start ( @
+            @w{gpgme_ctx_t @var{ctx}}, @
+            @w{gpgme_verify_flags_t @var{flags}}, @
+            @w{gpgme_data_t @var{sig}}, @
+            @w{gpgme_data_t @var{signed_text}}, @
+            @w{gpgme_data_t @var{plain}})
+
+The function @code{gpgme_op_verify_ext_start} initiates a
+@code{gpgme_op_verify_ext} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
+@code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
+any data to verify.
+@end deftypefun
+
+
 @deftp {Data type} {gpgme_sig_notation_t}
 This is a pointer to a structure used to store a part of the result of
 a @code{gpgme_op_verify} operation.  The structure contains the