Callbacks

This chapter describes the use of callbacks in PDF 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 includes the following callbacks:

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. It does not include the already open initial file passed to EXOpen Export, 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;

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;

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.

EX_CALLBACK_ID_PAGECOUNT

PDF 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 Oracle 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.

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