LBaseFile::SetFilterInfo

#include "ltwrappr.h"

static L_INT LBaseFile::SetFilterInfo(pFilterInfo, uFilterCount, uFlags)

pFILTERINFO pFilterInfo;

/* pointer to FILTERINFO structure */

L_UINT uFilterCount;

/* number of elements in an array */

L_UINT uFlags;

/* flags */

Changes all the filters information obtained in the array ppFilterList parameter by calling the LBaseFile::GetFilterListInfo function; or changes the information of a specific filter obtained in pFilterInfo parameter by calling the LBaseFile::GetFilterInfo function.

Parameter

Description

pFilterInfo

Pointer to FILTERINFO structure to changes the filters information. This parameter cannot be NULL. This pointer points either to an array of information for all filters obtained by LBaseFile::GetFilterListInfo function; or points to information of a specific filter obtained by LBaseFile::GetFilterInfo function.

uFilterCount

Value that represents the number of elements of the pFilterInfo parameter. Possible values are:

 

Value

Meaning

 

1

Change only the memory stored inside the pFilterInfo parameter obtained by the LBaseFile::GetFilterInfo function.

 

>1

Change the memory allocated in the array of information for all filters obtained in the ppFilterList parameter by calling LBaseFile::GetFilterListInfo function.

uFlags

Reserved for future use. Pass 0.

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

The filters are identified by the value of pFilterInfo.szName.

There are currently three types of information can be changed for a filter:

1.

The extension list associated with a specific filter.

 

LEADTOOLS will use the extension list specified by the value of pFilterInfo.pszExtensionList member to quickly test the file format. Whenever LFile::GetInfo function is called for a certain file, the file extension is matched against all the extension lists associated with the file filters. For example, the CMP filter is used to check for files with extensions cmp, jpg, jpeg or tif. If you have files with a certain extension intended to check, add them to the usual extension list and call LBaseFile::SetFilterInfo function.

2.

The usage of extended filter checking for a file. This extended filter checking is specified by the value of pFilterInfo.uFlags member:

 

If the user sets this member to FILTERINFO_CHECKEDBYFILEINFO flag, the extended filter checking will be used and the LFile::GetInfo function will check a certain filter even if the extension does not match the extension list.

 

If the user does not set this member to FILTERINFO_CHECKEDBYFILEINFO flag, the extended filter checking will not be used and the LFile::GetInfo function will check a certain filter ONLY if the extension is in the extension list.

 

Some vectorial filters have a slow check to detect whether a file is of a certain format. In certain cases, the whole file needs to be parsed. If the run of LFile::GetInfo function is taking too long, the user can specify them not to be checked unless the file extension is one of the usual extensions associated with that filter.

 

The user can specify whether process of obtaining the file information of a filter will be slow or not by setting the value of the pFilterInfo.uFlags member to FILTERINFO_SLOWFILEINFO flag.

3.

The handling function of the filter either it will be ignored, fixed in the memory, or dynamically loaded. For more information, refer to LFileSettings::IgnoreFilters and LFileSettings::PreLoadFilters functions. The function of handling the filter is specified by the value of the pFilterInfo.uFlags member. If it is set to:

 

Handling Function:

Meaning:

 

FILTERINFO_IGNORED

The filter will be ignored. In this case, the user cannot load, save or get information for files handled by this filter. This flag overrides the other flags.

 

FILTERINFO_FIXED

The filter will be fixed in memory. Fixed filters will not be unloaded even when the maximum number of filters that can be loaded in memory is reached.

 

 

To set the maximum number of filters that will be loaded at a certain time, specify the value of nFixedFilters parameter of LFileSettings::PreLoadFilters function.

 

FILTERINFO_DYNAMIC

The filter will be dynamically loaded and unloaded as required. LEADTOOLS will load filters when the user loads, save or check files of their corresponding format. When the maximum number of loaded filters has been reached, the least recently used filter will be unloaded.

 

 

To set the number of filters that can be loaded and unloaded dynamically, specify the value of nCachedFilters parameter of LFileSettings::PreLoadFilters function.

 

 

This flag will be used automatically if the user did not set the pFilterInfo.uFlags member to either FILTERINFO_IGNORED or FILTERINFO_FIXED.

 

 

The user can check whether the filter is dynamic as the following: (uFlags & FILTERINFO_LOADMASK) == FILTERINFO_DYNAMIC

If the filter name (pFilterInfo.szName member) is invalid, the function will return ERROR_INV_FILTERNAME error code.

Required DLLs and Libraries

LTFIL

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

See Also

Functions:

LBaseFile::GetFilterListInfo, LBaseFile::GetFilterInfo, LBaseFile::FreeFilterInfo, LFileSettings::IgnoreFilters, LFileSettings::PreLoadFilters, LFile::GetInfo

Topics:

Raster Image Functions: Loading Files

 

Raster Image Functions: Getting and Setting File Information

 

Loading and Saving Images

Example

For an example, refer to LBaseFile::GetFilterInfo.