[libpng17] Changed user chunk callback API to respect global and per chunk

defaults.  Previously a return of 0 from a user chunk callback would result in
the chunk being saved (if this was safe, even if the chunk was unsafe-to-copy);
this change respects the defaults set by the application, so unknown chunks
can be discarded by default and known-safe ones preserved.

ANNOUNCE

@@ -1,5 +1,5 @@
 
-Libpng 1.7.0beta05 - March 2, 2013
+Libpng 1.7.0beta05 - March 3, 2013
 
 This is not intended to be a public release.  It will be replaced
 within a few weeks by a public version or by another test version.
@@ -193,10 +193,13 @@ Version 1.7.0beta04 [February 27, 2013]
   Revised scripts/dfn.awk to work with the buggy MSYS awk that has trouble
     with CRLF line endings.
 
-Version 1.7.0beta05 [March 2, 2013]
+Version 1.7.0beta05 [March 3, 2013]
   Avoid a possible memory leak in contrib/gregbook/readpng.c
-  Fixed bug introduced in libpng-1.6.0beta28 that causes libpng to handle chunks
+  Changed user chunk callback API to respect global and per chunk defaults.
-    even when they have been tagged PNG_HANDLE_CHUNK_NEVER.
+    Previously a return of 0 from a user chunk callback would result in the
+    chunk being saved (if this was safe, even if the chunk was unsafe-to-copy);
+    this change respects the defaults set by the application, so unknown chunks
+    can be discarded by default and known-safe ones preserved.
 
 Send comments/corrections/commendations to png-mng-implement at lists.sf.net
 (subscription required; visit

CHANGES

@@ -4480,10 +4480,13 @@ Version 1.7.0beta04 [February 27, 2013]
   Revised scripts/dfn.awk to work with the buggy MSYS awk that has trouble
     with CRLF line endings.
 
-Version 1.7.0beta05 [March 2, 2013]
+Version 1.7.0beta05 [March 3, 2013]
   Avoid a possible memory leak in contrib/gregbook/readpng.c
-  Fixed bug introduced in libpng-1.6.0beta28 that causes libpng to handle chunks
+  Changed user chunk callback API to respect global and per chunk defaults.
-    even when they have been tagged PNG_HANDLE_CHUNK_NEVER.
+    Previously a return of 0 from a user chunk callback would result in the
+    chunk being saved (if this was safe, even if the chunk was unsafe-to-copy);
+    this change respects the defaults set by the application, so unknown chunks
+    can be discarded by default and known-safe ones preserved.
 
 Send comments/corrections/commendations to png-mng-implement at lists.sf.net
 (subscription required; visit

libpng-manual.txt

@@ -1,6 +1,6 @@
 libpng-manual.txt - A description on how to use and modify libpng
 
- libpng version 1.7.0beta05 - February 27, 2013
+ libpng version 1.7.0beta05 - March 3, 2013
  Updated and distributed by Glenn Randers-Pehrson
  <glennrp at users.sourceforge.net>
  Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -11,7 +11,7 @@ libpng-manual.txt - A description on how to use and modify libpng
 
  Based on:
 
- libpng versions 0.97, January 1998, through 1.7.0beta05 - February 27, 2013
+ libpng versions 0.97, January 1998, through 1.7.0beta05 - March 3, 2013
  Updated and distributed by Glenn Randers-Pehrson
  Copyright (c) 1998-2013 Glenn Randers-Pehrson
 
@@ -527,10 +527,15 @@ you can retrieve with
 
     png_get_user_chunk_ptr(png_ptr);
 
-If you call the png_set_read_user_chunk_fn() function, then all unknown
+If you call the png_set_read_user_chunk_fn() function, then all unknown chunks
-chunks will be saved when read, in case your callback function will need
+will be passed to your callback when read.  You can cause known chunks to be
-one or more of them.  This behavior can be changed with the
+passed in as well by using png_set_keep_unknown_chunks (see below) - this will
-png_set_keep_unknown_chunks() function, described below.
+prevent the normal libpng handling of those known chunks.
+
+If your callback returns 0 the default unknown handling will be used (see
+below).  This is new behavior in libpng 1.7, prior to 1.7 it was not possible to
+discard a chunk; PNG_HANDLE_CHUNK_IF_SAFE was forced.  Libpng 1.6.0 issues a
+warning when this was done.
 
 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
@@ -5187,7 +5192,7 @@ Other rules can be inferred by inspecting the libpng source.
 
 XVII. Y2K Compliance in libpng
 
-February 27, 2013
+March 3, 2013
 
 Since the PNG Development group is an ad-hoc body, we can't make
 an official declaration.

libpng.3

@@ -1,4 +1,4 @@
-.TH LIBPNG 3 "February 27, 2013"
+.TH LIBPNG 3 "March 3, 2013"
 .SH NAME
 libpng \- Portable Network Graphics (PNG) Reference Library 1.7.0beta05
 .SH SYNOPSIS
@@ -494,7 +494,7 @@ Following is a copy of the libpng-manual.txt file that accompanies libpng.
 .SH LIBPNG.TXT
 libpng-manual.txt - A description on how to use and modify libpng
 
- libpng version 1.7.0beta05 - February 27, 2013
+ libpng version 1.7.0beta05 - March 3, 2013
  Updated and distributed by Glenn Randers-Pehrson
  <glennrp at users.sourceforge.net>
  Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -505,7 +505,7 @@ libpng-manual.txt - A description on how to use and modify libpng
 
  Based on:
 
- libpng versions 0.97, January 1998, through 1.7.0beta05 - February 27, 2013
+ libpng versions 0.97, January 1998, through 1.7.0beta05 - March 3, 2013
  Updated and distributed by Glenn Randers-Pehrson
  Copyright (c) 1998-2013 Glenn Randers-Pehrson
 
@@ -1021,10 +1021,15 @@ you can retrieve with
 
     png_get_user_chunk_ptr(png_ptr);
 
-If you call the png_set_read_user_chunk_fn() function, then all unknown
+If you call the png_set_read_user_chunk_fn() function, then all unknown chunks
-chunks will be saved when read, in case your callback function will need
+will be passed to your callback when read.  You can cause known chunks to be
-one or more of them.  This behavior can be changed with the
+passed in as well by using png_set_keep_unknown_chunks (see below) - this will
-png_set_keep_unknown_chunks() function, described below.
+prevent the normal libpng handling of those known chunks.
+
+If your callback returns 0 the default unknown handling will be used (see
+below).  This is new behavior in libpng 1.7, prior to 1.7 it was not possible to
+discard a chunk; PNG_HANDLE_CHUNK_IF_SAFE was forced.  Libpng 1.6.0 issues a
+warning when this was done.
 
 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
@@ -5682,7 +5687,7 @@ Other rules can be inferred by inspecting the libpng source.
 
 .SH XVII. Y2K Compliance in libpng
 
-February 27, 2013
+March 3, 2013
 
 Since the PNG Development group is an ad-hoc body, we can't make
 an official declaration.
@@ -5952,7 +5957,7 @@ possible without all of you.
 
 Thanks to Frank J. T. Wojcik for helping with the documentation.
 
-Libpng version 1.7.0beta05 - February 27, 2013:
+Libpng version 1.7.0beta05 - March 3, 2013:
 Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
 Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
 
@@ -5975,7 +5980,7 @@ this sentence.
 
 This code is released under the libpng license.
 
-libpng versions 1.2.6, August 15, 2004, through 1.7.0beta05, February 27, 2013, are
+libpng versions 1.2.6, August 15, 2004, through 1.7.0beta05, March 3, 2013, are
 Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
 distributed according to the same disclaimer and license as libpng-1.2.5
 with the following individual added to the list of Contributing Authors
@@ -6074,7 +6079,7 @@ certification mark of the Open Source Initiative.
 
 Glenn Randers-Pehrson
 glennrp at users.sourceforge.net
-February 27, 2013
+March 3, 2013
 
 .\" end of man page
 

png.h

@@ -1,7 +1,7 @@
 
 /* png.h - header file for PNG reference library
  *
- * libpng version 1.7.0beta05 - March 2, 2013
+ * libpng version 1.7.0beta05 - March 3, 2013
  * Copyright (c) 1998-2013 Glenn Randers-Pehrson
  * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
  * (Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
@@ -11,7 +11,7 @@
  * Authors and maintainers:
  *   libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat
  *   libpng versions 0.89c, June 1996, through 0.96, May 1997: Andreas Dilger
- *   libpng versions 0.97, January 1998, through 1.7.0beta05 - March 2, 2013: Glenn
+ *   libpng versions 0.97, January 1998, through 1.7.0beta05 - March 3, 2013: Glenn
  *   See also "Contributing Authors", below.
  *
  * Note about libpng version numbers:
@@ -201,7 +201,7 @@
  *
  * This code is released under the libpng license.
  *
- * libpng versions 1.2.6, August 15, 2004, through 1.7.0beta05, March 2, 2013, are
+ * libpng versions 1.2.6, August 15, 2004, through 1.7.0beta05, March 3, 2013, are
  * Copyright (c) 2004, 2006-2013 Glenn Randers-Pehrson, and are
  * distributed according to the same disclaimer and license as libpng-1.2.5
  * with the following individual added to the list of Contributing Authors:
@@ -313,7 +313,7 @@
  * Y2K compliance in libpng:
  * =========================
  *
- *    March 2, 2013
+ *    March 3, 2013
  *
  *    Since the PNG Development group is an ad-hoc body, we can't make
  *    an official declaration.
@@ -381,7 +381,7 @@
 /* Version information for png.h - this should match the version in png.c */
 #define PNG_LIBPNG_VER_STRING "1.7.0beta05"
 #define PNG_HEADER_VERSION_STRING \
-     " libpng version 1.7.0beta05 - March 2, 2013\n"
+     " libpng version 1.7.0beta05 - March 3, 2013\n"
 
 #define PNG_LIBPNG_VER_SONUM   17
 #define PNG_LIBPNG_VER_DLLNUM  17
@@ -1838,7 +1838,7 @@ PNG_EXPORT(218, png_byte, png_get_current_pass_number, (png_const_structrp));
 #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,11 +1850,13 @@ PNG_EXPORT(218, png_byte, png_get_current_pass_number, (png_const_structrp));
  * 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
+ *     zero: The chunk was not handled, the default unknown handling is used
- *           png_set_keep_unknown_chunks has been used to set a 'keep' behavior
+ *           (even if this was a chunk that would otherwise be known.)
- *           for this particular chunk, in which case that will be used.  A
+ *           NOTE: prior to libpng 1.7 handling values of
- *           critical chunk will cause an error at this point unless it is to be
+ *           PNG_HANDLE_CHUNK_AS_DEFAULT and PNG_HANDLE_CHUNK_NEVER were
- *           saved.
+ *           converted to PNG_HANDLE_CHUNK_IF_SAFE (libpng 1.6.0 warns if this
+ *           happens) so it was not possible to discard unknown chunk data if a
+ *           user callback was installed.
  * positive: The chunk was handled, libpng will ignore/discard it.
  */
 PNG_EXPORT(88, void, png_set_read_user_chunk_fn, (png_structrp png_ptr,
@@ -2369,9 +2371,14 @@ PNG_EXPORT(171, void, png_set_sCAL_s, (png_const_structrp png_ptr,
  * NOTE: prior to 1.6.0 the handling specified for particular chunks on read was
  * ignored and the default was used, the per-chunk setting only had an effect on
  * write.  If you wish to have chunk-specific handling on read in code that must
- * work on earlier versions you must use a user chunk callback to specify the
+ * work on earlier versions you must use a user chunk callback to implement the
  * desired handling (keep or discard.)
  * 
+ * NOTE: prior to 1.7.0 when a user callback returned '0', indicating that the
+ * chunk had not been handled, libpng would preserve it regardless of the
+ * default or per-chunk settings.  For compatibility with earlier versions
+ * simply return '1' (handled) from the callback to discard the chunk.
+ *
  * The 'keep' parameter is a PNG_HANDLE_CHUNK_ value as listed below.  The
  * parameter is interpreted as follows:
  *

pngrutil.c

@@ -2801,37 +2801,19 @@ png_handle_unknown(png_structrp png_ptr, png_inforp info_ptr,
             if (ret < 0)
                png_chunk_error(png_ptr, "error in user chunk");
 
-            else if (ret == 0)
+            else if (ret > 0) /* chunk was handled */
-            {
-               /* If the keep value is 'default' or 'never' override it, but
-                * still error out on critical chunks unless the keep value is
-                * 'always'  While this is weird it is the behavior in 1.4.12.
-                * A possible improvement would be to obey the value set for the
-                * chunk, but this would be an API change that would probably
-                * damage some applications.
-                *
-                * The png_app_warning below catches the case that matters, where
-                * the application has not set specific save or ignore for this
-                * chunk or global save or ignore.
-                */
-               if (keep < PNG_HANDLE_CHUNK_NEVER)
-               {
-#                 ifdef PNG_SET_UNKNOWN_CHUNKS_SUPPORTED
-                     if (png_ptr->unknown_default < PNG_HANDLE_CHUNK_IF_SAFE)
-                        png_app_warning(png_ptr,
-                           "forcing save of an unhandled chunk;"
-                           " please call png_set_keep_unknown_chunks");
-#                 endif
-                  keep = PNG_HANDLE_CHUNK_IF_SAFE;
-               }
-            }
-
-            else /* chunk was handled */
             {
                handled = 1;
                /* Critical chunks can be safely discarded at this point. */
                keep = PNG_HANDLE_CHUNK_NEVER;
             }
+
+            /* else: use the default handling.
+             * NOTE: this is an API change in 1.7.0, prior to 1.7.0 libpng would
+             * force keep to PNG_HANDLE_CHUNK_IF_SAFE at this point, and 1.6.0
+             * would issue a warning if this caused a default of discarding the
+             * chunk to be changed.
+             */
          }
 
          else