fpFilter()

Filters text from a document.

Syntax

KVErrorCode (pascal* fpFilter)(
    KVDocument pDocument,
    KVFilterOutput* pFilterOutput);

Arguments

pDocument	A KVDocument that you created with fpOpenDocumentFromFile() or fpOpenDocumentFromStream().
pFilterOutput	A pointer to an existing KVFilterOutput structure. On success, fpFilter populates this structure with the filtered text.

Returns

The return value is an error code.

• If the call is successful, the return value is KVError_Success and the filtered text is stored in pFilterOutput.
• If the call is unsuccessful, the return value is an error code that indicates the problem.

Lifetimes and Memory Management

• After each successful call to fpFilter, when you no longer require the data in the pFilterOutput structure, call fpFreeFilterOutput to free the memory allocated by this function. Call fpFreeFilterOutput only if fpFilter returns KVError_Success. You must call fpFreeFilterOutput before you call fpShutdown().

Discussion

• This function outputs filtered text in chunks. The first call to fpFilter() outputs the first chunk of filtered text to pFilterOutput. Call fpFilter() again to output the next chunk, and repeat this process to obtain all of the filtered text from the document. The final chunk does not contain any text, such that pFilterOutput->cbText == 0. Do not call fpFilter() again after this.

  IMPORTANT: Do not call any Filter API functions between calls to fpFilter(), because doing so might prevent filtering from resuming correctly.

• If fpFilter returns an error, filtering failed and you must not call fpFilter() again for this pDocument because it will not obtain any more text.

• When you run out-of-process, fpFilter needs to be responsive, which means that it must strike a balance between returning data in appropriate-sized chunks, and minimizing the time spent on processing overhead. In out-of-process mode, the slowest part is the cross-process context switch, so filtering attempts to minimize the number of times it switches between processes. To achieve this, File Content Extraction creates batches of filter text, up to a size or time limit. Because of the time factor, the size of each chunk might vary across different runs.