png_set_keep_unknown_chunks

Name

png_set_keep_unknown_chunks -- specify list of chunks and how to handle them

Synopsis

#include <png.h>

void png_set_keep_unknown_chunks(png_structp png_ptr, int keep, png_bytep chunk_list, int num_chunks);

Description

This interface shall specify a list of chunks in the input PNG stream and how to handle them. Any unspecified chunks shall be handled in the default way. The IEND and IHDR chunks must not be specified.

The parameter png_ptr shall specify the PNG file.

The parameter keep shall specify how the unknown chunks are to be handled (see below).

The parameter chunk_list shall specify the list of chunks that shall be affected. The value passed must be a string of bytes with five bytes per chunk, or NULL or \0 if the value of num_chunks is 0.

The parameter num_chunks shall specify the number of chunks to be affected. If the value is 0, all unknown chunks shall be affected.

The possible values of keep are as follows.

0 

handle unknown chunks in the default way

1 

do not keep unknown chunks

2 

keep unknown chunks only if they are safe to copy

3 

keep unknown chunks even if they are unsafe to copy

Application Usage (informative)

The normal behavior of libpng is that known chunks are processed and unknown chunks are discarded. This interface reads both known and unknown chunks, handling them as specified by the user.

Unknown chunks specified to this interface are saved unchanged in a list of png_unknown_chunk structures. If a known chunk is specified in the list of unknown chunks, it will be handled per the keep parameter. If a chunk is specified in successive calls to this interface, the final call takes precedence.