Run Export Out of Process

The cnv2htmloop sample program demonstrates how to run Export out of process.

To convert files out of process in the C API

  1. If required, set parameters for the out-of-process conversion in the formats_e.ini file. See Configure Out-of-Process Conversions.

  2. Declare instances of the following types and assign values to the members as required:

    KVHTMLTemplateEx
    KVHTMLOptionsEx
    KVHTMLHeadingInfo
    KVHTMLTOCOptions

    See HTML Export API Structures for more information.

  3. Load the KVHTML library and obtain the KVHTMLInterfaceEx entry point by calling KVHTMLGetInterfaceEx().

    See KVHTMLGetInterfaceEx().

  4. Initialize an Export session by calling fpInit() or fpInitWithLicenseData(). See fpInit() or fpInitWithLicenseData().

  5. If you are using streams for the input and output source, follow these steps; otherwise, proceed to Step 6:

    1. Create an input stream (KVInputStream) by calling fpFileToInputStreamCreate(). See fpFileToInputStreamCreate().

    2. Create an output stream (KVOutputStream) by calling fpFileToOutputStreamCreate(). See fpFileToOutputStreamCreate().

    3. Proceed to Step 6.

  6. Set up an out-of-process session by calling KVHTMLStartOOPSession().

    See KVHTMLStartOOPSession(). This function performs the following:

    • Initializes the out-of-process session.

    • Specifies the input stream or file. If you are using an input file, set pFileName to the file name, and set pInputStream to NULL. If you are using an input stream, set pInputStream to point to KVInputStream, and set pFileName to NULL.

    • 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.

      See the sample code in Example—KVHTMLStartOOPSession, and KVHTMLStartOOPSession().

  7. Convert the input and generate the output files by calling KVHTMLConvertFile() or fpConvertStream(). The KVHTMLTemplateEx, KVHTMLOptionsEx, and KVHTMLTOCOptions structures are passed in the call to KVHTMLStartOOPSession(), and should be NULL in the conversion call. A conversion function can be called only once in a single out-of-process session. See KVHTMLConvertFile(), and fpConvertStream().

  8. Terminate the out-of-process session by calling KVHTMLEndOOPSession(). The Servant ends the current conversion session, and releases the source data and session resources. See sample code in Example—KVHTMLEndOOPSession, and KVHTMLEndOOPSession().

  9. If you used streams, free the memory allocated for the input stream and output stream by calling the fpFileToInputSreamFree() and fpFileToOutputStreamFree() functions. See fpFileToInputStreamFree() and fpFileToOutputStreamFree().

  10. Repeat Step 5 to Step 9 for additional files.

  11. After all files are converted, terminate the out-of-process session and the Servant process by calling KVHTMLEndOOPSession() and setting the Boolean to FALSE.

  12. After the out-of-process session and Servant are terminated, shut down the Export session by calling fpShutDown(). See fpShutDown().

Example—KVHTMLStartOOPSession

The following sample code is from the cnv2htmloop sample program:

/* declare OOP startsession function pointer */
KVHTML_START_OOP_SESSION fpKVHTMLStartOOPSession;
/* assign OOP startsession function pointer */
fpKVHTMLStartOOPSession = (KVHTML_START_OOP_SESSION)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.fpShutDown)(pKVHTML);
   mpFreeLibrary(hKVHTML);
   return 9;    
}

Example—KVHTMLEndOOPSession

The following sample code is from the cnv2htmloop sample program:

/* declare endsession function pointer */
KVHTML_END_OOP_SESSION   fpKVHTMLEndOOPSession;
/* assign OOP endsession function pointer */
fpKVHTMLEndOOPSession = (KVHTML_END_OOP_SESSION)mpGetProcAddress
                        (hKVHTML, "KVHTMLEndOOPSession");
   if(!fpKVHTMLEndOOPSession)
   {
      printf("Error assigning KVHTMLEndOOPSession pointer\n");
      (*KVHTMLInt.fpFileToInputStreamFree)(pKVHTML, &Input);
      (*KVHTMLInt.fpFileToOutputStreamFree)(pKVHTML, &Output);
      mpFreeLibrary(hKVHTML);
      return 8;
   }
/********END OOP SESSION, DO NOT KEEP SERVANT ALIVE *********/
if(!(*fpKVHTMLEndOOPSession)(pKVHTML,
        FALSE,
        &error,
        0,
        NULL,
        NULL))
{
   printf("Error calling fpKVHTMLEndOOPSession \n");
   (*KVHTMLInt.fpShutDown)(pKVHTML);
   mpFreeLibrary(hKVHTML);
   return 10;
}