IFilter
The IFilter interface scans documents for text and properties (also called attributes). It extracts chunks of text from these documents, filtering out embedded formatting and retaining information about the position of the text. It also extracts chunks of values, which are properties of an entire document or of well-defined parts of a document. IFilter provides the foundation for building higher-level applications such as document indexers and application-independent viewers.
For introductory information about how the IFilter interface works with documents and document properties, see Properties of Documents. For a synopsis and an example of how the IFilter interface processes a document, see Property Filtering and Property Indexing.
When to Implement
Implement this interface if you are providing a filter to extract information from a proprietary file format so that the text and properties can be included in the index. For information about constructing an IFilter implementation, see Constructing Filters. For information about registering a dynamic-link library (DLL) to be called by Indexing Service for the associated file class, see Applying Filters. For information about testing your IFilter implementation, see Testing Filters.
When to Use
Full-text search engines like Indexing Service call the methods of this interface to extract text and property information for creating an index. Text viewers can also use this interface after a query, for example, to show the hit highlights for that file.
Indexing Service uses three functions to access registered IFilter implementations. These functions are especially useful when loading and binding to an embedded object's IFilter implementation. The functions are: LoadIFilter, BindIFilterFromStorage, and BindIFilterFromStream.
Methods in Vtable Order
| IUnknown methods | Description |
|---|
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments reference count. |
| Release | Decrements reference count. |
| IFilter methods | Description |
|---|
| Init | Initializes a filtering session. |
| GetChunk | Positions filter at beginning of first or next chunk and returns a descriptor. |
| GetText | Retrieves text from the current chunk. |
| GetValue | Retrieves values from the current chunk. |
| BindRegion | Retrieves an interface representing the specified portion of object. Currently reserved for future use. |
Microsoft® Windows® NT® or later: Requires Windows NT 4.0 with the Windows NT 4.0 Option Pack or Microsoft Windows 2000 or later.
Header: Declared in filter.h.
Import Library: User-defined.
Remarks
IFilter components for Indexing Service run in the Local Security context and should be written to manage buffers and to stack correctly. All string copies must have explicit checks to guard against buffer overruns. You should always verify the allocated size of the buffer and test the size of the data against the size of the buffer.
See Also
Applying Filters, BindIFilterFromStorage, BindIFilterFromStream, CHUNK_BREAKTYPE, CHUNKSTATE, Constructing Filters, FILTERREGION, FULLPROPSPEC, IFILTER_FLAGS, IFILTER_INIT, LoadIFilter, PROPVARIANT, Secure Code Practices, STAT_CHUNK, Testing Filters