(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.