Export Functions

7 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:

7.1 General Functions

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

This section includes the following functions:

7.1.1 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,
   VTLPVOID     pCallbackFunc,
   VTSYSPARAM   dwCallbackData,
   VTLPHEXPORT  phExport);

Parameters

hDoc: A handle that identifies the source file, created by DAOpenDocument. Knowledge of this should only affect OEMs under the most unusual of circumstances.
dwOutputId: File ID of the desired format of the output file. This value must be set to either FI_PDF (for generic PDF 1.5), FI_PDFA (for PDF/A-1a compliance), or FI_PDFA_2 (for PDF/A-2a compliance).

Note:

For FI_PDFA exports, raster images with transparency will not be produced as transparent due to the explicit exclusion of transparency in the ISO PDF/A-1a specification document.
dwSpecType: Describes the contents of pSpec. Together, dwSpecType and pSpec describe the location of the initial output file. Must be one of the following values:
- IOTYPE_ANSIPATH: Windows only. pSpec points to a NULL-terminated full path name using the ANSI character set and FAT 8.3 (Win16) or NTFS (Win32 and Win64) file name conventions.
- IOTYPE_UNICODEPATH: Windows only. pSpec points to a NULL-terminated full path name using the Unicode character set and NTFS file name conventions.
  
  Note:
  
  If you are using IOTYPE_UNICODEPATH as a file spec type, if the calling application is providing an export callback function, you should set the option SCCOPT_EX_UNICODECALLBACKSTR to TRUE. Refer to the documentation on callbacks such as EX_CALLBACK_ID_CREATENEWFILE and the EXURLFILEIOCALLBACKDATAW structure for details
- IOTYPE_UNIXPATH: UNIX platforms only. pSpec points to a NULL-terminated full path name using the system default character set and UNIX path conventions. Unicode paths can be accessed on UNIX platforms by using a UTF-8 encoded path with IOTYPE_UNIXPATH.
- IOTYPE_REDIRECT: All platforms. pSpec may be NULL, and all file information specified in the callback routine. This allows the developer to redirect the IO routines used to write the files. For more information, see Redirected IO.
pSpec: Initial output file location specification. This is either a pointer to a buffer or NULL.

If the pointer is not NULL, the file referred to by the pSpec is assumed to be already open and the buffer's contents are based on the value of the dwSpecType parameter. See the descriptions for individual dwSpecType values in the preceding list.

Passing NULL indicates the developer will use the EX_CALLBACK_ID_CREATENEWFILE callback to specify the initial output file instead of specifying it here. When this parameter is NULL, the developer must handle the EX_CALLBACK_ID_CREATENEWFILE callback or EXOpenExport returns an error.
dwFlags: Must be set by developer to 0.
dwReserved: Reserved. Must be set by developer to 0.
pCallbackFunc: Pointer to a function of the type EXCALLBACKPROC. This function is used to give the developer control of certain aspects of the export process as they occur. For more details, see the definition for EXCALLBACKPROC in EXCALLBACKPROC. This parameter may be set to NULL if the developer does not wish to handle callbacks.
dwCallbackData: This parameter is passed transparently to the function specified by pCallbackFunc. The developer may use this value for any purpose, including passing context information into the callback function.
phExport: Pointer to a handle that receives a value uniquely identifying the document to the product routines. If the function fails, this value is set to VTHDOC_INVALID. phExport is not a file handle.

Return Values

SCCERR_OK: If the open was successful. Otherwise, one of the other SCCERR_ values in sccerr.h is returned.

7.1.2 EXCALLBACKPROC

Type definition for the developer's callback function.

Prototype

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

Parameters

hExport: Export handle for the document. Must be a handle returned by the EXOpenExport function.
dwCallbackData: This value is passed to EXOpenExport in the dwCallbackData parameter.
dwCommandOrInfoId: Indicates the type of callback. For information about supported callbacks, see Callbacks.
pCommandOrInfoData: Data associated with dwCommandOrInfoId. For information about supported callbacks, see Callbacks.

Return Values

