Callbacks

This chapter describes the use of callbacks in Image Export. Callbacks allow the developer to intervene at critical points in the export process

Read more about the callback procedure and the EXOpenExport function call in EXOpenExport. Each heading in this chapter is a possible value for the dwCommandOrInfoId parameter passed to the developer’s callback.

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

This chapter describes the following callbacks:

• EX_CALLBACK_ID_CREATENEWFILE

• EX_CALLBACK_ID_NEWFILEINFO

• EX_CALLBACK_ID_PAGECOUNT

• EX_CALLBACK_ID_BEGINPAGE

• EX_CALLBACK_ID_ENDPAGE

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.

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 value is as used in the original ExOpenExport in the dwOutputId field. For example, for JPEG this value should be FI_JPEGFIF.

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

• dwOutputId: The type of the new file. This value should be the same as the value in dwParentOutputID.

• dwFlags: Reserved

• dwSpecType: IO specification type. For details about IO specifications, see DAOpenDocument.

  This member in conjunction with pSpec allows the developer to select any location for the new file or even redirect its IO calls entirely. For more details, see 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 your application receives this callback, the contents of the buffer pointed to by pSpec are undefined. A specification must be defined by your application 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 EXURLFILEIOCALLBACKDATA / EXURLFILEIOCALLBACKDATAW Structures. Set by caller.

• pTemplateName: NULL

EXURLFILEIOCALLBACKDATA / EXURLFILEIOCALLBACKDATAW Structures

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;

• dwSize: Set by Image Export to sizeof(EXURLFILEIOCALLBACKDATA) or sizeof(EXURLFILEIOCALLBACKDATAW).

• szURLString / wzURLString: This parameter can be set by the developer to a new URL that references the newly created file. This parameter is optional unless the pSpec provided by the developer points to something that cannot be used as a URL (as when using redirected IO, for example). In that case, this parameter must be set.

  This string is written into any output file that needs to reference the newly created file, with appropriate conversions between single and double byte output. Because this parameter is a URL, it is assumed to be URL encoded. When used in conjunction with dwSpecType and pSpec, this parameter can be used to generate almost any structure or location for the output files, including things like writing the output files into a database and then using a CGI mechanism to retrieve them.

  The current size limitation is 2048 characters. If the size exceeds this limit, the URL will be truncated and rendered useless.

• dwFileID: Set by the product. This is used as a unique identifier for each output file generated. It may be used for an OEM-specific purpose. When using HTML Export, this identifier is always set to zero when this callback is made as the result of a {## copy} statement in the template.

Return Value

• SCCERR_OK: dwSpecType, pSpec and szURLString (or wzURLString) have been populated with valid values.

• SCCERR_NOTHANDLED: Default naming should be used.

• SCCERR_FILEOPENFAILED: Some error was encountered creating a new output.

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.

EX_CALLBACK_ID_PAGECOUNT

Image Export uses this callback message to return a count of all of the output pages produced during an export operation. This count reflects the number of pages created by Outside In’s processing of the input document; which in some cases may differ slightly from the number of pages as seen in the document’s original application.

The page count is not necessarily the same as the number of output files produced. For example, exporting to TIFF images will result in the same page count regardless of whether a single multi-page file was created or multiple individual TIFF files were created.

This callback occurs during the execution of EXRunExport.

Data Type

VTDWORD

EX_CALLBACK_ID_BEGINPAGE

This callback message allows the margin text to be supplied for each page. This callback indicates that a new page of output is about to be created. Within the scope of this callback, the host application is able to set margin text to new values for the current page.

For this callback, the pCommandOrInfoData parameter points to a zero-based count of the page about to be created.

Data Type

VTDWORD

Return Value

Must be either SCCERR_OK or SCCERR_NOTHANDLED

EX_CALLBACK_ID_ENDPAGE

This callback allows the communication of page-level information via a callback/API call combination. It is called upon the completion of each page that is exported and gives the zero-based page number of the page exported.

Information on whether or not a page is hidden or if a page has slide notes, as specified in the input document, can be retrieved when this callback is received. You can retrieve this information with the API call EXGetProperties.

Data Type

VTDWORD

Return Value

SCCERR_OK or SCCERR_NOTHANDLED should be returned