The GenericPluginContext structure
This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core
A GenericPluginContext
structure is the first parameter of all input plugin calls, including plugin dialog selector calls. This means the data in this structure is available to the plugin at all times. The structure is analogous to the deviceDefinition
structure for output plugins. It is defined in the header file ggendefs.h
.
typedef struct genericPluginContext { int32 version;
void * globalState;
uint32 * timer;
plugMessageReason msgReason;
plugAnswer answer;
char * szSWDir;
char szPlgDir[GP_MAX_SUBDIR];
int32 pluginType;
} GenericPluginContext;
Note:
An equivalent to szPlgDir
(called d_PlgDir
) is also in the output plugin deviceDefinition
structure. The argument to each is a string containing the name of the directory under SW
where the plugin is located. The string is concatenated with szSWDir
to form a full path. For example, for a fictional plugin called myplug
on the PC platform, where szSWDir
might be C:\xx\SW
, szPlgDir
would be
\Devices\myplug
.
version (GenericPluginContext)
version N
Type: int32
The plugin should ignore this field. It is obsolete.
See Compatibility between plugin kit versions for more details about compatibility between different versions of the plugin interface.
globalState (GenericPluginContext)
globalState Wr
Type: void*
This is a pointer to an area of memory that the RIP maintains, even when the plugin has been unloaded.
(The plugin first informs the RIP of this pointer in response to the D_IP_PLUGIN_INITIALISE
selector call. The RIP uses the pointer to initialize this field.)
timer (GenericPluginContext)
timer Wr
Type: int32*
This field provides a timer facility. The RIP increments it at regular intervals. It can be used for any purpose.
The initial value of the field is not defined so the value is not the absolute elapsed time since the plugin, or the RIP was started up. When using the timer your plugin should record the value when the timed event starts, and compute elapsed time by the difference from that recorded value. The plugin must not change the value of this field. The units of time are milliseconds.
The timer provides the plugin with a means to carry out real‐time operations, such as tickling an AppleTalk connection - an operation necessary every two minutes.
Note: The value in this field may not be updated a millisecond at a time. (For example, it might be updated in multiples of five milliseconds.)
msgReason (GenericPluginContext)
msgReason Wr
Type: plugMessageReason
This field is used by the plugin library. The plugin should not change it.
answer (GenericPluginContext)
answer Wr
Type: plugAnswer
When the plugin asks the user a question via the plugin library mechanism, the user's answer is passed back to the plugin in this field. It can be one of the following values, defined in the enumeration plugAnswer
in gplugin.h
:
| The answer was “yes”. |
| The answer was “no”. |
| No answer received yet. |
This field does the same thing for input plugins as the d_answer
field of deviceDefinition
does for output plugins.
szSWDir (GenericPluginContext)
szSWDir Wr
Type: char
*
A null‐terminated string giving the location of the SW
directory as a platform‐dependent absolute pathname.
This field is encoded using the Harlequin character encoding scheme.
szPlgDir (GenericPluginContext)
szPlgDir[GP_MAX_SUBDIR] Wr
The pathname of the directory from which the plugin executable was loaded relative to szSWDir
, including a terminating directory separator, so the plugin can access data files by concatenating their names to the value of szPlgDir
.
This field is encoded using the Harlequin character encoding scheme.
pluginType (GenericPluginContext)
pluginType Wr
Type: int32
This field is used by the plugin library. The plugin should not change it.