fpOpenDocumentFromStream()

Creates a KVDocument from a stream.

The KVDocument type is an opaque pointer that represents a single document. You can pass the KVDocument into other functions in the Filter API to perform operations with that document.

Syntax

KVErrorCode (pascal* fpOpenDocumentFromStream)(
    KVFilterSession session,
    KVInputStream* pInput,
    KVDocument* ppDocument);

Arguments

session

A Filter session that you initialized by calling fpInit().

pInput A pointer to a KVInputStream. Before calling this function you must create an input stream by using code similar to that in the Filter sample program.
ppDocument A pointer to a KVDocument.

Returns

The return value is an error code.

  • If the call is successful, the return value is KVError_Success and the KVDocument is stored in *ppDocument.
  • If the call is unsuccessful, the return value is an error code and *ppDocument is set to NULL.

Lifetimes and Memory Management

  • If the function returns KVError_Success, when you have finished with the KVDocument that was returned in *ppDocument, you must call fpCloseDocument() to free the memory that was allocated by this function.
  • The Filter session must outlive the KVDocument created by this function. In other words, you must call fpCloseDocument() on the KVDocument before calling fpShutdown() on the Filter session (session) that was used to create it.
  • The pInput must outlive the KVDocument created by this function. You must call fpCloseDocument() on the KVDocument before you close or destroy it.

Discussion

  • After creating a KVDocument from a stream, you must not use the input stream for anything else until you have closed the document by calling fpCloseDocument().

Example

The following example demonstrates the creation of a KVDocument from a stream.

KVDocument pDocument = NULL;
error = fpOpenDocumentFromStream(session, pInput, &pDocument)