(v13) D_GET_OUTPUT_FILENAME

This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core

D_GET_OUTPUT_FILENAME Selector

Parameter: devGetOutputFilenameParam * filenameparam

This selector is aimed specifically at plugins that produce raster files on disk for further processing. The selector provides the opportunity for the plugin to pass back key details about each file that has been produced, most importantly the absolute path and filename. The information handed back to the RIP from this selector is then used to support raster file processing in SOAR workflows.

The RIP arranges to call the D_GET_OUTPUT_FILENAME selector immediately after the D_WAIT_ON_CLOSE selector (or D_CLOSE , if D_WAIT_ON_CLOSE is not supported) for each separation. It is expected that the plugin will have finalized the raster file on disk at this time, and that it will have preserved the absolute name of the file that was created. In the rare event that the plugin produces multiple disk files for individual separations, it can signal for further D_GET_OUTPUT_FILENAME selector calls to be made.

Each selector call is used by the RIP to retrieve information about only one file.

Each call to D_GET_OUTPUT_FILENAME is used to feed information to an equivalent callout to JobStatusConsumer::job_ripped_byte_map_file_8() in the SOAR SDK. The RIP is able to provide information about the job ID, page number and separation color name automatically from the context of its server loop. The remaining information about the filename and data format type needs to come directly from the plugin, and the role of this selector is to obtain it.

The parameter passed with the selector is described below.

    #define MAX_FILENAME_LENGTH 1024
    typedef struct devGetOutputFilenameParam
    {
        int32 nIndex;
        int32 fMoreFiles;
        uint8 atbzFilename [MAX_FILENAME_LENGTH];
        uint8 atbzFiletype [MAX_FILETYPE_LENGTH];
    } devGetOutputFilenameParam

Note : Please note that in some circumstances the RIP may not call this selector at all, and your plugin should be designed to accommodate this. For example, you should not rely upon this selector call to free any memory used to store the file name within your plugin.

nIndex

This allows the plugin to keep track of the number of selector calls that have been made for the cur‐ rent separation. This parameter is only interesting in the case where multiple files are produced for individual separations, which is expected to be quite rare. The RIP will pass 0 on the first call to the selector.

fMoreFiles

The plugin should set this flag to TRUE if it has generated more than one file. In this case, further calls will be made to D_GET_OUTPUT_FILENAME to retrieve information about the remaining files, with nIndex being incremented each time.

The plugin should set this flag to FALSE in order for no further calls to be made. It is expected that the regular case would be for the output plugin to produce a single file on disk for each separation of each page, such as with the TIFF plugin. In this case, the plugin should set this flag to FALSE immediately on the first call.

atbzFilename

The plugin should write the absolute name of the output file into this buffer. The name should be structured according to the conventions of the host platform (for example, using drive letters and backslash separators on PC platforms). The string must be null‐terminated, and should conform to the Harlequin multi‐byte text string format. If the plugin has failed to produce a file due to an error, it can safely pass an empty string back to the RIP.

atbzFiletype

The plugin can use this space to write a null‐terminated C locale string (that is, containing no multi‐ byte characters) indicating, where appropriate, the standard IANA data type (as would be used as the content type in a MIME stream). The TIFF plugin, for example, always writes the constant string ʺimage/tiff ʺ into this buffer. The plugin can write an empty string if no standard format type is appropriate, or required.