KVHTMLConvertFile()

This function is called directly and converts a source file to an output file.

Syntax

BOOL pascal KVHTMLConvertFile  (
    void                    *pContext,
    void                    *pCallingContext,
    char                    *pInFileName,
    char                    *pOutFileName,
    KVHTMLTemplateEx        *pTemplatesEx,
    KVHTMLOptionsEx         *pOptionsEx,
    KVHTMLCallbacksEx       *pCallbacksEx,
    KVHTMLTOCOptions        *pTOCCreateOptions,
    BOOL                     bIndex,
    KVErrorCode             *pError)

Arguments

pContext

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

pCallingContext

A pointer passed back to the callback functions.

pInFileName

A pointer to the input file.

pOutFileName

A pointer to the output file.

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.

pCallbacksEx

A pointer to the KVHTMLCallbacksEx data structure. It is a structure of functions that Export calls for specific, user-defined purposes. See KVHTMLCallbacksEx.

If you do not use callbacks, this can be NULL. Only the Continue() callback can be used with KVHTMLConvertFile().

pTOCCreateOptions

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

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

bIndex

Set this to TRUE to generate output with minimal markup and without images. Because the generated output is minimized to textual content, it is suitable for an indexing engine. If you set bIndex to FALSE, embedded images in a document are regenerated as separate files and stored in the output directory.

You can also set this through the bNoPictures member in the template files.

pError

A pointer to an error code if the call to KVHTMLConvertFile() fails.

Returns

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

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

Discussion

  • Only pContext, pInFileName, pOutFileName, and bIndex are required. All other pointers should be NULL when they are not set.

  • If pCallbacksEx is NULL, pOptionsEx->pszDefaultOutputDirectory must be valid, except when you set bIndex to TRUE.

  • This function runs in-process or out of process. See Convert Files Out of Process.

  • When converting out of process, this function must be called after the call to KVHTMLStartOOPSession() and before the call to KVHTMLEndOOPSession(). See KVHTMLStartOOPSession() and KVHTMLEndOOPSession().

  • When converting out of process, the values for the KVHTMLTemplateEx, KVHTMLOptionsEx, and KVHTMLTOCOptions structures should be set to NULL. These structures are already passed in the call to KVHTMLStartOOPSession(). SeeKVHTMLStartOOPSession().

  • On Windows, pInFileName and pOutFileName must be in the local Windows code page.

Example

if(!(*KVHTMLInt.KVHTMLConvertFile)(
             pKVHTML,        /* A pointer returned by fpInit()   */
             NULL,           /* A pointer for callback functions */
             &InputFile,     /* Input file                   */
             &OutputFile,    /* Output file                  */
             &HTMLTemplates, /* Markup and related variables  */
             &HTMLOptions,   /* Options                        */
             NULL,           /* A pointer to callback functions  */
             NULL,           /* TOC options                    */
             FALSE,          /* Index mode                     */
             &error))        /* The error return value             */
{
   printf("Error converting %s to HTML %d\n", argv[i - 1], error);
}
else
{
   printf("Conversion of %s to HTML completed.\n\n", argv[i - 1]);
}