10 Callbacks

10.1.1 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;
   VTDWORD    dwParentOutputId;
   VTDWORD    dwAssociation;
   VTDWORD    dwOutputId;
   VTDWORD    dwFlags;
   VTDWORD    dwSpecType;
   VTLPVOID   pSpec;
   VTLPVOID   pExportData;
   VTLPVOID   pTemplateName;
} EXFILEIOCALLBACKDATA;

• hParentFile: Handle to the initial output file with which the new file is associated. The dwAssociation describes the relationship. This handle is not intended for use by the developer. Set by caller.

• dwParentOutputId: Set by caller. The type of the parent file. This is one of three values, depending on which output format is being produced. It can be FI_HTML, FI_MHTML, or FI_XHTML.

• dwAssociation: One of the following values:

  • CU_ROOT: For the initial output file.

  • CU_SIBLING: For new files that are not somehow owned by the parent file. This can be additional HTML output files created as the result of template directives.

  • CU_CHILD: For new files (usually GIFs, JPEGs, or PNGs) that are embedded in the parent file.

  • CU_COPY: For files that are being copied as the result of a template {## copy} macro.

    The OEM should be aware that each time the {## copy} macro causes a file to be copied, the EX_CALLBACK_ID_CREATENEWFILE callback is called. To indicate the callback happened as a result of the {## copy} macro, the dwAssociation field is set by HTML Export to CU_COPY. In addition, the OEM should also be aware that the dwOutputId field will be set by HTML Export to FI_UNKNOWN.

    OEMs using {## copy} and redirected IO should be aware that copied files are considered to be loosely associated with the template. As such, if redirected IO is being used for the root template, HTML Export allows the copied files to be handled through redirected IO, as well. For each {## copy} instance, an IOGetInfo call is made, requesting IOGETINFO_GENSECONDARY.

    The IOGETINFO_GENSECONDARY call for redirected IO should have opened the file to be copied, so this call is entirely informational in this situation. The OEM may then return redirected IO information in the IOGENSECONDARY/IOGENSECONDARYW structure, as needed. If redirected IO is not needed for the file to be copied, HTML Export attempts to open the file locally. OEMs should also be aware that {## copy} results in a IOGENSECONDARY call with dwOpenFlags set to IOOPEN_WRITE.

  dwAssociation used in conjunction with dwOutputId can be used to segregate various types of files. For instance, the developer might want to place all GIFs in a sub-directory named GRAPHICS. Set by caller.

• dwOutputId: The outputID will reflect the type of file that the export wants to create at the time of the callback. The outputID will match the output format of the export (HTML, MHTML, or XHTML) when it is creating an output file of that type. It will be one of: FI_HTML, FI_MHTML, or FI_XHTML.

  When the export is creating an associated file to go along with the main output file, such as a graphic, Javascript, CSS, etc., then the outputID will reflect the type of this file. It could one of the following: FI_HTML_CSS, FI_JAVASCRIPT, FI_GIF, FI_JPEGFIF or FI_PNG.

• dwFlags: Reserved

• dwSpecType: IO specification type. For details about IO specifications, see Section 7, "Data Access Common Functions."

  This member in conjunction with pSpec allows the developer to choose any location for the new file or even redirect its IO calls entirely. For more information, see Chapter 9, "Redirected IO." When the developer receives this callback, the value of this element is undefined. Must be set by developer if this callback returns SCCERR_OK.

• pSpec: This field holds the IO specification of the output file to be created. pSpec points to a buffer that is 1024 bytes in size. If your application needs to set the specification of the output file, it may do so by either writing new data into this buffer, or by changing the value of pSpec to point to memory owned by your application. If pSpec is set to a new value, then your application must ensure that this memory stays valid for an appropriate length of time, at least until the next callback message is received, or EXRunExport returns.

  If the current export operation is using redirected IO, your application must create a redirected IO data structure for the new file and set pSpec to point to it. This pointer must stay valid until the structure's pClose function is called.

  If your application sets dwSpecType to IOTYPE_UNICODEPATH, the specification must contain UCS-2 encoded Unicode characters.

  When the developer receives this callback, the bytes in the buffer pSpec points to are undefined. Must be set by the developer if this callback returns SCCERR_OK.

• pExportData: Pointer to data specific to the individual export. In this case, always a pointer to either an EXURLFILEIOCALLBACKDATA structure or an EXURLFILEIOCALLBACKDATAW structure. The EXURLFILEIOCALLBACKDATAW struct is only used when the SCCOPT_UNICODECALLBACKSTR option is set to TRUE. These two structures are defined in Section 10.1.1.1, "EXURLFILEIOCALLBACKDATA / EXURLFILEIOCALLBACKDATAW Structures." Set by caller.

• pTemplateName: Pointer to a NULL-terminated string containing the name of the template responsible for opening the new output file. If a template uses the {## link} command, a new output file may be created to hold the linked-to output. When this happens, this field contains the name of the template being parsed in order to create the output. Whether this is a string of WORDs or BYTEs is dependent on the SCCOPT_UNICODECALLBACKSTR option. If this option is set to TRUE, it is a pointer to an array of WORDs. Otherwise, it is a pointer to an array of BYTEs.

  Because historically the SCCOPT_EX_TEMPLATE option was not set until after the original output file had been opened, a change was made to allow this option to be set before the call to EXOpenExport. If this option is set before EXOpenExport, the pTemplateName field is a valid string. Otherwise, it is NULL for the original output file.

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;

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

10.1.3 EX_CALLBACK_ID_ALTLINK

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

• dwType: Set by HTML Export to the type of link that couldn't be resolved, either EX_ALTLINK_PREV or EX_ALTLINK_NEXT.

• pAltURLStr: Set by HTML Export to a buffer of size 1024 bytes. The developer should write to this buffer a null terminated string representing the URL to be used as the alternate link. The character size of the string is based on the value of the SCCOPT_UNICODECALLBACKSTR option.

  If a buffer larger than 1024 bytes is required, the developer may assign this pointer to a new buffer. In this case the new buffer must be guaranteed to exist until the next callback message is received for the current hExport, or EXRunExport returns.

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

10.1.4 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 Section 10.1.12, "EX_CALLBACK_ID_PROCESSLINK."

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.

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

• dwSpecType: Describes the contents of pSpec. Together dwSpecType and pSpec describe the location of the initial output file for the archive entry. A default value is filled in by HTML Export based on the next output file name HTML Export would normally use. Must be one of the values allowed for the dwSpecType passed to EXOpenExport.

• pSpec: File location specification for the first output file generated by the conversion of the archive entry. This parameter is either a pointer to a buffer or NULL. If the pointer is not NULL, the buffers contents are based on the value of the dwSpecType parameter. See the descriptions under the individual dwSpecTypes listed for EXOpenExport.

  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 will return an error. For more information, see Section 10.1.1, "EX_CALLBACK_ID_CREATENEWFILE."

  A default value is filled in by HTML Export based on the next output file name HTML Export would normally use. In other words, if the original output file created was main.htm, and main0001.htm - main0003.htm have been created, then the first file created for the file in the archive is main0004.htm.

• wzFullName: Filled in by HTML Export with a NULL-terminated Unicode string representing the name of the file entry in the archive. This name includes any path information provided in the archive file. Similar to sections.current.fullname in the template language.

• dwItemNum: The item number of the entry in the archive file. Similar to sections.current.itemnum in the template language.

Return Value

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

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

• hFile: A handle to the current graphic output file. An OEM can substitute their own graphic by writing the desired graphic image to the beginning of the hFile (via an IOSEEK (hFile, IOSEEK_TOP, 0L), etc. The export function closes the file when control is returned from the callback. The contents of hFile on entry to the callback handler are unpredictable.

• pXSize/pYsize: Pointers to the dimensions of the image that would have been exported. An OEM can set and use these values to control the image size displayed by browsers. These dimensions are placed in the associated <img> tag.

• dwOutputId: The type of graphics file that was being created (FI_GIF, FI_JPEGFIF, or FI_PNG).

• ExportGraphicStatus: The error code from the operation that caused the graphic image conversion to fail.

• pImageSize: The maximum size for the image in bytes is filled in by HTML Export here (0 = no limit). If this callback is handled, on return the OEM should set this field to the size of the image the OEM created. This image should be no larger than the maximum size HTML Export entered into this variable.

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.

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

• ExportResult

  Filled in by HTML Export with SCCERR_OK or the error code generated by the conversion of the archive file entry.

Return Value

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

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

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

• dwSize: sizeof(EXOEMOUTCALLBACKDATA_VER2)

• dwCharset: The character set of the string contained in pwBuffer. This may not be set to SO_UTF8.

• dwLength: The length of the string contained in pwBuffer.

• pOEMString: Pointer to a Unicode string that represents the value of the oem attribute of the {## insert} macro. For example, if the macro is {## insert oem=phone}, pOEMString points to the NULL-terminated Unicode string "phone."

• pwBuffer: Pointer to the string which the OEM wants to insert. This is a WORD buffer, and it is the OEM's responsibility to convert their string to a NULL-terminated WORD string regardless of the character set specified by dwCharset. This means that single-byte character strings must be expanded into one character per WORD.

  For double-byte character set strings, the lead byte and trail byte should occupy the same WORD value, with the lead byte in the high order byte of the WORD.

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED.

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

10.1.11 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 Section 10.1.4, "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;

• dwSize: sizeof(EXCUSTOMELEMENTCALLBACKDATA_VER2)

• dwCharset: The character set of the string contained in pwBuffer. This may not be set to SO_UTF8.

• dwLength: Set by the OEM to the number of characters, not bytes, in the string contained in pwBuffer.

• pKeyStr: Pointer to a string that represents the keyword value of the custom element. The representation of the string is defined by the value set by the SCCOPT_EX_UNICODECALLBACKSTR option. The keyword is the text following the "=", up to the next separator character, either a space or a period. This is the string used for determining if the element is a valid custom element, based on the list of valid elements given by the EX_CALLBACK_ID_CUSTOMELEMENTLIST callback. For example, if the macro is {## insert element=phone help}, pKeyStr points to the NULL-terminated string "phone."

• pElementStr: Pointer to a string that represents the keyword value of the custom element. The representation of the string is defined by the value set by the SCCOPT_EX_UNICODECALLBACKSTR option. This is the text after the keyword up to the closing "}". This string may be NULL. For example, if the macro is {## insert element=phone help}, pElementStr points to the NULL-terminated string "help."

• pwBuffer: Pointer to the string that the OEM wants to insert into the output file(s). This is a WORD buffer, and it is the OEM's responsibility to convert their string to a NULL-terminated WORD string regardless of the character set specified by dwCharset. This means that single-byte character strings must be expanded into one character per WORD.

  When HTML Export makes this callback, pwBuffer points to a buffer that is 512 WORDs in size. If this is not enough room, the OEM may set pwBuffer to point to a different buffer allocated (and later freed) by the OEM. The OEM should NOT free or realloc the buffer provided by HTML Export. In addition, the OEM's buffer must be valid until the next call from HTML Export is received, or EXRunExport returns.

  For double-byte character set strings, the lead byte and trail byte should occupy the same WORD value, with the lead byte in the high order byte of the WORD.

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED.

10.1.12 EX_CALLBACK_ID_PROCESSLINK

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;

• pLocatorStr: Pointer to a string containing the linked object location information (such as a file path or URL). The buffer containing this string is 1024 bytes in size. The developer may use this buffer to change the object location string or provide a new one.

  If the developer wishes, the pointer can be changed to point to a buffer of the developer's choosing. However, if this is done, the pointer provided must be valid until the next EX_CALLBACK_ID_PROCESSLINK callback is made, or EXRunExport returns.

  If the string is changed, it only has an effect if the developer is requesting that it be used as the SRC parameter in the resultant image tag (for example, dwAction = EX_ACTION_CREATELINK). The size of a character in the string (BYTE or WORD) is resolved by the dwLocatorStrCharset field.

• dwLocatorStrCharset: Character set of the string pointed to by pLocatorStr. The value corresponds to the character set defines in vtchars.h. If the string pointed to by pLocatorStr is changed, this value must also be changed if the character set of the new string is different than the original.

• dwObjectFileId: The type of the object pointed to by the link. The value corresponds to the FI value defines found in sccfi.h. If the value is FI_NONE, the linked object could not be found.

• dwAction: Must be set by the callback routine. The value tells HTML Export how to deal with this link and can be one of the following values:

  • EX_ACTION_CONVERT: Default behavior occurs. HTML Export attempts to follow the link, convert it to the selected image type, and insert that object into the resultant output file.

  • EX_ACTION_SKIP: The link is to be skipped. No image tag is to be produced. SCCERR_OK must be returned in order for the value of this field to have an effect.

• dwLinkFlags: Contains a set of flags that provide information about the link.

  • EX_FLAG_USEOUTPUTCHARSET: Set by the callback routine to indicate that dwLocatorStrCharset specifies the character set of pLocatorStr.

  • EX_FLAG_PUTATTRIBUTES: Set by the callback routine to indicate that image attributes, such as the width and height of the image, should be output in the <img> tag.

  • EX_FLAG_DIMENSIONSKNOWN: Set by HTML Export to indicate whether the dimensions of the graphic are known. If this flag is set and the callback routine sets EX_FLAG_PUTATTRIBUTES, the width and height of the image will be output in the <img> tag.

• hReserved: Field reserved for future use.

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.

10.1.13 EX_CALLBACK_ID_REFLINK

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;

• pSubdocSpec: Filled in by HTML Export with a subdocument specification for the current archive entry. The subdocument specification is a single-byte character string that specifies the referenced item within the archive file. To resolve this link, the subdocument specification should be provided (unmodified) to HTML Export in a subsequent call to DAOpenDocument.

• URL: Filled in by the OEM with the complete URL that HTML Export should use in response to the {## insert}. This URL will later be returned to the OEM's application when the link is used. The OEM will need to interpret this URL and use it to provide the file and subdocument specifications to DAOpenDocument during the export of the subdocument. This URL will not be modified or encoded by HTML Export, but written to the output file exactly as you specify. Therefore, the string returned is expected to be URL encoded. Since URLs are 7-bit ASCII, the value passed in here is a NULL-terminated, single-byte character string.

• wzFullName: This parameter is populated with the value of the sections.x.fullname template element, which is the full name (including path, where applicable) of the file in the archive.

Return Value

• SCCERR_OK: If the OEM is providing the URL for HTML Export to use.

• SCCERR_NOTHANDLED: If HTML Export should generate the URL to be used.