Export Functions

This chapter outlines the basic functions used to initiate the conversion of documents using the Web View Export SDK.

This chapter includes the following sections:

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.

EXAddKeyValue Functions

These functions specify key/value pairs for use in the exported document.

SCCERR EXAddKeyValueString( HEXPORT hExport, VTLPCSTR szKeyName, VTLPCSTR szValue )
SCCERR EXAddKeyValueInt( HEXPORT hExport, VTLPCSTR szKeyName, VTDWORD dwValue)
SCCERR EXAddKeyValueFloat( HEXPORT hExport, VTLPCSTR szKeyName, VTFLOAT fValue )

These functions are being added to Outside In 8.5.0 for the use of the Web View Export product. They may in the future be used in other SDKs. A given key name cannot have multiple values. Calling this function multiple times with the same value for szKeyName will replace each previous value with the newest one.

Parameters

Return Values

Use in Web View Export Output

The data specified by this method will be made available to scripts that have access to the Web View Export Javascript API. For a script operating within a web view, the data specified will be accessible through an object returned from the API function OIT.document.externalData().

For example, if at export time the export SDK is called like this:

EXAddKeyValueInt( hExport, (VTLPCSTR)"UserId", 42 );
EXAddKeyValueString( hExport, (VTLPCSTR)"UserName", (VTLPCSTR)"Bob" );
EXAddKeyValueFloat( hExport, (VTLPCSTR)"Pie", 3.14159 );

Then from a script that is loaded into the Web View Export output, the following is possible:

var myData = OIT.document.externalData();

alert( myData.UserId ); // displays "42"
alert( myData["UserName"] ); // displays "Bob"
alert( myData.Pie ); // displays "3.14159"

Annotation Functions

Annotations are a way to highlight, insert, or delete text in product output, without modifying the original document.

This section covers the following annotation functions:

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 Web View Export. Contact your sales representative for more information.

The following notes should be considered when using annotations:

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

EXHiliteTextEx

DAERR EXHiliteTextEx( VTHEXPORT hExport, PEXANNOHILITETEXT pHilite, 
         VTLPDWORD pHiliteId )

This function is the same as EXHiliteText, but allows for a highlight id to be obtained, so that highlight properties or a text comment can be attached to this highlight. (This function was called EXHiliteAnchorText in earlier specifications)

EXHiliteArea

DAERR EXHiliteArea( VTHEXPORT hExport, PEXANNOHILITEAREA pHilite, 
         VTLPDWORD pHiliteId)

This function applies an area highlight to the export. The highlight is defined through the following data structure.

EXANNOHILITEAREA

typedef struct EXANNOHILITEAREA
{
  VTDWORD    dwSize;
  VTDWORD    dwSection;         // zero based number of (sheet/image/slide)
  VTDWORD    dwTop;             // Top coordinate or row
  VTDWORD    dwLeft;            // Leftmost coordinate or column
  VTDWORD    dwWidth;           // Width of area in coordinates or columns
  VTDWORD    dwHeight;          // Height of area in coordinates or columns
  VTDWORD    dwUnits;           // SCCANNO_TWIPS, SCCANNO_PIXELS or SCCANNO_CELLS
  VTDWORD    dwUser;            // User data
 
  SCCVWCOLORREF fillColor;      // Fill color
  VTFLOAT    fOpacity;          // 0-1.0; 0==invisible; applies to fill color * 
 
  SCCVWCOLORREF borderTopColor;      // Border Colors and thickness in twips *
  VTDWORD       borderTopThickness; 
  SCCVWCOLORREF borderLeftColor;    
  VTDWORD       borderLeftThickness; 
  SCCVWCOLORREF borderBottomColor;    
  VTDWORD       borderBottomThickness; 
  SCCVWCOLORREF borderRightColor;    
  VTDWORD       borderRightThickness; 
  
  VTDWORD       dwBorderStyle;      // Currently not supported 
                                    // (would be SCCVW_BORDER_DOT, SCCVW_BORDER_DASH, or SCCVWBORDER_SOLID)
 
} EXANNOHILITEAREA;

EXAddStampAnnotation

DAERR EXAddStampAnnotation( VTHEXPORT hExport, PEXANNOSTAMP pStamp
         VTLPDWORD pHiliteId)

This function applies an image stamp to the export output. The stamp is defined through the following data structure.

EXANNOSTAMP

typedef struct EXANNOSTAMP *
{
  VTDWORD    dwSize;
  VTDWORD    dwUser;            // User data
  VTDWORD    dwSection;         // zero based number of (page/sheet/image/slide)
  VTDWORD    dwTop;             // Top coordinate or row
  VTDWORD    dwLeft;            // Leftmost coordinate or column
  VTDWORD    dwWidth;           // Width of area in coordinates or columns
  VTDWORD    dwHeight;          // Height of area in coordinates or columns
  VTDWORD    dwUnits;           // EX_ANNO_TWIPS, EX_ANNO_PIXELS or EX_ANNO_CELLS
  VTFLOAT    fOpacity;          // 0-1.0; 0==invisible 
 
  DWORD      dwSizeMode;        // EX_ANNO_SIZE_FIT, EX_ANNO_SIZE_STRETCH, 
                                // EX_ANNO_SIZE_FROM_SOURCE;
  VTLPCSTR   szStampName;       // name of stamp image, specified via one of
                                // the SCCOPT_STAMP_IMAGE_* options  
 
} EXANNOSTAMP;
Notes

For word processing files, the dwSection parameter indicates the zero-based index of the page of the output document to which the stamp should be applied. Note that the usual caveats apply to paginated output. Pagination is influenced by how text is wrapped on a page, which is in turn influenced by the fonts that are available to the Outside In rendering code on the system that is generating the output. Exporting the same document on two different systems with different fonts available to them may result in slightly different page boundaries.

About the dwSizeMode parameter:

EXAddComment

DAERR EXAddComment( VTHEXPORT hExport, VTDWORD dwHighlightId, VTLPCWSTR pComment )

This function adds a comment associated with a previously applied highlight annotation. If a comment was previously defined for the highlight, it is replaced by the new comment.

EXAddHiliteProperty

DAERR EXAddHiliteProperty( HEXPORT hExport, DWORD dwAnchorId, VTLPCWSTR wsName, VTLPCWSTR sValue )

Note: This method associates a property with a highlight. The property is specified as a Unicode (UCS2) name/value pair.

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

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

Prototype

DAERR EXRedactText( VTHEXPORT hExport, 
   PEXANNOREDACTTEXT pRedaction )

Parameters

Structure

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

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