(v13) Selectors involved in error handling

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

D_CLEAR_ERROR and error handling

D_CLEAR_ERROR Selector

Parameter: a NULL pointer

The RIP calls this selector whenever the plugin reports an error.

If the plugin can clear the error, it should do so. It should at least test whether the condition that caused the error still exists, and modify the d_error field in the deviceDefinition on the basis of this test if necessary.

D_CLEAR_ERROR is called whenever the error status changes. Therefore, as well as in the places shown in (v13) Abort output and write text , it is also called at some point after the error is cleared, when the state has changed from some error to no error.

In general, the plugin should do nothing with an error code of DERR_NONE .

With some error types, the RIP may repeat this call until the error has been cleared. It calls it a final time when it detects the change in d_error back to normal, that is

DERR(DETYPE_CONTINUE, DERR_NONE)

D_ERROR_TEXT and error handling

D_ERROR_TEXT Selector

Parameter: devErrorTextParam * error

The RIP calls this selector to obtain a character string containing message text for the error code reported in d_error . The message is displayed in the Output Controller.

If the plugin can provide no text for the error code, it should return ‐1. The RIP then tries to find text of its own corresponding to the error code. If it fails to do so, it uses the text for the “unknown” error, which it retrieves from the RIP's messages file. It asks the plugin for its version of this first, with another D_ERROR_TEXT call, and if no text is supplied uses its own. All error messages can be localized. For more information see the Localization Kit documentation.

      typedef struct devErrorTextParam { int32 e_code;
      char *e_text;
    } devErrorTextParam;

e_code for D_ERROR_TEXT

The RIP sets this to the error code from the error report to which this call is a response.

e_text for D_ERROR_TEXT

The plugin should copy the characters of its error message into the string pointed to by e_text . It can be up to 256 bytes long, including the null terminator. The plugin should copy the string, and not assign to the pointer. (However, for backward compatibility, this selector will work if the pointer is assigned.)

D_ERROR_ICON and error handling

D_ERROR_ICON Selector

Parameter: devErrorIconParam * error

The RIP calls this selector to obtain an icon for the error code reported in d_error . The icon is dis‐ played in the Output Controller.

If the plugin can provide no icon for the error code, it should return ‐1. The RIP then tries to find an icon of its own corresponding to the error code. If it fails to do so, it will use the icon for the “unknown” error, DERR_UNKNOWN . It asks the plugin for this, with another D_ERROR_ICON call, and if no icon is supplied uses its own.

Note: On the Macintosh, the plugin also looks for the icon resource (see “Handling code and other resources on Mac OS X” ) if this selector is not supported.

      typedef struct devErrorIconParam { int32 version;
      int32 e_code;
      IconId e_icon;
    } devErrorIconParam;

version for D_ERROR_ICON

The plugin should ignore this field. It is obsolete. Instead, perform version checking with the

CHECK_VERSION macro in the D_GET_IDENTITY call, and use that result throughout.

e_code for D_ERROR_ICON

The RIP sets this to the error code from the error report to which this call is a response.

e_icon for D_ERROR_ICON

This is a structure, IconId , whose contents depend on the platform.

Windows versions use icons in resources created by a dialog editor such as Microsoft's AppStudio or Apple's ResEdit, identified by a single number. High‐color 32 x32 pixel icons for Windows may be created outside AppStudio, and compiled into the plugin.