Export Functions

This chapter outlines the basic functions used to initiate the conversion of documents using the product API.

This chapter covers the following types of functions:

Parent topic: Using the C/C++ API

General Functions

The following functions are general functions used in most export products.

This section includes the following functions:

EXOpenExport

This function is used to initiate the export process for a file that has been opened by DAOpenDocument. If EXOpenExport succeeds, EXCloseExport must be called regardless of any other API calls.

Note:

SCCOPT_GRAPHIC_TYPE = FI_NONE must be set (via DASetOption) before the call to EXOpenExport. Otherwise, the SCCUT_FILTEROPTIMIZEDFORTEXT speed enhancement for the PDF filter is not set. This will result in slower exports of PDFs when graphic output is not required.

Prototype

SCCERR EXOpenExport(
   VTHDOC        hDoc,
   VTDWORD       dwOutputId,
   VTDWORD       dwSpecType,
   VTLPVOID       pSpec,
   VTDWORD        dwFlags,
   VTSYSPARAM     dwReserved,
   EXCALLBACKPROC pCallbackFunc,
   VTSYSPARAM    dwCallbackData,
   VTLPHEXPORT  phExport);

Parameters

Return Values

EXCALLBACKPROC

Type definition for the developer’s callback function.

Prototype

DAERR (DA_ENTRYMODPTR EXCALLBACKPROC)(
   VTHEXPORT    hExport,
   VTSYSPARAM   dwCallbackData,
   VTDWORD      dwCommandOrInfoId,
   VTLPVOID     pCommandOrInfoData);

Parameters

Return Values

EXCloseExport

This function is called to terminate the export process for a file.

Prototype

SCCERR EXCloseExport(
   VTHEXPORT   hExport);

Parameters

Return Values

EXRunExport

This function is called to run the export process.

Prototype

SCCERR EXRunExport(
   VTHEXPORT   hExport);

Parameters

Return Values

EXExportStatus

This function is used to determine if there were conversion problems during an export. It returns a structure that describes areas of a conversion that may not have high fidelity with the original document.

Prototype

SCCERR EXExportStatus(VTHEXPORT hExport, VTDWORD dwStatusType, VTLPVOID pStatus)

Parameters

Return Values

SCCERR_OK: Returned if there were no problems. Otherwise, one of the other SCCERR_ values in sccerr.h is returned.

EXSUBDOCSTATUS Structure

The EXSUBDOCSTATUS structure is defined as follows:

typedef struct EXSUBDOCSTATUStag
{
VTDWORD dwSize;      /* size of this structure */
VTDWORD dwSucceeded; /* number of sub documents that were converted */
VTDWORD dwFailed;    /* number of sub documents that were not converted */
} EXSUBDOCSTATUS;

EXSTATUSINFORMATION Structure

The EXSTATUSINFORMATION structure is defined as follows:

typedef struct EXSTATUSINFORMATIONtag
{    
   VTDWORD dwVersion;              /* version of this structure */    
   VTBOOL bMissingMap;             /* a PDF text run was missing the toUnicode table */    
   VTBOOL bVerticalText;           /* a vertical text run was present */    
   VTBOOL bTextEffects;            /* a run that had unsupported text effects applied.  One example is Word Art */    
   VTBOOL bUnsupportedCompression; /* a graphic had an unsupported compression */    
   VTBOOL bUnsupportedColorSpace;  /* a graphic had an unsupported color space */    
   VTBOOL bForms;                  /* a sub documents had forms */    
   VTBOOL bRightToLeftTables;      /* a table had right to left columns */    
   VTBOOL bEquations;              /* a file had equations */    
   VTBOOL bAliasedFont;            /* The desired font was missing, but a font alias was used*/    
   VTBOOL bMissingFont;            /* The desired font wasn't present on the system */    
   VTBOOL bSubDocFailed;           /* a sub document was not converted */    
   VTBOOL bTypeThreeFont;          /* a PDF Type 3 embedded font was encountered */    
   VTBOOL bUnsupportedShading;     /* a PDF input file had an unsupported shading type */    
   VTBOOL bInvalidHTML;            /* invalid HTML was encountered */    
   VTBOOL bVectorObjectLimit;      /* The vector object limit was reached */    
   VTBOOL bInvalidAnnotationNotApplied;    /* Annotation/Redaction wasn't displayed */    
   VTBOOL bInlineImageFound;       /* An inline image was found and may not have been rendered */    
   VTBOOL bIncorrectPageSize;      /* a PDF file was larger than 200 in x 200 in, as specified in the PDF reference guide */    
   VTBOOL bIncorrectPageSize_lower;/* a PDF file was smaller than 3 units x 3 units, as specified in the PDF reference guide */    
   VTBOOL bPDFOneToMany;           /* A PDF input file contained an embedded font with a ToUnicode table which maps one Unicode value to multiple glyphs */    
   VTBOOL bIsBidi;                 /* a PDF file contains Bi-Directional Text*/    
   VTBOOL bUnsupportedFont;        /* an unsupported font was encountered */    
   VTDWORD currPathSize, maxPathLimit; // Current size of the paths seen, Max number of Paths allowed    
   VTDWORD currVectSize, maxVectLimit; // Current size of the Vectors seen, Max number of Vectors allowed    
   VTDWORD currObjtSize, maxObjtLimit; // Current size of the Objects seen, Max number of Objects allowed    
   VTBOOL bFontWidthUsed;          /* a PDF file is using Width parameter to change widths of glyphs */
} EXSTATUSINFORMATION;

