Callbacks

Callbacks allow the developer to intervene at critical points in the export process. Each heading in this chapter is a possible value for the dwCommandOrInfoId parameter passed to the developer’s callback.

Read more about the callback procedure and the EXOpenExport function call in Export Functions.

The new SCCOPT_EX_CALLBACKS option allows developers to enable or disable some or all of these callbacks. See the Options documentation for details.

This chapter describes callbacks set in EXOpenExport. A second callback function, DASetStartCallback, can provide information about the progress of a file conversion. For more details, see Data Access Common Functions.

The following callbacks apply to HTML Export:

Parent topic: Using the C/C++ API

EX_CALLBACK_ID_CREATENEWFILE

This callback is made any time a new output file needs to be generated. This gives the developer the chance to execute routines before each new file is created.

It allows the developer to override the standard naming for a file or to redirect entirely the IO calls for a file. This callback is made for all output files that are created.

These include all output text and graphics files that are created. However, it does not include the already open initial file passed to EXOpenExport, unless of course redirected IO is in use with a pSpec of NULL.

If redirected IO is being used on output files, this callback must be implemented.

For this callback, the pCommandOrInfoData parameter points to a structure of type EXFILEIOCALLBACKDATA:

typedef struct EXFILEIOCALLBACKDATAtag
{
    HIOFILE hParentFile;        /* handle of the first output file that the new file is associated with */
    VTDWORD dwParentOutputId;   /* FI ID indicating type of data parent file will contain */
    VTDWORD dwAssociation;      /* information on how new file should relate to the file passed in hFile */
    VTDWORD dwOutputId;         /* FI ID indicating type of data that this file will contain */
    VTDWORD dwFlags;            /* Reserved; set to 0 */
    VTDWORD dwSpecType;
    VTLPVOID pSpec;
    VTLPVOID pExportData;       /* more file info based on the dwParentOutput ID; */
                                                /* see EXURLFILEIOCALLBACKDATA above */
    VTLPVOID pTemplateName;     /* pointer to the name of the template */
} EXFILEIOCALLBACKDATA;

EXURLFILEIOCALLBACKDATA / EXURLFILEIOCALLBACKDATAW Structures

These are new, more generic names for the old EXHTMLFILEIOCALLBACKDATA and EXHTMLFILEIOCALLBACKDATAW structures. The old names continue to be supported indefinitely to maintain backwards compatibility.

The EXURLFILEIOCALLBACKDATA and EXURLFILEIOCALLBACKDATAW structures are defined as follows:

typedef struct EXURLFILEIOCALLBACKDATAtag 
{
   VTDWORD   dwSize;
   VTBYTE    szURLString[VT_MAX_URL];
   VTDWORD   dwFileID;
} EXURLFILEIOCALLBACKDATA;

typedef struct EXURLFILEIOCALLBACKDATAWtag
{
   VTDWORD   dwSize;
   VTWORD    wzURLString[VT_MAX_URL];
   VTDWORD   dwFileID;
} EXURLFILEIOCALLBACKDATAW;

Return Value

EX_CALLBACK_ID_NEWFILEINFO

This informational callback is made just after each new file has been created. Like the EX_CALLBACK_ID_CREATENEWFILE callback, the pExportData parameter points to an EXURLFILEIOCALLBACKDATA or an EXURLFILEIOCALLBACKDATW structure, but in this case the structure should be treated as read-only and the dwSpecType, pSpec and szURLString (or wzURLString) will be filled in.

This callback occurs for every new file. If the developer has used the EX_CALLBACK_ID_CREATENEWFILE notification to change the location of (or to set up redirected IO for) the new file, the data structure echoes back the information set by the developer during the EX_CALLBACK_ID_CREATENEWFILE callback.

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED. Return value is currently ignored.

