(v13) D_GEN_SECURITY_NAME (core module plugins)
This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core
D_GEN_SECURITY_NAME Selector
Parameter: devSecurityNameParam * SecurityNameParam
The RIP or the plugin may require a password before enabling the use of a plugin, as described for D_GEN_PASSWORD_PROTECTED
in (v13) D_GEN_PASSWORD_PROTECTED (core module plugins)
. Implementing this selector allows you to choose the option name presented when requesting a password from the user and possibly to reduce the number of passwords required from the user when enabling related modules.
Note:
D_GEN_SECURITY_NAME
relates to the instance referenced in the most recent call to an ENUMER‐ ATE selector. That is, if the RIP has called D_HTM_ENUMERATE(1)
followed by D_GEN_SECURITY_NAME
the returned value will be relevant to instance 1 of the Screening Core Modules, not to the whole plugin.
When the security device or a prior call to D_GEN_PASSWORD_PROTECTED
indicates that the plugin requires a password, the RIP calls this selector once for each core module enumerated by
the plugin.
The possibilities are:
- The plugin does not support this selector.
- The plugin module can return plugin and security names that the RIP will use when asking for a password.
If this selector is not implemented, the RIP generates the plugin and security names for itself.
- The plugin name is derived in a platform‐specific way - from the filename on PC platforms (for example,
htm_plug.i32
). - The security name is the name field returned during the instance's enumeration, in the
sw_api_info
portion of the sw_htm_api
structure:
/* Required first member for all APIs. */ typedef struct sw_api_info {
sw_api_version version ; const uint8 *name ;
const uint8 *display_name ; size_t instance_size ;
} sw_api_info ;
If the plugin supports this selector, the RIP will call it once for every module enumerated by the plugin after calling D_HTM_ENUMERATE
. As D_GEN_SECURITY_NAME
does not have an index parameter, the plugin must remember the index value passed in the CoreModuleEnumerateParam
structure during the preceding D_HTM_ENUMERATE
call, if you wish to use different passwords for different modules.
If this selector returns NOERR
, the plugin has a composite security name, returned using the parameter described here:
#define SECURITY_NAME_STRLEN 32
typedef struct devSecurityNameParam {
uint8 atbzPluginName [SECURITY_NAME_STRLEN]; uint8 atbzSecurityName[SECURITY_NAME_STRLEN];
} devSecurityNameParam;
Each distinct value of this parameter produces a separate entry, visible in the Extras dialog box in the RIP and requiring a password to enable the relevant plugins or modules. By choosing appropriate (shared) values for the names described in atbzPluginName and atbzSecurityName, you can produce groupings of plugins, modules, or both; all represented by one entry.
However, you choose the names, you must declare all the names to Global Graphics so that suitable passwords can be supplied.
To ensure the security of your plugin, you must also supply a copy of the plugin file so that Global Graphics can protect the plugin against subsequent tampering, and then return the protected plugin to you for issue to your customers
atbzPluginName
To create a unique entry for each module, the plugin should copy the module name into this string. To create an entry that groups related modules, the plugin should enter a more generic shared name.
atbzSecurityName
To create a unique entry for each module, the plugin should copy the module name for a multiple module plugin into this string. To create an entry that groups related modules, the plugin should enter a more generic shared name.
Note: A core module can indicate that it does not require a password by using “Free Module” as its security name.
Enabling options in the Extras dialog box
For each composite security name used by the installed plugins, a new entry appears in the Extras dialog box accessed from the Configure RIP dialog box. This entry takes the general form:
<Plug-in Name>, <Security Name>
The <Plug-in Name>
and the <Security Name>
are the values of atbzPluginName
and
atbzSecurityName
, respectively.
If the user selects an entry for a module (or modules) and clicks Add, the RIP prompts the user for a password, as with other Extras features. Provided that the password is correct, the RIP enables the module(s).
The RIP's table will cover all existing protected plugins, so existing plugins do not need to be modified to implement this selector in order to work with an LDK enabled RIP. If a plugin implements this selector, its LDK feature number overrides any value in the RIP's table.
If the plugin supports this selector, the RIP will call it once for every module implemented by the plugin, after calling D_FIND_DEVICE
. At this point the d_capabilities
field of the deviceDefinition
is not filled in, so the plugin must remember the device identifier itself if the same names are not being used for all of the devices in the plugin.
If this selector returns NOERR
, the plugin has a feature number, returned using the parameter described here:
typedef struct devSecurityFeaatureNumberParam { uint32 nFeatureNumber;
} devSecurityFeatureNumberParam;
Each distinct value of this parameter should correspond one‐to‐one with the option names returned by the D_GEN_SECURITY_NAME
selector, so that a different LDK feature is required to enable the plugins or device types corresponding to each entry in the Configure RIP Extras dialog box in the RIP.
The LDK feature numbers to use are allocated by Global Graphics, so as to avoid a clash between two plugins choosing to use the same number. You should use your usual support channel if you want to be allocated feature numbers.
To ensure the security of your plugin, you must also supply a copy of the plugin file so that Global Graphics can protect the plugin against subsequent tampering, and then return the protected plugin to you for issue to your customers.