TIFFOpenOptions

Synopsis

#include <tiffio.h>

typedef TIFFOpenOptions TIFFOpenOptions

TIFFOpenOptions *TIFFOpenOptionsAlloc(void)

void TIFFOpenOptionsFree(TIFFOpenOptions*)

void TIFFOpenOptionsSetMaxSingleMemAlloc(TIFFOpenOptions *opts, tmsize_t max_single_mem_alloc)

void TIFFOpenOptionsSetMaxCumulatedMemAlloc(TIFFOpenOptions *opts, tmsize_t max_cumulated_mem_alloc)

void TIFFOpenOptionsSetErrorHandlerExtR(TIFFOpenOptions *opts, TIFFErrorHandlerExtR handler, void *errorhandler_user_data)

void TIFFOpenOptionsSetWarningHandlerExtR(TIFFOpenOptions *opts, TIFFErrorHandlerExtR handler, void *warnhandler_user_data)

void TIFFOpenOptionsSetWarnAboutUnknownTags(TIFFOpenOptions *opts, int warn_about_unknown_tags)

Description

TIFFOpenOptions is an opaque structure which can be passed to the TIFF open"Ext" functions to define some libtiff internal settings. The settings are the maximum single memory allocation limit and per-TIFF handle (re-entrant) error handler and warning handler functions. For those handler a pointer to a custom defined data structure user_data can be given along.

TIFFOpenOptionsAlloc() allocates memory for the TIFFOpenOptions opaque structure and returns a TIFFOpenOptions pointer.

TIFFOpenOptionsFree() releases the allocated memory for TIFFOpenOptions. The allocated memory for TIFFOpenOptions can be released straight after successful execution of the related TIFFOpen"Ext" functions like TIFFOpenExt().

TIFFOpenOptionsSetMaxSingleMemAlloc() (added in libtiff 4.5.0) sets the value for the maximum single memory limit in byte that libtiff internal memory allocation functions are allowed to request per call.

Note

However, the libtiff external functions _TIFFmalloc() and _TIFFrealloc() do not apply this internal memory allocation limit set by TIFFOpenOptionsSetMaxSingleMemAlloc()!

TIFFOpenOptionsSetMaxCumulatedMemAlloc() (added in libtiff 4.6.1) sets the maximum cumulated memory allocations in byte, for a given TIFF handle, that libtiff internal memory allocation functions are allowed.

Note

However, the libtiff external functions _TIFFmalloc() and _TIFFrealloc() do not apply this internal memory allocation limit set by TIFFOpenOptionsSetMaxCumulatedMemAlloc()!

TIFFOpenOptionsSetErrorHandlerExtR() sets the function pointer to an application-specific and per-TIFF handle (re-entrant) error handler. Furthermore, a pointer to a custom defined data structure errorhandler_user_data can be passed. This error handler is invoked through TIFFErrorExtR() and the errorhandler_user_data pointer is given along. The errorhandler_user_data argument may be NULL.

TIFFOpenOptionsSetWarningHandlerExtR() works like TIFFOpenOptionsSetErrorHandlerExtR() but for the warning handler, which is invoked through TIFFWarningExtR()

TIFFOpenOptionsSetWarnAboutUnknownTags() sets whether libtiff should emit a warning when encountering a unknown tag. This function has been added in libtiff 4.7.1 and the default value is FALSE (change of behaviour compared to earlier versions).

Example

#include "tiffio.h"

typedef struct MyErrorHandlerUserDataStruct
{
    /* ... any user data structure ... */
} MyErrorHandlerUserDataStruct;

static int myErrorHandler(TIFF *tiff, void *user_data, const char *module,
                      const char *fmt, va_list ap)
{
    MyErrorHandlerUserDataStruct *errorhandler_user_data =
        (MyErrorHandlerUserDataStruct *)user_data;
    /*... code of myErrorHandler ...*/
    return 1;
}


main()
{
    tmsize_t limit = (256 * 1024 * 1024);
    MyErrorHandlerUserDataStruct user_data = { /* ... any data ... */};

    TIFFOpenOptions *opts = TIFFOpenOptionsAlloc();
    TIFFOpenOptionsSetMaxSingleMemAlloc(opts, limit);
    TIFFOpenOptionsSetErrorHandlerExtR(opts, myErrorHandler, &user_data);
    TIFF *tif = TIFFOpenExt("foo.tif", "r", opts);
    TIFFOpenOptionsFree(opts);
    /* ... go on here ... */

    TIFFClose(tif);
}

Note

This functionality was introduced with libtiff 4.5.

See also

libtiff (3tiff), TIFFOpen (3tiff), TIFFError (3tiff), TIFFWarning (3tiff)