This callback is made when a {## anchor} macro that would be used for navigating between output files cannot be resolved to a location in the set of output files. The two cases that result in this callback are a “previous” link from the first output file, or a “next” link from the last output file. Responding to this callback allows the endpoints of the next/previous links in a set of output pages to point to locations outside of the converted document itself.

This callback only occurs if the altlink= attribute is missing in the {## anchor} statement or is invalid.

The pCommandOrInfoData parameter points to a structure of type EXALTLINKCALLBACKDATA:

typedef struct EXALTLINKCALLBACKDATA
{
   VTDWORD    dwType;
   VTLPVOID   pAltURLStr;
}

Unlike the other callbacks that use the SCCOPT_UNICODECALLBACKSTR option, EX_CALLBACK_ID_ALTLINK does not have separate normal and wide structures.

EX_CALLBACK_ID_CUSTOMELEMENTLIST

This callback works in conjunction with the EX_CALLBACK_ID_PROCESSELEMENTSTR_VER2 callback to allow the OEM to extend the template document tree. The callback is made at the beginning of processing to get a pointer to the list of OEM-defined custom elements. These elements are referenced from the template with {## insert element=}. When one of these elements is found in the template, the EX_CALLBACK_ID_PROCESSELEMENTSTR_VER2 callback is triggered. If that callback returns SCCERR_NOTHANDLED, then the EX_CALLBACK_ID_PROCESSELEMENTSTR callback is triggered. For more information, see EX_CALLBACK_ID_PROCESSLINK.

Note:

Oracle reserves the right to add any string(s) to the list of supported elements. It is therefore recommended that great care be exercised when selecting element names. One method of reducing this risk may be to use your company’s name in the element name keyword. Due to this potential for future naming conflicts, the “oem=” mechanism is still the preferred method for generating callbacks based on template elements.

The pCommandOrInfoData field is a pointer that is expected to be filled in with the address of an array of NULL-terminated strings, where the last string is a NULL string. This array is provided by the OEM and is not allocated or freed by HTML Export. This list is used to determine if an unexpected element found in a template is valid.

If the SCCOPT_UNICODECALLBACKSTR option is set to TRUE, it is assumed this list contains Unicode strings. If the option is set to FALSE, it is assume the list contains ASCII strings. Each string is limited to 64 characters in length (128 bytes for Unicode) including NULL-terminator. Elements are case insensitive, as is the template language.

HTML Export only allows Unicode or 7bit ASCII for the custom element values when this option is set.

An example of declaring the list of strings would be the following:

   char * CustomElementList[] = {
      "string1",
      "string2",
      "string3",
      NULL,
      };

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED. If SCCERR_OK is returned, the pCommandOrInfoData field must contain a valid pointer.

EX_CALLBACK_ID_ENTERARCHIVE

This callback is made when the template begins the following construct:

`{## link element=sections.current.decompressedfile}`

This callback provides a way for the OEM to change the pSpec and dwSpecType used for the output of the conversion of the archive entry. For the remainder of the conversion of the archive entry, the default output file names generated by HTML Export are based on the pSpec and dwSpecType returned here. By default, the OEM may leave these unchanged and use names generated by HTML Export. The callback also provides the OEM with information about the archive entry to be converted. This information could be used for things such as putting the output of each archive entry into a directory separate from the output of the original output file(s).

When this callback happens, HTML Export internally recursively calls itself on the target archive file entry. As such, any options set in the parent export are inherited by the child export. However, any options set by the OEM or the templates while processing is being done inside the child export, revert to their original settings upon completion of the child export. In addition, any callbacks HTML Export would normally make are percolated up from the child export to the OEM’s program. Note that options cannot be set via this callback for child exports.

The pCommandOrInfoData parameter points to a structure of type EXENTERARCHIVECALLBACKDATA:

typedef struct EXENTERARCHIVECALLBACKDATAtag
{
   VTDWORD     dwSpecType;
   VTLPVOID    pSpec;
   VTLPWORD    wzFullName;
   VTDWORD     dwItemNum;
} EXENTERARCHIVECALLBACKDATA;

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED. The return value is currently ignored.

EX_CALLBACK_ID_GRAPHICEXPORTFAILURE

This callback only occurs when an error is encountered exporting a graphic. It allows the OEM to customize their handling of this type of error. This callback does not occur for graphics exports that are successful. It also does not occur for graphics that cannot be converted due to the lack of an appropriate type of import filter. If the appropriate import filter is not present, EXOpenExport returns SCCERR_NOFILTER.

The pCommandOrInfoData field points to a structure of type EXGRAPHICEXPORTINFO:

typedef struct EXGRAPHICEXPORTINFOtag
{
   HIOFILE     hFile;
   VTLPDWORD   pXSize;
   VTLPDWORD   pYSize;
   VTDWORD     dwOutputId;
   SCCERR      ExportGraphicStatus;
   VTLPDWORD   pImageSize;
} EXGRAPHICEXPORTINFO;

Return Value

The callback handler should return SCCERR_NOTHANDLED unless the OEM has written an image to hFile in which case a value of SCCERR_OK should be returned.

EX_CALLBACK_ID_LEAVEARCHIVE

This callback is made when the template finishes the following:

{## link element=sections.current.decompressedfile}

Links of this nature are handled by Export internally as a recursive call to HTML Export on the target archive file entry. As such, any errors returned by the conversion of the {## link} target are not reflected in the error code returned by EXRunExport. In addition, conversion of the target archive entry may fail, but export of the archive file continues. This callback provides the error code generated by the conversion of the archive file entry.

The pCommandOrInfoData parameter points to a structure of type EXLEAVEARCHIVECALLBACKDATA:

typedef struct EXLEAVEARCHIVECALLBACKDATAtag
{
   SCCERR   ExportResult;
} EXLEAVEARCHIVECALLBACKDATA;

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED. The return value is currently ignored.

EX_CALLBACK_ID_OEMOUTPUT

This callback has been deprecated. While this callback continues to be supported, users are encouraged to use the new EX_CALLBACK_ID_OEMOUTPUT_VER2 callback. The new version supports mapping the output for this callback to the output character set. This is especially important given that HTML Export sometimes overrides the output character set indicated by the SCCOPT_EX_OUTPUTCHARACTERSET option.

For now, HTML Export only makes this callback if EX_CALLBACK_ID_OEMOUTPUT_VER2 returns SCCERR_NOTHANDLED.

EX_CALLBACK_ID_OEMOUTPUT_VER2

This callback is made in response to a {## insert oem=} macro inside a template file. When this callback occurs, the developer may return a string to be inserted into the output file. Multiple {## insert oem=} macros are differentiated by the value of the “oem=” string. For example, {## insert oem=phone} could be used to trigger this callback so that a phone number could be extracted from a database and inserted into the output file at this point.

This callback differs from the EX_CALLBACK_ID_OEMOUTPUT callback in that it correctly handles character mapping of the string to be inserted into the output file. It does this by mapping the string pointed to in pwBuffer from the character set given by dwCharset to the output character set used by HTML Export. This is especially important given that HTML Export sometimes overrides the output character set indicated by the SCCOPT_EX_OUTPUTCHARACTERSET option. With this callback, the string pointed to in pwBuffer is mapped from the character set given by dwCharset to the output character set used by HTML Export. The correctly mapped character string is then written by HTML Export to the output file.

The EX_CALLBACK_ID_OEMOUTPUT callback is not made unless this callback returns SCCERR_NOTHANDLED.

The pCommandOrInfoData parameter points to a structure of type EXOEMOUTCALLBACKDATA_VER2:

typedef struct EXOEMOUTCALLBACKDATA_VER2tag
{
   VTDWORD   dwSize;
   VTDWORD   dwCharset;
   VTDWORD   dwLength;
   VTLPVOID  pOEMString;
   VTLPWORD  pwBuffer; 
} EXOEMOUTCALLBACKDATA_VER2;

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED.

EX_CALLBACK_ID_PROCESSELEMENTSTR

This callback has been deprecated. While this callback continues to be supported, users are encouraged to use the new EX_CALLBACK_ID_PROCESSELEMENTSTR_VER2 callback. The new version supports mapping the output for this callback to the output character set. This is especially important given that HTML Export sometimes overrides the output character set indicated by the SCCOPT_EX_OUTPUTCHARACTERSET option.

For now, HTML Export only makes this callback if the EX_CALLBACK_ID_PROECESSSELEMENTSTR_VER2 callback returns SCCERR_NOTHANDLED.

EX_CALLBACK_ID_PROCESSELEMENTSTR_VER2

This callback works in conjunction with the EX_CALLBACK_ID_CUSTOMELEMENTLIST callback to allow the OEM to extend the template document tree. The callback is made when a custom element is found in a template. A custom element is verified by comparing it against the list of custom elements defined by the EX_CALLBACK_ID_CUSTOMELEMENTLIST callback. For more information, see EX_CALLBACK_ID_CUSTOMELEMENTLIST.

This callback differs from the EX_CALLBACK_ID_PROCESSELEMENTSTR callback in that it correctly handles character mapping of the string to be inserted into the output file. It does this by mapping the string pointed to in pwBuffer from the character set given by dwCharset to the output character set used by HTML Export. This is especially important given that HTML Export sometimes overrides the output character set indicated by the SCCOPT_EX_OUTPUTCHARACTERSET option. With this callback, the string pointed to in pwBuffer is mapped from the character set given by dwCharset to the output character set used by HTML Export. The correctly mapped character string is then written by HTML Export to the output file.

The EX_CALLBACK_ID_PROCESSELEMENTSTR callback will not be made unless this callback returns SCCERR_NOTHANDLED.

The pCommandOrInfoData field points to a structure of type EXCUSTOMELEMENTCALLBACKDATA_VER2:

typedef struct EXCUSTOMELEMENTCALLBACKDATA_VER2tag
{
   VTDWORD    dwSize;
   VTDWORD    dwCharset;
   VTDWORD    dwLength;
   VTLPVOID   pKeyStr;
   VTLPVOID   pElementStr;
   VTLPWORD   pwBuffer; 
} EXCUSTOMELEMENTCALLBACKDATA_VER2;

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED.

Currently, this advanced callback is available only for links to images. It is made in response to a link to a file or URL from inside the file being converted. It allows the developer to choose how this link should be handled. There are essentially four ways to deal with a link:

  1. The developer may request that the link be handled by having HTML Export attempt to follow the link, convert it to the selected image type, and insert the converted object (this is the default behavior).

  2. The developer may have an image tag created which uses a specified string as the source attribute (for example, as <img src=string>).

  3. The developer may ignore the link altogether.

  4. The developer may return SCCERR_NOTHANDLED, in which case HTML Export will use the original URL string.

The pCommandOrInfoData parameter points to a structure of type EXPROCESSLINKCALLBACKDATA:

typedef struct EXPROCESSLINKCALLBACKDATAtag
{
   VTLPVOID   pLocatorStr;
   VTDWORD    dwLocatorStrCharset;
   VTDWORD    dwObjectFileId;
   VTDWORD    dwAction;
   VTDWORD    dwLinkFlags; 
   VTHANDLE   hReserved;
} EXPROCESSLINKCALLBACKDATA;

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED. If the return value is anything other than SCCERR_OK, the default behavior will be performed.

As of this release, there are three working directories associated with HTML Export:

When a document being converted has a link to an object through a relative path, some unexpected results may occur due to differences in these working directories. Namely, a browser displaying the resultant HTML file if the relative path is not also valid for the directory containing the HTML file will not find relative links processed with the EX_ACTION_CREATELINK action. Furthermore, relative links processed using the default action (EX_ACTION_CONVERT) will result in an output document with image tags that reference empty files unless the relative path for the original objects is also valid for the directory containing the HTML Export technology.

Some browsers do not recognize <drive>:\<path>\<file> as an absolute path. A possible solution may be to use UNIX path notation instead if this is a problem (/drive|/path/file).

HTML Export’s support for archive files includes the ability to generate links to items within an archive. This is accomplished using the {## insert} element reflink. Because the OEM’s application will later be the recipient of requests to open these links, HTML Export provides a mechanism through which the OEM can specify exactly how these links are to be written to the output file.

When creating a link to an item within an archive, HTML Export will use the EX_CALLBACK_ID_REFLINK callback to provide the OEM with the subdocument specification of the item within the archive. The OEM can then format the URL to be used when writing this link to an output file. Then, upon receipt of a request to open this link, the OEM’s application will be able to provide HTML Export with the specification and subdocument specification needed to open the item within the archive.

For example, when exporting the archive c:\docs\file.zip, the particular template being used includes reflink insertions that generate links to each item within file.zip. Each time HTML Export is about to write such a link to the output file, it will use the callback function SCCEX_CALLBACK_ID_REFLINK to allow the OEM to format the link. When the request to open the link is received by the application, the developer will be able to provide the appropriate file and subdocument specifications to HTML Export to resolve the link to the archive item.

If this callback is not handled, HTML Export will generate a default URL. The default URL will be of the form NameOfArchiveFile?SubdocSpec. This callback is particularly important to OEMs using redirected IO, since when redirected IO is in use, the default URL generated by HTML Export is unlikely to be what is desired.

The pCommandOrInfoData parameter points to a structure of type EXREFLINKCALLBACKDATA:

typedef struct EXREFLINKCALLBACKDATAtag
{
   VTLPSTR   pSubdocSpec;
   VTCHAR    URL[VT_MAX_URL];
   VTLPWORD  wzFullName;
} EXREFLINKCALLBACKDATA;

Return Value