This topic provides information about the following:

Getting Information about a Format Filter

ImageGear provides a set of API functions that simplify the handling of different file formats in the application.

To get information about an ImageGear format filter use the IG_fltr_info_get() function. It returns information about the features supported by ImageGear for this file format (as IG_FLTR_ flags), the short and full names of the filter's file format and the names of the default file's extension:

nErrCount = [lpfn]IG_fltr_info_get( nFormat, &dwFlags, szShortName,
sizeof(szShortName), szFullName, sizeof(szFullName), szDefExt, sizeof(szDefExt) );

Together with this function, you can use the IG_fltr_formatlist_sort() function to sort file formats in alphabetic order based on the short name returned by the IG_fltr_info_get() function through its third lpShortNameparameter.

If you want to determine the list of filters that support the IG_FLTR_ features you can use the function:

IG_fltr_formatlist_get(DWORD dwFlags, LPAT_MODE lpFormatList, UINT nFListSize,
LPUINT lpnFListCount)

Through the dwFlagsargument, you can specify any combination of features (for instance, IG_FLTR_DETECTSUPPORT | IG_FLTR_PAGEREADSUPPORT | IG_FLTR_MPAGEREADPSUPPORT), and a list of filters that support those features will be returned through the second parameter (lpFormatList). See the description of this function in the Core Component API Function Reference for detailed information about the parameters. If you want to determine the value of the nFListSizeargument, first set lpFormatListto NULL. You can also use this function together with IG_fltr_formatlist_sort() to get the list of filters that support necessary features and sort them by filter name:

UINT              nFilterSize;
UINT              nFListSize;
LPAT_MODE         FList = NULL;
LPCHAR            lpFilter = NULL;
LPSTR                   str;
IG_fltr_formatlist_get( IG_FLTR_PAGEREADSUPPORT, NULL, 0, &nFListSize );
FList = malloc( nFListSize*sizeof(AT_MODE) );
if( FList!=NULL )
{
IG_fltr_formatlist_get( IG_FLTR_PAGEREADSUPPORT, FList, nFListSize, NULL );
IG_fltr_formatlist_sort( FList, nFListSize );
...
}

You can get information about any page of a multi-page file without loading it into memory if you use the function IG_fltr_pageinfo_get(). Return information consists of the name of the file format (as IG_FORMAT_ constant), the type of image compression (as IG_COMPRESSION_ constant), and such info as bpp, width and height of the page-image.

Another two IG_fltr_...() functions allow you to work with pages in a multi-page file without loading it in memory:

IG_fltr_pageswap_file (const LPSTR   lpszFileName, AT_MODE  nFormatType,  UINT
Page1, UINT  Page2)

IG_fltr_pagedelete_file (const LPSTR   lpszFileName, AT_MODE  nFormatType,  UINT
nStartPage, UINT  nRange)

Both functions accept the filename of the multi-page image, format filter ID, and two integer parameters as page numbers (assuming numeration from 1). The first function swaps pages in a multi-page image specified by page numbers, but the second function deletes pages from it.

Before using these functions you have to determine whether or not ImageGear supports the corresponding features for the necessary file format. This can be done using the function IG_fltr_info_get() and inspecting flags returned through the second parameter for the specified file formats. If this value contains the flag IG_FLTR_PAGESWAPSUPPORT, then the format filter does support the IG_fltr_pageswap_file() operation. If it also has the flag IG_FLTR_PAGEDELETESUPPORT, then it supports the IG_fltr_pagedelete_file() operation.

Each format filter has its own list of supported features determined by IG_FLTR_ flags. The table below describes the meaning of each of these flags:

Using File Filter Control Parameters

Almost every format filter in ImageGear has some attributes on which it depends while processing operations such as READ, WRITE, etc. Those attributes may be attributes declared by the format filter specification or may be specific to its implementation by ImageGear. ImageGear has a general public interface implemented and named as format filter control parameters. Every such control parameter is identified by the format filter and string name and has an associated type of acceptable value, the value itself, and the default value. Each control parameter is filter specific. The ImageGear Supported File Formats Reference describes the filters, and also describes each control parameter for each format filter.

The ImageGear Filters API has three functions that allow you to get/set info about every supported filter control parameter:

• IG_fltr_ctrl_list(DWORD dwFormatID, LPUINT lpnCount, LPDWORD lpArray, DWORD dwArraySizeInBytes)

  This function allows the application to get the list of names of all control parameters supported by the format filter identified by dwFormatID. The Application is responsible for allocating the buffer lpArray, but ImageGear sets the elements of this array as pointers to strings with control parameter names. You can use the control parameter names as input values for the second argument of the next two functions.

• IG_fltr_ctrl_get(DWORD dwFormatID, const LPCHAR lpcsCtrlName, AT_BOOL bGetDefault, LPAT_MODE lpnValueType, LPDWORD lpdwValueSize, LPVOID lpBuffer, DWORD dwBufferSize)

  This function is used to get the value of a given control parameter of a given format filter, and it may return either its current value or its default value - that is controlled by the bGetDefault argument. A TRUE value returns the default value, but FALSE returns the current value. The value itself is copied into a buffer that the application provides through the dwBufferSize argument. You can use the control parameter names from IG_fltr_ctrl_list as input values for the lpcsCtrlName argument.

• IG_fltr_ctrl_set(DWORD dwFormatID, const LPCHAR lpcsCtrlName, LPVOID lpValue, DWORD dwValueSize)

  This function allows you to set a new value for the control parameter. You can use the control parameter names from IG_fltr_ctrl_list as input values for the lpcsCtrlName argument. The last two arguments of this function specify the data to be set, and ImageGear always treats this data as a type that can be gotten by the _get() function. If the actual size of the new value is less than 4 bytes, then lpValue is treated as the value itself, otherwise it is treated as a pointer to the value.

This example demonstrates how to get the names of all supported control parameters for the TIFF format filter:

/* getting the total number of parameters */
nErrCount = IG_fltr_ctrl_list(IG_FORMAT_TIF, &nCount, NULL, 0);
if(!nErrCount && nCount > 0)
{
/* allocate required buffer to keep all names */
lpOptList = malloc(nCount * sizeof(DWORD));
        if(lpArray)
        {
        nErrCount = IG_fltr_ctrl_list(IG_FORMAT_TIF, NULL, lpOptList, nCount *
sizeof(DWORD));

This example demonstrates how to get and set the value of the TIFF control parameter named "BIG_ENDIAN":

char DocumentName[_MAX_PATH];
AT_BOOL bDefBigEndian, bOldBigEndian;
...
/* get current value of BIG_ENDIAN control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "BIG_ENDIAN", FALSE, NULL, NULL,
(LPVOID)&bOldBigEndian, sizeof(hOldBigEndian));
/* get default value of BIG_ENDIAN control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "BIG_ENDIAN", TRUE, NULL, NULL,
(LPVOID)&bDefBigEndian, sizeof(hDefBigEndian));
/* get current value of DOCUMENT_NAME control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "DOCUMENT_NAME", FALSE, NULL, NULL, DocumentName,
sizeof(DocumentName));
/* set new value to BIG_ENDIAN control parameter */
IG_fltr_ctrl_set(IG_FORMAT_TIF, "BIG_ENDIAN", (LPVOID)TRUE, sizeof(AT_BOOL));
/* set new value to DOCUMENT_NAME control parameter */
strcpy( DocumentName, "This is a test string for DocumentName" );
IG_fltr_ctrl_set(IG_FORMAT_TIF, "DOCUMENT_NAME", (LPVOID)DocumentName,
sizeof(DocumentName));