From 352c1a7d03cb12f5bc18d116da6b8c1ab5a281d7 Mon Sep 17 00:00:00 2001
From: Even Rouault <[EMAIL REDACTED]>
Date: Sat, 12 Nov 2022 17:46:47 +0100
Subject: [PATCH] Document TIFFOpenExt, TIFFOpenWExt, TIFFFdOpenExt,
TIFFClientOpenExt, TIFFSetErrorHandlerExtR, TIFFSetWarningHandlerExtR
---
doc/functions/TIFFError.rst | 9 ++++-
doc/functions/TIFFOpen.rst | 63 +++++++++++++++++++++++++++++++++++
doc/functions/TIFFWarning.rst | 15 +++++++++
3 files changed, 86 insertions(+), 1 deletion(-)
diff --git a/doc/functions/TIFFError.rst b/doc/functions/TIFFError.rst
index f03eef8c..3648db77 100644
--- a/doc/functions/TIFFError.rst
+++ b/doc/functions/TIFFError.rst
@@ -23,6 +23,10 @@ Synopsis
.. c:function:: TIFFErrorHandlerExt TIFFSetErrorHandlerExt(TIFFErrorHandlerExt handler)
+.. c:type:: int (*TIFFErrorHandlerExtR)(TIFF* tif, void* errorhandler_user_data, const char * module, const char* fmt, va_list ap)
+
+.. c:function:: void TIFFSetErrorHandlerExtR(TIFF* tif, TIFFErrorHandlerExtR handler, void* errorhandler_user_data)
+
Description
-----------
@@ -43,7 +47,10 @@ as *fd*, which represents the TIFF file handle (file descriptor).
.. TODO: Check description, how to setup a TIFFErrorExt handler and its file handle.
-With :c:func:`TIFFSetErrorHandlerExt` an extra error handler can be setup.
+With :c:func:`TIFFSetErrorHandlerExt` an extra error handler can be setup
+in order to write to a file. The file handle needs to be stored in
+``tif->tif_clientdata`` if the ``libtiff`` internal errors shall also
+be written to that file.
Note
----
diff --git a/doc/functions/TIFFOpen.rst b/doc/functions/TIFFOpen.rst
index 29c7cfc6..7d96161f 100644
--- a/doc/functions/TIFFOpen.rst
+++ b/doc/functions/TIFFOpen.rst
@@ -35,6 +35,52 @@ Synopsis
.. c:function:: thandle_t TIFFSetClientdata(TIFF* tif, thandle_t newvalue)
+.. c:struct:: TIFFOpenExtStruct
+
+ .. c:var:: int version
+
+ .. c:var:: TIFFErrorHandlerExtR errorhandler
+
+ .. c:var:: void* errorhandler_user_data
+
+ .. c:var:: TIFFErrorHandlerExtR warnhandler
+
+ .. c:var:: void* warnhandler_user_data
+
+.. c:function:: TIFF* TIFFOpenExt(const char* filename, const char* mode, TIFFOpenExtStruct* arguments)
+
+.. c:function:: TIFF* TIFFOpenWExt(const wchar_t* name, const char* mode, TIFFOpenExtStruct* arguments)
+
+.. c:function:: TIFF* TIFFFdOpenExt(const int fd, const char* filename, const char*mode, TIFFOpenExtStruct* arguments)
+
+.. c:struct:: TIFFClientOpenExtStruct
+
+ .. c:var:: int version
+
+ .. c:var:: TIFFReadWriteProc readproc
+
+ .. c:var:: TIFFReadWriteProc writeproc
+
+ .. c:var:: TIFFSeekProc seekproc
+
+ .. c:var:: TIFFCloseProc closeproc
+
+ .. c:var:: TIFFSizeProc sizeproc
+
+ .. c:var:: TIFFMapFileProc mapproc
+
+ .. c:var:: TIFFUnmapFileProc unmapproc
+
+ .. c:var:: TIFFErrorHandlerExtR errorhandler
+
+ .. c:var:: void* errorhandler_user_data
+
+ .. c:var:: TIFFErrorHandlerExtR warnhandler
+
+ .. c:var:: void* warnhandler_user_data
+
+.. c:function:: TIFF* TIFFClientOpenExt(const char* filename, const char* mode, thandle_t clientdata, TIFFOpenExtStruct* arguments)
+
Description
-----------
@@ -86,6 +132,18 @@ first :c:func:`TIFFCleanup` should be called to free the internal
TIFF structure without closing the file handle and afterwards the
file should be closed using its file descriptor *fd*.
+:c:func:`TIFFOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFOpen`, but re-entrant
+error and warning handlers may be passed. The version member of the arguments
+structure should be set to 1 for now.
+
+:c:func:`TIFFOpenWExt` (added in libtiff 4.5) is like :c:func:`TIFFOpenW`, but re-entrant
+error and warning handlers may be passed. The version member of the arguments
+structure should be set to 1 for now.
+
+:c:func:`TIFFFdOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFFdOpen`, but re-entrant
+error and warning handlers may be passed. The version member of the arguments
+structure should be set to 1 for now.
+
:c:func:`TIFFSetFileName` sets the file name in the tif-structure
and returns the old file name.
@@ -123,6 +181,11 @@ The clientdata is used as open file's I/O descriptor within ``libtiff``.
When updating the file's clientdata with :c:func:`TIFFSetClientdata`,
the *fd* value is **not** updated.
+:c:func:`TIFFClientOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFClientOpen`, but re-entrant
+error and warning handlers may be passed, as well as their respective user_data.
+The version member of the arguments structure should be set to 1 for now.
+
+:c:func:`TIFFClientdata` returns open file's clientdata handle.
Options
-------
diff --git a/doc/functions/TIFFWarning.rst b/doc/functions/TIFFWarning.rst
index 38bfbf1c..281341f0 100644
--- a/doc/functions/TIFFWarning.rst
+++ b/doc/functions/TIFFWarning.rst
@@ -23,6 +23,11 @@ Synopsis
.. c:function:: TIFFWarningHandlerExt TIFFSetWarningHandlerExt(TIFFWarningHandlerExt handler)
+.. c:type:: int (*TIFFWarningHandlerExtR)(TIFF* tif, void* warnhandler_user_data, const char * module, const char* fmt, va_list ap)
+
+.. c:function:: void TIFFSetWarningHandlerExtR(TIFF* tif, TIFFWarningHandlerExtR handler, void* warnhandler_user_data)
+
+
Description
-----------
@@ -49,6 +54,16 @@ as *fd*, which represents the TIFF file handle (file descriptor).
With :c:func:`TIFFSetWarningHandlerExt` an extra warning handler can be
setup up.
+:c:func:`TIFFSetWarningHandlerExtR` (added in libtiff 4.5) installs a warning
+handler for a given TIFF handle. The R suffix means re-entrant, in that it avoids
+the global effects of :c:func:`TIFFSetWarningHandler` or :c:func:`TIFFSetWarningHandlerExt`.
+The installed handler replaces any previously set handler with that function.
+The handler should nominally return a non-0 value. If it returns 0, then the
+global handler set with :c:func:`TIFFSetWarningHandler` or :c:func:`TIFFSetWarningHandlerExt`
+will also be called.
+Note that this per-TIFF handler may also be installed with :c:func:`TIFFOpenExt`
+or :c:func:`TIFFClientOpenExt`
+
Note
----