SCCERR_OK: Command was handled by the callback function.
SCCERR_BADPARAM: One of the function parameters was invalid.
SCCERR_NOTHANDLED: Callback function did not handle the command. This return value must be the default for all values of dwCommandOrInfoId the developer does not handle.

7.1.3 EXCloseExport

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

Prototype

SCCERR EXCloseExport(
   VTHEXPORT   hExport);

Parameters

hExport: Export handle for the document. Must be a handle returned by the EXOpenExport function.

Return Values

SCCERR_OK: Returned if the close was successful. Otherwise, one of the other SCCERR_ values in sccerr.h is returned.

7.1.4 EXRunExport

This function is called to run the export process.

Prototype

SCCERR EXRunExport(
   VTHEXPORT   hExport);

Parameters

hExport: Export handle for the document. Must be a handle returned by the EXOpenExport function.

Return Values

SCCERR_OK: Returned if the export was successful. Otherwise, one of the other SCCERR_ values in sccerr.h is returned.

7.1.5 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

hExport: Export handle for the document.
dwStatusType: Specifies which status information should be filled in pStatus.
- EXSTATUS_SUBDOC – fills in the EXSUBDOCSTATUS structure (only implemented in Search Export and XML Export)
- EXSTATUS_INFORMATION - fills in the EXSTATUSINFORMATION structure.
pStatus: Either a pointer to a EXSUBDOCSTATUS or EXSTATUSINFORMATION data structure depending on the value of dwStatusType.

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;            /* unsupported text effects applied (i.e.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;            /* A 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 Type 3 Font was encountered */ 
VTBOOL bUnsupportedShading;        /* an unsupported shading pattern was encountered */ 
VTBOOL bInvalidHTML;                  /* An HTML parse error, as defined by the W3C, was encountered. */ 
VTBOOL bInvalidAnnotationNotApplied;  /* Unsupported annotation/redaction wasn't rendered */
VTBOOL bVectorObjectLimit;            /* This flag does not apply to PDF Export */
VTBOOL bInvalidAnnotationNotApplied;  /* Unsupported annotation/redaction wasn't rendered  */
} 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.

7.2 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:

highlighting search hits
inserting notes to comment on text in the original document
deleting sensitive information not intended for viewing

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:

Processing annotations slows down the conversion process to some extent.
While other products in the Oracle Outside In family support annotations, not all products support all types of annotations.
The ACC acronym (Actual Character Count) is used in the following function descriptions. ACCs represent the location of text in the source document data stream. They represent a marker just before the location of text, and this marker is zero-based.

startACC parameters should be set to an ACC value that represents the position just prior to the first character and endACC parameters should be set to an ACC value that represents the position just past the last character in the range. For this reason, users should make sure endACC values are 1 greater than the ACC of the last character in the desired range of annotation.
Calling EXCloseExport causes all annotations set so far to be cleared.

This section includes the following functions:

7.2.1 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

hExport: Export handle for the document. Must be the handle returned by the EXOpenExport() function.
pHiliteText: Pointer to a structure containing the information on what to highlight and how to highlight it.

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 */
   VTDWORD         dwOptions;
   SCCVWCOLORREF   sForeground;
   SCCVWCOLORREF   sBackground;
   VTWORD          wCharAttr;
   VTWORD          wCharAttrMask;
} EXANNOHILITETEXT;

