# 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 returned from fpInit() or fpInitWithLicenseData().
`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;
    }

_FT_HTML5_bannerTitle.htm