D_GET_IDENTITY

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

D_GET_IDENTITY Selector

Parameter: IdentityParam *param

Call type: Single‐call

This is the first call any plugin receives from the RIP. It determines if the plugin is an input or output plugin, and allows the plugin to decide if it will run with the supplied version of the plugin interface. If the plugin does not support the selector, it is assumed to be an older output plugin which can run on a newer RIP. This maintains backwards‐compatibility with devices built with earlier plugin kits.

Note: Any other kind of plugin introduced in the future will also be identified using this call.

Before version 4.0 of the RIP, each structure used in the plugin interface had its own version number. This proved unmanageable, especially for structures filled in by the plugin. An alternative numbering scheme was adopted which referred to the whole plugin interface.

This is accomplished by the last three fields in the IdentityParam structure. This structure is passed to the plugin by the RIP with the plugin interface numbers set. In response, the plugin should set fVersionOK to TRUE if it can run.

TEXT

      typedef struct { int32 version ; int32 pluginType ;
      int32 protocolVersion ;
      int32 pluginInterfaceMajorVersion ; int32 pluginInterfaceMinorVerson ; int32 fVersionOK ;
    } IdentityParam ;

Plugins should be compiled using a plugin kit for the earliest version of the RIP in which they can run. For example, if a plugin tried to set the new screensRequired field in rasterFormat for older versions of the RIP that do not have such a field, the plugin would be setting invalid memory. The fVersionOK field is used to inform the RIP whether the plugin can run with a given version of the RIP. Alternatively, the plugin might store the result of a test for the presence of a newer RIP version, and use the newer fields and features such as deviceResolutionsInPairs only when appropriate.

pluginType

If the plugin is an input plugin it should set this field to PT_INPUT ; if it is an output plugin it should set this field to PT_OUTPUT and if it's a core module plugin, it should set it to PT_COREMODULE .

protocolVersion

This field allows for changes to the way in which plugins are accessed in the future while still sup‐ porting existing ones. Input plugins should set it to INPUT_PLUGIN_PROTOCOL_VER , from gipdefs.h . Output plugins and core modules should set this field to 0 (zero).

pluginInterfaceMajorVersion and pluginInterfaceMinorVersion

These fields are set by the RIP to specify the major and minor plugin interface version numbers, respectively. Version 18.11 is the plugin interface version for version 7.2 of the RIP and version 20.2 is for version 10.1 of the RIP. Numbers may not be incremented if no non‐backward‐compatible changes to the interface are made. Plugin developers are recommended to make use of the CHECK_VERSION macro, as demonstrated in the output example plugins. See fVersionOK.

fVersionOK

If the plugin can run with the given version of the RIP, this field should be set to TRUE . If this field is set to FALSE , further loading or use of the plugin is prevented.

The CHECK_VERSION macro is provided to simplify this:

p->fVersionOK = CHECK_VERSION (p, 18, 11);

This example informs the RIP that the plugin is compatible with any RIP implementing plugin inter‐ face version 18.11 or higher. If the RIP is older, is will display an error message during startup, and unload the plugin.