(v13) The DICTSTRUCTION structure

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

DICTSTRUCTION Structure

The plugin uses this structure to describe a plugin parameter. The RIP maintains an array of DICTSTRUCTION structures, one for each parameter the plugin supports. The plugin passes a DICTSTRUCTION back to the RIP with each D_GETSTIOTEMPL call. See (v13) D_GETSTIOTEMPL .

For output plugins, in PostScript language code, these parameters are added to the pagedevice dictionary before a job is run. They may also optionally be made available for user modification in a plugin dialog, and saved by the RIP in the SW folder.

For input plugins, parameters become PostScript language device parameters (since input plugins are represented as devices in the PostScript language). They can be manipulated by the setdevparams operator, and, optionally, by the user from the Input Manager.

The DICTSTRUCTION does not contain the parameter values itself. Instead, it contains offsets into an associated area of memory, usually a structure defined for the purpose. On platforms where it is possible, the array of DICTSTRUCTION structures is usually just written out as a static structure. See also the note under the field struction_name about copying DICTSTRUCTION structures.

This structure is defined in the header file gdevstio.h .

TEXT

    typedef struct dictstruction {
        int32 struction_type;
        uint8 *struction_title;
        uint8 *struction_prefix;
        uint8 *struction_name;
        int32 struction_offset;
        int32 struction_size;
        int32 struction_data;
        int32 struction_min,
        int32 struction_max;
        int32 reserved1;
        int32 reserved2;
        int32 reserved3;
        int32 reserved4;
    } DICTSTRUCTION;

struction_type

This field describes the type of the parameter being defined. It may be one of the following;

`STIO_BOOL`	A 32‐bit boolean value, `true` or `false` .
`STIO_INT`	A 32‐bit integer value.
`STIO_FLOAT`	A 32‐bit floating point value.
`STIO_INLINE_STRING`	A null‐terminated string of characters (a `uint8` string).
`STIO_END`	The end of an array of `DICTSTRUCTION` structures.

struction_title

This field is for the RIP's internal use only.

struction_prefix

This field is for the RIP's internal use only.

struction_name

This field points to a string which gives the name of the parameter being defined. This is a literal name in the PostScript language sense and must start with a “/ ”. It must be unique within the DICTSRUCTION .

Note: The memory for this string is allocated by the RIP and the string is copied into it. It would be convenient to write a static definition of a DICTSTRUCTION array and then try to copy it to the RIP on request, but this does not work. Doing so would copy a pointer to the string, which would then be in a possibly different address space. The plugin library function PluginLibStioFixup is provided to copy the structure and everything it points to safely. See (v13) PluginLibStioFixup for details.

struction_offset

The offset, in bytes, into the area of memory containing the values of the parameters defined by the DICTSTRUCTION . The Stio_Offset macro provides an easy way to obtain this value.

struction_size

The declared size of the structure member's data area, in bytes. Declarations for strings should include an allowance for the terminating \0 . It is currently only used for strings, since other types have an implicit length.

struction_data

This field contains flags, defined in gdevdlg.h , affecting how the RIP handles the parameter defined by the DICTSTRUCTION . The plugin can construct a value for this field with the following flags and the bitwise‐OR operator, | .

Note: For many parameters, the plugin will not need to set this field to anything other than zero. The flags are as follows:

`SF_CONSTANT`	The parameter cannot be changed by the user and therefore need not be stored in the `SW` folder.
`SF_INPUTATTRIB`	The parameter is an input attribute and, as well as being stored in the `pagedevice` dictionary, should also be flagged as a Media Selection Key and stored in the `InputAttributes` dictionary. Note: This flag must not be combined with the `SF_OUTPUTATTRIB` flag.
`SF_OUTPUTATTRIB`	The parameter is an output attribute, and as well as being stored in the `pagedevice` dictionary, should also be flagged as a Media Selection Key and stored in the `OutputAttributes` dictionary. Note: This flag must not be combined with the `SF_INPUTATTRIB` flag.
`SF_POSTSCRIPT`	The parameter, which must be of type `STIO_INLINE_STRING` , defines a piece of PostScript language code to be executed immediately before any job associated with the plugin.

struction_min, struction_max

The minimum and maximum valid values for numeric parameters. They don't apply to any other types. The RIP checks the values the user enters against this range, to make sure that they are valid.

These integer values are used only for testing integer and floating point values. This means the valid range for floating point values is defined by integer, and not floating point, values.

reserved1, reserved2, reserved3, reserved4

Not used at present. Reserved for future use.