[libpng16] Better documentation of unknown handling API interactions.
diff --git a/ANNOUNCE b/ANNOUNCE
index bbb0e12..6c2ae40 100644
--- a/ANNOUNCE
+++ b/ANNOUNCE
@@ -68,6 +68,7 @@
Avoid a possible memory leak in contrib/gregbook/readpng.c
Version 1.6.1beta06 [March 2, 2013]
+ Better documentation of unknown handling API interactions.
Send comments/corrections/commendations to png-mng-implement at lists.sf.net
(subscription required; visit
diff --git a/CHANGES b/CHANGES
index 02abe37..d75b9ef 100644
--- a/CHANGES
+++ b/CHANGES
@@ -4425,6 +4425,7 @@
Avoid a possible memory leak in contrib/gregbook/readpng.c
Version 1.6.1beta06 [March 2, 2013]
+ Better documentation of unknown handling API interactions.
Send comments/corrections/commendations to png-mng-implement at lists.sf.net
(subscription required; visit
diff --git a/libpng-manual.txt b/libpng-manual.txt
index 58858e9..898f095 100644
--- a/libpng-manual.txt
+++ b/libpng-manual.txt
@@ -527,9 +527,14 @@
png_get_user_chunk_ptr(png_ptr);
If you call the png_set_read_user_chunk_fn() function, then all unknown
-chunks will be saved when read, in case your callback function will need
-one or more of them. This behavior can be changed with the
-png_set_keep_unknown_chunks() function, described below.
+chunks which the callback does not handle will be saved when read. You can
+cause them to be discarded by returning '1' ("handled") instead of '0'. This
+behavior will change in libpng 1.7 and the default handling set by the
+png_set_keep_unknown_chunks() function, described below, will be used when the
+callback returns 0. If you want the existing behavior you should set the global
+default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current
+versions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep the
+default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.
At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control
@@ -628,8 +633,10 @@
...
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
- /* ignore all unknown chunks: */
- png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
+ /* ignore all unknown chunks
+ * (use global setting "2" for libpng16 and earlier):
+ */
+ png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0);
/* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
diff --git a/libpng.3 b/libpng.3
index 0f5d16a..dadbb3d 100644
--- a/libpng.3
+++ b/libpng.3
@@ -1031,9 +1031,14 @@
png_get_user_chunk_ptr(png_ptr);
If you call the png_set_read_user_chunk_fn() function, then all unknown
-chunks will be saved when read, in case your callback function will need
-one or more of them. This behavior can be changed with the
-png_set_keep_unknown_chunks() function, described below.
+chunks which the callback does not handle will be saved when read. You can
+cause them to be discarded by returning '1' ("handled") instead of '0'. This
+behavior will change in libpng 1.7 and the default handling set by the
+png_set_keep_unknown_chunks() function, described below, will be used when the
+callback returns 0. If you want the existing behavior you should set the global
+default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current
+versions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep the
+default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.
At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control
@@ -1132,8 +1137,10 @@
...
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
- /* ignore all unknown chunks: */
- png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
+ /* ignore all unknown chunks
+ * (use global setting "2" for libpng16 and earlier):
+ */
+ png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0);
/* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
diff --git a/png.h b/png.h
index 0faeb4c..a781197 100644
--- a/png.h
+++ b/png.h
@@ -1838,7 +1838,7 @@
#endif
#ifdef PNG_READ_USER_CHUNKS_SUPPORTED
-/* This callback is called only for *unknown* chunks, if
+/* This callback is called only for *unknown* chunks. If
* PNG_HANDLE_AS_UNKNOWN_SUPPORTED is set then it is possible to set known
* chunks to be treated as unknown, however in this case the callback must do
* any processing required by the chunk (e.g. by calling the appropriate
@@ -1850,12 +1850,12 @@
* The integer return from the callback function is interpreted thus:
*
* negative: An error occured, png_chunk_error will be called.
- * zero: The chunk was not handled, the chunk will be discarded unless
- * png_set_keep_unknown_chunks has been used to set a 'keep' behavior
- * for this particular chunk, in which case that will be used. A
- * critical chunk will cause an error at this point unless it is to be
- * saved.
+ * zero: The chunk was not handled, the chunk will be saved. A critical
+ * chunk will cause an error at this point unless it is to be saved.
* positive: The chunk was handled, libpng will ignore/discard it.
+ *
+ * See "INTERACTION WTIH USER CHUNK CALLBACKS" below for important notes about
+ * how this behavior will change in libpng 1.7
*/
PNG_EXPORT(88, void, png_set_read_user_chunk_fn, (png_structrp png_ptr,
png_voidp user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn));
@@ -2389,12 +2389,21 @@
* to specifying "NEVER", however when "AS_DEFAULT" is used for specific chunks
* it simply resets the behavior to the libpng default.
*
+ * INTERACTION WTIH USER CHUNK CALLBACKS:
* The per-chunk handling is always used when there is a png_user_chunk_ptr
* callback and the callback returns 0; the chunk is then always stored *unless*
* it is critical and the per-chunk setting is other than ALWAYS. Notice that
* the global default is *not* used in this case. (In effect the per-chunk
* value is incremented to at least IF_SAFE.)
*
+ * IMPORTANT NOTE: this behavior will change in libpng 1.7 - the global and
+ * per-chunk defaults will be honored. If you want to preserve the current
+ * behavior when your callback returns 0 you must set PNG_HANDLE_CHUNK_IF_SAFE
+ * as the default - if you don't do this libpng 1.6 will issue a warning.
+ *
+ * If you want unhandled unknown chunks to be discarded in libpng 1.6 and
+ * earlier simply return '1' (handled).
+ *
* PNG_HANDLE_AS_UNKNOWN_SUPPORTED:
* If this is *not* set known chunks will always be handled by libpng and
* will never be stored in the unknown chunk list. Known chunks listed to