dwSize: Must be set by the developer to sizeof(EXANNOHILITETEXT).
dwStartACC: The ACC of the first character to be highlighted.
dwEndACC: ACC of the last character to be highlighted +1. Ranges for annotations have their end point set one past the ACC of the last character in the range. For example, to highlight a single character at ACC position 5, dwStartACC would be set to 5, and dwEndACC would be set to 5+1=6.
dwOptions: Flags that provide highlight options. The default is all flags set to off. The valid flags are:
- SCCVW_USEFOREGROUND: Indicates that sForeground defines the foreground text color to apply to highlights.
- SCCVW_USEBACKGROUND: Indicates that sBackground defines the background text color to apply to highlights.
- SCCVW_USECHARATTR: Indicates that wCharAttr defines the character attributes to apply to highlights.
- sForeground: Defines the foreground text color to be used if the SCCVW_USEFOREGROUND flag is set in dwOptions. Set this value with the SCCANNORGB(red, green, blue) macro. The red, green and blue values are percentages of the color from 0-255 (with 255 being 100%). There is no default value for this parameter -- if it is set, the color must be specified.
- sBackground: Defines the background text color to be used if the SCCVW_USEBACKGROUND flag is set in dwOptions. Set this value with the SCCANNORGB(red, green, blue) macro. The red, green and blue values are percentages of the color from 0-255 (with 255 being 100%). There is no default value for this parameter. If it is set, the color must be specified.
- wCharAttr: Defines the character attributes to use if SCCVW_USECHARATTR is set in dwOptions. Only bits with the corresponding bits set in wCharAttrMask are affected. To turn off all character attributes, set this to SCCVW_CHARATTR_NORMAL (the default) and set wCharAttrMask to -1. Otherwise, set this to any of the following character attributes OR-ed together:
  - SCCVW_CHARATTR_UNDERLINE
  - SCCVW_CHARATTR_ITALIC
  - SCCVW_CHARATTR_BOLD
  - SCCVW_CHARATTR_STRIKEOUT
  - SCCVW_CHARATTR_SMALLCAPS: Not supported in PDF Export.
  - SCCVW_CHARATTR_OUTLINE: Not currently supported.
  - SCCVW_CHARATTR_SHADOW: Not currently supported.
  - SCCVW_CHARATTR_CAPS: Not currently supported.
  - SCCVW_CHARATTR_SUBSCRIPT
  - SCCVW_CHARATTR_SUPERSCRIPT
  - SCCVW_CHARATTR_DUNDERLINE
  - SCCVW_CHARATTR_WORDUNDERLINE
  - SCCVW_CHARATTR_DOTUNDERLINE: Currently supported as single underline.
wCharAttrMask: Defines which character attributes to change based on the settings of the bits in wCharAttr. Uses the same bit flags defined above for wCharAttr. Only attributes whose flag is set in this mask are modified to match the state specified by wCharAttr. This mask provides a way to distinguish between bits being set in wCharAttr because the developer wants to force a change to the character attributes and bits in wCharAttr that the developer would rather set to "inherit from the source document." The following are real-world examples of these interactions (all examples assume that SCCVW_USECHARATTR is set in dwOptions):
- Example 1: wCharAttr is set to SCCVW_CHARATTR_BOLD and wCharAttrMask is set to SCCVW_CHARATTR_BOLD. This results in bold being forced on in the annotation.
- Example 2: wCharAttr is set to SCCVW_CHARATTR_BOLD and wCharAttrMask is set to 0. This results in bold being left the way it was in the source document in the annotation.
- Example 3: wCharAttr is set to 0 and wCharAttrMask is set to SCCVW_CHARATTR_BOLD. This results in bold being forced off in the annotation.
  
  The default value for this is 0, meaning that all the flags in wCharAttr are ignored.

Return Values

DAERR_OK: Returned if the annotation was successfully added. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.

7.2.2 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

hExport: Export handle for the document. Must be the handle returned by the EXOpenExport() function.
pInsertText: Pointer to a structure containing the information on the text to insert.

Structure

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

typedef struct EXANNOINSERTTEXTtag
{
   VTDWORD         dwSize;
   VTDWORD         dwTextACC;
   VTLPWORD        pText;
   VTDWORD         dwOptions;
   SCCVWCOLORREF   sForeground;
   SCCVWCOLORREF   sBackground;
   VTWORD          wCharAttr;
   VTWORD          wCharAttrMask;
} EXANNOINSERTTEXT;

