IFilter::GetChunk method

Retrieves a description of the current chunk and positions the filter at the beginning of the next chunk, or at the first chunk if this is the first call to the GetChunk method.

Syntax


SCODE GetChunk(
  [out] STAT_CHUNK *pStat
);

Parameters

pStat [out]

Type: STAT_CHUNK*

Pointer to a STAT_CHUNK structure that contains a description of the current chunk.

Return value

Type: SCODE

Return codeDescription
S_OK

Successful completion.

FILTER_E_END_OF_CHUNKS

The previous chunk is the last chunk.

FILTER_E_EMBEDDING_UNAVAILABLE

The next chunk is an embedding and no content filter is available.

FILTER_E_LINK_UNAVAILABLE

The next chunk is a link and no content filter is available.

FILTER_E_PASSWORD

Password or other security-related access failure.

FILTER_E_ACCESS

General access failure.

 

Remarks

If on return, pStat points to a STAT_CHUNK structure with the breakType member equal to CHUNK_NO_BREAK, only the idChunk member will be updated with the new chunk ID value. The other members of the STAT_CHUNK structure remain unchanged.

Internal value-type properties (chunks with a CHUNKSTATE enumeration value of CHUNK_VALUE) cannot be concatenated using CHUNK_NO_BREAK. A single word cannot span more than two glued chunks.

Chunk ID zero is invalid.

Notes to Callers

When the GetChunk method finishes, the chunk described in *pStat is the current chunk. The chunk descriptor is owned by the routine calling the GetChunk method, but the property name pointer, which can be set in the property specification, is owned by the GetChunk method and should not be freed.

Notes to Implementers

If a call to the GetChunk method of the content filter of a linked or embedded object returns FILTER_E_END_OF_CHUNKS, the implementation should retrieve the next chunk of the linking or embedding object. For example, if a document has two embedded objects and the first has returned FILTER_E_END_OF_CHUNKS, the outer content filter must call the GetChunk method of the content filter for the embedded object.

Before returning the results of a call to the GetChunk method on an embedded or linked object, be sure that the chunk ID is unique. If not, the implementer must renumber the chunk and map the new chunk ID to the old one.

The IFilterSample code sample, available on Code Gallery and the Windows 7 SDK, demonstrates how to create an IFilter base class for implementing the IFilter interface.

For conceptual information about IFilter implementation, see Developing Filter Handlers. For information about IFilters and property handlers, see "Full-Text Support" and "Operating System Implementation Considerations" in Developing Property Handlers for Windows Search.

Important  In Windows 7 and later, filters written in managed code are explicitly blocked. Filters MUST be written in native code due to potential CLR versioning issues with the process that multiple add-ins run in.
 

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Redistributable

Windows NT 4.0 Option Pack

Header

Filter.h

See also

Reference
IFilter
GetText
GetValue
CHUNKSTATE
CHUNK_BREAKTYPE
STAT_CHUNK

 

 

Community Additions

ADD
Show: