Use the C-Language Implementation of the API

The C-language implementation of the API is divided into the following function suites:

Input/Output Operations

In the Export API, the source input and target output can be either a physical file accessed through a file path, or a stream created from a data source. A stream is a C structure that contains pointers to I/O functions similar in nature to their standard ANSI C counterparts. This structure is passed to Export functions in place of the standard input source. See KVInputStream and KVOutputStream.

You can create an input stream either by using the fpFileToInputStreamCreate() function, or by using code similar to the example code in the io_samp sample program. You can create an output stream by using the fpFileToOutputStreamCreate() function. These functions assign C equivalent I/O functions to fpOpen(), fpRead(), fpSeek(), fpTell(), and fpClose(). See fpFileToInputStreamCreate() and fpFileToOutputStreamCreate().

Convert Files

To use the C-language implementation of the API

  1. Develop the XML markup and tokens to be assigned to the required members of a declared instance of KVXMLTemplate.

    If you use markup in the structure that is not compliant with XML standards, XML Export inserts the markup into the output file unchanged. This might result in a malformed XML file.

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

    KVXMLTemplateEx
    KVXMLOptions
    KVXMLHeadingInfo
    KVXMLTOCOptions

    See XML Export API Structures for more information.

  3. Load the KVXML library and obtain the KVXMLInterface entry point by calling KVXMLInterface. See KVXMLGetInterface().

  4. Initialize an Export session by calling fpInit() or fpInitWithLicenseData(). The function's return value, pContext, is passed as the first argument to all other Export functions. See fpInit() or fpInitWithLicenseData().

  5. Pass the context pointer from fpInit() or fpInitWithLicenseData() and the address of a structure containing pointers to the File Extraction API functions in the call to KVGetExtractInterface(). See. KVGetExtractInterface().

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

    1. Create an input stream (KVInputStream) either by calling fpFileToInputStreamCreate(), or by using code similar to the example code in the io_samp sample program. fpFileToInputStreamCreate().

    2. Create an output stream (KVOutputStream) either by calling fpFileToOutputStreamCreate(), or by using code similar to the example code in the io_samp sample program. fpFileToOutputStreamCreate().

    3. Proceed to Step 7.

  7. Declare the input stream or file name in the KVOpenFileArg structure. See KVOpenFileArg.

  8. Open the source file by calling fpOpenFile() and passing the KVOpenFileArg structure. This call defines the parameters necessary to open a file for extraction. See fpOpenFile().

  9. Determine whether the source file is a container file (contains subfiles) by calling fpGetMainFileInfo(). See fpGetMainFileInfo().

  10. If the call to fpGetMainFileInfo() determined the source file is a container file, proceed to Step 11; otherwise, proceed to Step 14.

  11. Determine whether the subfile is itself a container (contains subfiles) by calling fpGetSubFileInfo(). See fpGetSubFileInfo().

  12. Extract the subfile by calling fpExtractSubFile(). See fpExtractSubFile().

  13. If the call to fpGetSubFileInfo() determined the subfile is a container file, repeat Step 6 through Step 12 until all subfiles are extracted; otherwise, proceed to Step 14.

  14. Setup an out-of-process session by calling KVXMLStartOOPSession(). See KVXMLStartOOPSession().

  15. Convert the input and generate the output files by calling KVXMLConvertFile() or fpConvertStream(). The structures KVXMLTemplate, KVXMLOptions, and KVXMLTOCOptions are defined in the call to KVXMLStartOOPSession(), and should be NULL in the conversion call. A conversion function can be called only once in a single out-of-process session. See fpConvertStream() or KVXMLConvertFile().

    If you are using callbacks, they are called while the conversion process is underway. If required, you can specify alternate paths and file names for output files, including using the table of content entries for the file names. See XML Export API Callback Functions.

  16. If you are converting additional files, terminate the out-of-process session by calling KVXMLEndOOPSession() and setting the Boolean to TRUE. The Servant ends the current conversion session, and releases the source data and session resources.

    If you are not converting additional files, terminate the out-of-process session and the Servant process by calling KVXMLEndOOPSession() and setting the Boolean to FALSE. KVXMLEndOOPSession()

  17. Close the file by calling fpCloseFile(). See fpCloseFile().

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

  19. Repeat Step 6 through Step 18 for additional source files.

  20. Shutdown the Export session by calling fpShutDown(). See fpShutDown().

Multithreaded Conversions

To ensure that multithreaded conversions are thread-safe, you must create a unique context pointer for every thread by initializing the Export session with fpInit() or fpInitWithLicenseData(). In addition, threads must not share context pointers, and the same context pointer must be used for all API calls in the same thread. Creating a context pointer for every thread does not affect performance because the context pointer uses minimal resources.

For example, your code should have the following logic for one thread:

fpInit()
   KVGetExtractInterface()
   fpFileToInputStreamCreate()
   fpFileToOutputStreamCreate()
      fpOpenFile()
      fpGetMainFileInfo()         /* container file */
      fpGetSubFileInfo()
      fpExtractSubFile
      fpGetSubFileMetadata()
      KVXMLStartOOPSession()
      fpConvertStream()
      KVXMLEndOOPSession(bKeepServantAlive TRUE)
      fpCloseFile()
   fpFileToInputSreamFree()
   fpFileToOutputStreamFree()
      set input/output file
      fpOpenFile()
      fpGetMainFileInfo()           /* not a container file */
      KVXMLStartOOPSession()
      KVXMLConvertFile()
      KVXMLEndOOPSession(bKeepServantAlive TRUE)
      fpCloseFile()
   ...
fpShutdown()