KVHTMLStartOOPSession()

This function performs the following:

  • Initializes the out-of-process session.

  • Specifies the input stream or file.

  • Passes conversion options from the KVHTMLTemplateEx, KVHTMLOptionsEx, and KVHTMLTOCOptions 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 KVHTMLStartOOPSession(
    void                *pContext,
    KVInputStream       *pInputStream,
    char                *pFileName,
    KVHTMLTemplateEx    *pTemplatesEx,
    KVHTMLOptionsEx     *pOptionsEx,
    KVHTMLTOCOptions    *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, then 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, then pInput must be NULL. The input data can be defined as a data stream or file, but not both.

pTemplatesEx

A pointer to the KVHTMLTemplateEx 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 KVHTMLTemplateEx.

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

pOptionsEx

A pointer to the KVHTMLOptionsEx 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 KVHTMLOptionsEx.

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

pTOCCreateOptions

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

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

pPID

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 KVHTMLEndOOPSession().
  • All functions that can run out-of-process must be called within the out-of-process session, that is, after the call to KVHTMLStartOOPSession(), and before the call to KVHTMLEndOOPSession().
  • The KVHTMLConvertFile() function can only be called once in a single out-of-process session.
  • Since the KVHTMLTemplateEx, KVHTMLOptionsEx, and KVHTMLTOCOptions data structures are passed by this function, the same pointers in the call to KVHTMLConvertFile() are ignored.
  • On Windows, pFileName must be in the local Windows code page.

Example

The following sample code is from the cnv2htmloop sample program:

/* declare OOP startsession function pointer */
BOOL (pascal *fpKVHTMLStartOOPSession)( void     *,
                KVInputStream      *,
                char               *,
                KVHTMLTemplateEx   *,
                KVHTMLOptionsEx    *,
                KVHTMLTOCOptions   *,
                DWORD              *,
                KVErrorCode        *,
                DWORD               ,
                void               *,
                void               * ); 
/* assign OOP startsession function pointer */
fpKVHTMLStartOOPSession = (BOOL (pascal *)( void      *,
                KVInputStream       *,
                char                *,
                KVHTMLTemplateEx    *,
                KVHTMLOptionsEx     *,
                KVHTMLTOCOptions    *,
                DWORD               *,
                KVErrorCode         *,
                DWORD                ,
                void                *,
                void                * ))mpGetProcAddress(hKVHTML, "KVHTMLStartOOPSession");
if(!fpKVHTMLStartOOPSession)
{
   printf("Error assigning KVHTMLStartOOPSession() pointer\n");
   (*KVHTMLInt.fpFileToInputStreamFree)(pKVHTML, &Input);
   (*KVHTMLInt.fpFileToOutputStreamFree)(pKVHTML, &Output);
   mpFreeLibrary(hKVHTML);
   return 7;
}
/********START OOP SESSION *****************/
if(!(*fpKVHTMLStartOOPSession)(pKVHTML,
        &Input,
        NULL,
        &HTMLTemplates,        /* Markup and related variables */
        &HTMLOptions,          /* Options */
        NULL,                 /* TOC options */
        &oopServantPID,
        &error,
        0,
        NULL,
        NULL))
{
   printf("Error calling fpKVHTMLStartOOPSession \n");
   (*KVHTMLInt.fpFileToInputStreamFree)(pKVHTML, &Input);
   (*KVHTMLInt.fpFileToOutputStreamFree)(pKVHTML, &Output);
   (*KVHTMLInt.fpShutDown)(pKVHTML);
   mpFreeLibrary(hKVHTML);
   return 9;
}