dwSize: Must be set by the OEM to sizeof(EXANNOINSERTTEXT).
dwTextACC: Place to insert the string pointed to by pText. The string is inserted before the character normally at this ACC position. By default, the inserted string inherits the text attributes of the character at this position in the input document.
pText: The text to be inserted. Specified as a Unicode string.
dwOptions: This parameter sets flags that provide highlight options. The default is all flags off. The flags are:
- SCCVW_USEFOREGROUND: Indicates that sForeground defines the foreground text color to apply to highlights.
- SCCVW_USEBACKGROUND: Indicates that sBackground defines the background text color to apply to highlights.
- SCCVW_USECHARATTR: Indicates that wCharAttr defines the character attributes to apply to highlights.
sForeground: Defines the foreground text color to be used if the SCCVW_USEFOREGROUND flag is set in dwOptions. Set this value with the SCCANNORGB(red, green, blue) macro. The red, green and blue values are percentages of the color from 0-255 (with 255 being 100%). There is no default value for this parameter -- if it is set, the color must be specified.
sBackground: Defines the background text color to be used if the SCCVW_USEBACKGROUND flag is set in dwOptions. Set this value with the SCCANNORGB(red, green, blue) macro. The red, green and blue values are percentages of the color from 0-255 (with 255 being 100%). There is no default value for this parameter. If it is set, the color must be specified.
wCharAttr: Defines the character attributes to use if SCCVW_USECHARATTR is set in dwOptions. Only bits with the corresponding bits set in wCharAttrMask are affected. To turn off all character attributes, set this to SCCVW_CHARATTR_NORMAL (the default) and set wCharAttrMask to -1. Otherwise, set this to any of the following character attributes OR-ed together:
- SCCVW_CHARATTR_UNDERLINE
- SCCVW_CHARATTR_ITALIC
- SCCVW_CHARATTR_BOLD
- SCCVW_CHARATTR_STRIKEOUT
- SCCVW_CHARATTR_SMALLCAPS: Not currently supported in PDF Export.
- SCCVW_CHARATTR_OUTLINE: Not currently supported.
- SCCVW_CHARATTR_SHADOW: Not currently supported.
- SCCVW_CHARATTR_CAPS: Not currently supported.
- SCCVW_CHARATTR_SUBSCRIPT: SCCVW_CHARATTR_SUPERSCRIPT
- SCCVW_CHARATTR_DUNDERLINE: Currently supported as single underline.
- SCCVW_CHARATTR_WORDUNDERLINE: SCCVW_CHARATTR_DOTUNDERLINE
wCharAttrMask: Defines which character attributes to change based on the settings of the bits in wCharAttr. Uses the same bit flags defined above for wCharAttr. Only attributes whose flag is set in this mask are modified to match the state specified by wCharAttr. This mask provides a way to distinguish between bits being set in wCharAttr because the developer wants to force a change to the character attributes, and bits in wCharAttr that the developer would rather set to "inherit from the source document." The following are real-world examples of these interactions (all examples assume that SCCVW_USECHARATTR is set in dwOptions):
- Example 1: wCharAttr is set to SCCVW_CHARATTR_BOLD and wCharAttrMask is set to SCCVW_CHARATTR_BOLD. This results in bold being forced on in the annotation.
- Example 2: wCharAttr is set to SCCVW_CHARATTR_BOLD and wCharAttrMask is set to 0. This results in bold being left the way it was in the source document in the annotation.
- Example 3: wCharAttr is set to 0 and wCharAttrMask is set to SCCVW_CHARATTR_BOLD. This results in bold being forced off in the annotation.
The default value for this is 0, meaning that all the flags in wCharAttr are ignored.

Return Values

DAERR_OK: The annotation was successfully added. Otherwise, one of the other DAERR_ values in sccda.h or one of the SCCERR_ values in sccerr.h is returned.

7.2.3 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

hExportL Export handle for the document. Must be the handle returned by the EXOpenExport() function.
pHideText: Pointer to an EXANNOHIDETEXT structure containing the information on the section of text to hide.

7.2.3.1 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 */
   VTLPCHAR   pBookmark;    /* HTML Export Only */
} EXANNOHIDETEXT;

dwSize: Must be set by the OEM to sizeof(EXANNOHIDETEXT).
dwStartACC: Position of the first character to be hidden.
dwEndACC: Position of the last character to be hidden, plus one.

Return Values

SCCERR_OK: Returned if the annotation was successfully added. Otherwise, one of the other SCCERR_* values in sccerr.h is returned.

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

hExport: Export handle
pHilites: Buffer containing a stream of highlight (and comment) information that was obtained via the Web View Export Javascript API function OIT.highlights.serialize.

7.2.5 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;