#define EXSTATUSVERSION1 0X0001

#define EXSTATUSVERSION2 0X0002

Note:

When processing the main document, Search Export, HTML Export, and XML Export never use fonts, so bAliasedFont and bMissingFont will never report TRUE; however, when doing graphics conversions XML Export and HTML Export may use fonts, so bAliasedFont and bMissingFont may report TRUE.

bVectorObjectLimit applies only to WebView Export, and bInvalidAnnotationNotApplied applies only to Image Export, PDF Export, and Web View Export.

Annotation Functions

Annotations are a way to highlight, insert, or delete text in product output, without modifying the original document. Examples of ways annotations can be used by developers include:

Other Oracle Outside In products are required to ascertain the proper character positions where the developer wishes to make annotations. Currently, only Content Access and the SearchML output format (available in Search Export) can be used to get these positions. Although the Content Access module is included with the product, license to use the Content Access API is not automatically granted with the purchase of the Export software.

A separate license for Content Access or Search Export is required to enable use of any of the annotation features that are supported by PDF Export. Contact your sales representative for more information.

The following notes should be considered when using annotations:

This section includes the following functions:

EXHiliteText

This function allows the developer to change foreground and background colors of a range of characters from the input document.

The colors set by this option can be overridden by the equivalent settings in the ExInsertText function.

Prototype

DAERR EXHiliteText(
VTHEXPORT           hExport,
PEXANNOHILITETEXT   pHiliteText);

Parameters

Structure

A C data structure defined in sccex.h as follows:

typedef struct EXANNOHILITETEXTtag
  {    
     VTDWORD         dwSize;    
     VTDWORD         dwStartACC;    
     VTDWORD         dwEndACC; /* Last char to highlight +1 */    
     VTLPBYTE        pBookmark;    
     VTLPBYTE        pHyperlink;    
     VTDWORD         dwOptions;    
     SCCVWCOLORREF   sForeground;    
     SCCVWCOLORREF   sBackground;    
     VTWORD          wCharAttr;    
     VTWORD          wCharAttrMask;
  } EXANNOHILITETEXT, *PEXANNOHILITETEXT;

Return Values

EXInsertText

This function inserts a text string at a specified point in the document. The developer may also change character attributes or foreground or background colors. These settings override any provided by ExHiliteText.

Prototype

DAERR EXInsertText(
VTHEXPORT           hExport,
PEXANNOINSERTTEXT   pInsertText);

Parameters

Structure

A C data structure defined in sccex.h as follows:

typedef struct EXANNOINSERTTEXTtag
{
   VTDWORD         dwSize;
   VTDWORD         dwTextACC;
   VTLPWORD        pText;
   VTLPBYTE        pBookmark;    
   VTLPBYTE        pHyperlink;
   VTDWORD         dwOptions;
   SCCVWCOLORREF   sForeground;
   SCCVWCOLORREF   sBackground;
   VTWORD          wCharAttr;
   VTWORD          wCharAttrMask;
} EXANNOINSERTTEXT, *PEXANNOINSERTTEXT;

Return Values

EXHideText

This function removes the selected range of characters in the input document from the output.

The hidden text does not appear in any form in the final converted document.

Prototype

SCCERR EXHideText(
VTHEXPORT         hExport,
PEXANNOHIDETEXT   pHideText)

Parameters

EXANNOHIDETEXT Structure

A C data structure defined in sccex.h as follows:

typedef struct EXANNOHIDETEXTtag
{
   VTDWORD    dwSize;
   VTDWORD    dwStartACC;
   VTDWORD    dwEndACC;     /* Last char to hide +1 */
   VTLPBYTE   pBookmark; /* HTML Export Only */
} EXANNOHIDETEXT, *PEXANNOHIDETEXT;
Return Values

EXApplyHilites

DAERR EXApplyHilites(HEXPORT hExport, const VTBYTE * pHilites);

This function applies a set of highlights from a JSON-encoded text stream previously generated from the Web View Export Javascript library. This function may be called multiple times with different sets of highlights.

EXRedactText

This is an API call to redact text.

Prototype

EXRedactTest
DAERR EXRedactText( VTHEXPORT hExport,
   PEXAANNOREDACTTEXT pRedaction )

Similar to EXHiliteText, this accepts a data structure that defines the redaction.

typedef struct EXANNOREDACTTEXTtag
{
  VTDWORD         dwSize;
  VTDWORD         dwStartACC;
  VTDWORD         dwEndACC;     /* Last char to highlight +1 */
  VTWCHAR         dwLabel[EXANNO_MAXLABEL];
} EXANNOREDACTTEXT;