KVXMLStartOOPSession()

This function performs the following:

  • Initializes the out-of-process session.

  • Specifies the input stream or file.

  • Sets conversion options in the KVXMLTemplate, KVXMLOptions, and KVXMLTOCOptions data structures.

  • Creates a Servant process.

  • Establishes a communication channel between the application thread and the Servant.

  • Sends the data to the Servant.

Syntax

BOOL pascal KVXMLStartOOPSession(
    void                *pContext,
    KVInputStream       *pInputStream,
    char                *pFileName,
    KVXMLTemplate       *pTemplates,
    KVXMLOptions        *pOptions,
    KVXMLTOCOptions     *pTOCCreateOptions
    DWORD               *pPID,
    KVErrorCode         *pError
    DWORD                dwOptions,
    void                *pReserved1,
    void                *pReserved2 );

Arguments

pContext

A pointer to a KeyView Export session that you initialized by calling fpInit().

pInputStream

A pointer to the developer-assigned instance of KVInputStream. The KVInputStream structure defines the input stream containing the source for the conversion.

If pInput is defined, pFileName must be NULL. The input data can be defined as a data stream or file, but not both.

pFileName

A pointer to the file to be converted. The file must exist on the same file system as the Servant.

If pFileName is defined, pInput must be NULL. The input data can be defined as a data stream or file, but not both.

pTemplatesEx

A pointer to the KVXMLTemplate data structure. It defines the overall structure of the output. Individual elements within the structure define the markup written at specific points in the output stream. See KVXMLTemplate.

If this pointer is NULL, the default values for the structure are used.

pOptionsEx

A pointer to the KVXMLOptions data structure. It defines the options that control the markup written in response to the general style and attributes (font, color, and so on) of the document. See KVXMLOptions.

If this pointer is NULL, the default values for the structure are used.

pTOCCreateOptions

A pointer to the KVXMLTOCOptions data structure. It specifies whether a heading is included in the table of contents. See KVXMLTOCOptions.

If this pointer is NULL, the default values for the structure are used.

pPID

The address of a DWORD into which the Servant process ID is returned.

pError

A pointer to an error code defined in KVErrorCode in kverrorcodes.h.

dwOptions

Reserved for future use.

pReserved1

Reserved for future use.

pReserved2

Reserved for future use.

Returns

  • If the call is successful, the return value is TRUE.

  • If the call is unsuccessful, the return value is FALSE.

Discussion

  • After the out-of-process session is started successfully, all conversion functions can be called. The data is then processed on the Servant until the session is terminated by a call to KVXMLEndOOPSession().

  • All functions that can run out-of-process must be called within the out-of-process session, that is, after the call to KVXMLStartOOPSession(), and before the call to KVXMLEndOOPSession().

  • The KVXMLConvertFile(), and fpGetSummary() functions can be called only once in a single out-of-process session.

  • Because the KVXMLTemplate, KVXMLOptions, and KVXMLTOCOptions data structures are passed by this function, the same pointers in the call to KVXMLConvertFile() are ignored.

  • On Windows, pFileName must be in the local Windows code page.

Example

The following sample code is from the cnv2xmloop sample program:

/* declare OOP startsession function pointer */
BOOL (pascal *fpKVXMLStartOOPSession)( void     *,
                KVInputStream      *,
                char               *,
                KVXMLTemplate      *,
                KVXMLOptions       *,
                KVXMLTOCOptions    *,
                DWORD              *,
                KVErrorCode        *,
                DWORD               ,
                void               *,
                void               * ); 
/* assign OOP startsession function pointer */
fpKVXMLStartOOPSession = (BOOL (pascal *)( void      *,
                KVInputStream       *,
                char                *,
                KVXMLTemplate       *,
                KVXMLOptions        *,
                KVXMLTOCOptions     *,
                DWORD               *,
                KVErrorCode         *,
                DWORD                ,
                void                *,
                void                * ))mpGetProcAddress(hKVXML, "KVXMLStartOOPSession");
if(!fpKVXMLStartOOPSession)
{
   printf("Error assigning KVXMLStartOOPSession() pointer\n");
   (*KVXMLInt.fpFileToInputStreamFree)(pKVXML, &Input);
   (*KVXMLInt.fpFileToOutputStreamFree)(pKVXML, &Output);
   mpFreeLibrary(hKVXML);
   return 7;
}
/********START OOP SESSION *****************/
if(!(*fpKVXMLStartOOPSession)(pKVXML,
        &Input,
        NULL,
        &XMLTemplates,        /* Markup and related variables */
        &XMLOptions,          /* Options */
        NULL,                 /* TOC options */
        &oopServantPID,
        &error,
        0,
        NULL,
        NULL))
{
   printf("Error calling fpKVXMLStartOOPSession \n");
   (*KVXMLInt.fpFileToInputStreamFree)(pKVXML, &Input);
   (*KVXMLInt.fpFileToOutputStreamFree)(pKVXML, &Output);
   (*KVXMLInt.fpShutDown)(pKVXML);
   mpFreeLibrary(hKVXML);
   return 9;
}