D_GET_IDENTITY (input plugin)

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 second call any plugin receives from the RIP, after support for it has been confirmed by a D_SELECTOR_SUPPORT call. 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 indicate support for this selector in the D_SELECTOR_SUPPORT call, it is assumed to be an output plugin which will run. This keeps existing output plugins compatible.

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 has proved unmanageable, especially for structures filled in by the plugin. A numbering scheme has been adopted which refers 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.

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

Plugins should be compiled for the earliest version of the RIP in which they can run. For example, if a plugin tried to set 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.

At the time of a D_GET_IDENTITY call, the globalState pointer in the IPPluginContext structure is not initialized. It is not ready until after the D_IP_BOOT call is complete and the D_IP_PLUGIN_INITIALISE call is made. Until the D_IP_BOOT call, the RIP does not know how much memory to allocate for the global plugin state.

version

The version field should be ignored.

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 .

Other possible types include:

• PT_CRDGEN (Color Rendering Dictionary plugin)
• PT_TRAP (Trapping plugin)
• PT_POSTSCRIPTDEV (PostScript Device plugin)
• PT_PAGEPIPE (PagePipe plugin)
• PT_COREMODULE (Core Module plugin)
• PT_EVENTBASED (Event Based plugin).

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 . Other plugin types 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.

Table 11.2 Plugin interface versions

Hence for v7.0 of the RIP pluginInterfaceMajorVersion is 18, pluginInterfaceMinorVersion is 11 (Numbers may not be incremented if no non‐backward‐compatible changes to the interface are made.)

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, first provided in version 4.1 to simplify this:

    globals->fV19RIP = CHECK_VERSION (p, 19, 0);
    p->fVersionOK = CHECK_VERSION (p, 18, 4);

This allows the plugin to run with any RIP containing plugin interface version 18.4 (RIP v6.0) or higher, and it can use the additional interface version 19.0 structure members if globals->fV19RIP is non‐zero.

The macro is not present in version 4.0, but it can be defined in exactly the same way if required, using the following code:

      #define CHECK_VERSION( _p_, _majV_, _minV_ ) \ (((_p_)->version >= 1) && \
        (((_p_)->pluginInterfaceMajorVersion > (_majV_)) || \ ((_p_)->pluginInterfaceMajorVersion == (_majV_) && \ ((_p_)->pluginInterfaceMinorVersion >= (_minV_)))))