IFilter::GetChunk

Positions the content filter at the beginning of the next chunk, or the first chunk if this is the first GetChunk call, and returns a description of the current chunk.

SCODE GetChunk(
  STAT_CHUNK * pStat,  //Pointer to description of chunk
);

Parameters

pStat: [out] Pointer to a STAT_CHUNK structure containg a description of the current chunk.

Return Values

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

All of the information in the STAT_CHUNK structure, except for breakType and idChunk, will be taken from the most recent STAT_CHUNK that did not specify CHUNK_NO_BREAK. Other fields in STAT_CHUNK will not be modified. On exit, the other members will contain whatever values were in them on entry to GetChunk. If CHUNK_NO_BREAK is specified, GetChunk writes only to pStat->breakType and pStat->idChunk. Derived chunks (pseudoproperties) cannot be glued using CHUNK_NO_BREAK. A single word cannot span more than two glued chunks.

If GetChunk on the content filter of a linked or embedded object returns FILTER_E_END_OF_CHUNKS, it is the responsibility of the calling content filter to determine if there are any more chunks outside of that embedding or link to be returned. For example, if a document has two embedded objects and the first has returned FILTER_E_END_OF_CHUNKS, then the outer content filter must call GetChunk on the content filter for the next embedded object.

Additionally, before returning the results of a call to GetChunk on an embedded or linked object, the provider must check to make sure that the chunk identifier is unique. If not, the caller must renumber the chunk and keep a mapping of the new chunk identifier.

Chunk ID 0 is invalid.

When GetChunk returns, the chunk described in *pStat is the current chunk. The chunk descriptor is owned by the caller, but the property name pointer, which may be set in the property specification, is owned by the callee and should not be freed. Before GetChunk is called for the first time, there is no current chunk. After an error return code of anything other than FILTER_E_END_OF_CHUNKS the next call to IFilter will still retrieve the next chunk after the unavailable one.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in filter.h.