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 :

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.