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