(v13) The ChannelClassDescription structure

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

The plugin uses a ChannelClassDescription to describe a channel class to the RIP. (This is much like the device capabilities information for an output device.)

The RIP expects a ChannelClassDescription for each channel class the plugin supports. It asks for them in the D_IP_GET_CHANNEL_CLASS_DESCRIPTIONS selector call.

TEXT

      typedef struct channelClassDescription { int32 version ;
      uint8 channelClassName[ MAXCHANNELNAMELEN ] ; int32 channelClassID ;
      uint32 channelClassFlags ; int32 maxNumChannels ;
      int32 channelSizeOfPrivate ; int32 channelClassSizeOfPrivate ; int32 defaultChannelClassTickle ; int32 defaultChannelTickle ; int32 spare[4] ;
    } ChannelClassDescription ;

version (ChannelClassDescription)

Type: int32

This field contains the version number of the ChannelClassDescription structure.

If the plugin uses a field added to this structure in a particular version, it should check that the version of the structure passed is greater than or equal to that of the original version. The current version number is given by the manifest constant CHANNEL_CLASS_DESCR_VER in the header file gipdefs.h .

See (v13) Compatibility between plugin kit versions for more details about compatibility between different versions of the plugin interface.

channelClassName (ChannelClassDescription)

Type: uint8[]

The plugin fills this null‐terminated string in to name the channel class to which the description refers. The RIP prints this in the Type box of the Input Manager's (Input Controller's) New and Edit dialogs, in system monitor messages, and wherever else necessary.

Note: The encoding of the channel class name, like the name itself, will be determined by the plugin. It is the responsibility of the plugin to ensure that the encoding scheme selected is appropriate to the environment; the platform's native language encoding is recommended.

channelClassID (ChannelClassDescription)

Type: int32

The plugin sets this to the identifier it uses for the channel class among those it supports. The RIP uses this identifier for a variety of purposes, for example displaying a dialog for the channel class in response to the user clicking on the Configure button in the Input Manager.

channelClassFlags (ChannelClassDescription)

Type: uint32

A set of flags, ORed together, with which the plugin can identify properties of the channel class:

`CCF_NOT_POLLED`	The RIP will not look at the `dataAvailable` field of the `channelContext` for incoming PostScript language jobs (by default it will). This means that the channels of this class will only be used explicitly from the Post‐ Script language, not as input sources. A filter (see CCF_FILTER below) must not set this flag.
`CCF_POSTSCRIPT_MANAGED`	The channel class never appears in the Input Manager. Channels of this class can therefore only be configured by the PostScript language `setdevparams` operator.
`CCF_ASYNCHRONOUS_ACTION`	Channels of this channel class act as sources of asynchronous actions. See Asynchronous actions .
`CCF_CHANNEL_CLASS_NEEDS_TICKLE`	If this flag is set, a separate call is made periodically to the plugin's tickle function (the `D_IP_OBJECT_TICKLE` selector) with the `channelClassContext` parameter, even when there are no channels of the class instantiated, and no input or output is taking place. Otherwise, tickles are only made for individual channels.
`CCF_DO_NOT_UNLOAD`	If this flag is set, the RIP may not unload the plugin. Otherwise, the plugin may be unloaded as detailed in (v13) Dynamic plugin loading . This flag should be used when interrupt routines and the like may need to access memory independent of the selector calls.
`CCF_FILTER`	If this flag is set, that channels of this class implement a filter. See Filters .
`CCF_GROUP_CHANNEL_CREATES`	If this flag is set, channels of this class will be grouped together before their instantiation with `D_IP_CHANNEL_CREATE` . For example, a network protocol might allow several printers to be published simultaneously, but since the call takes ten seconds however many are published at once, it is worth grouping them into one call. See also `D_IP_CHANNEL_CREATE` in (v13) D_IP_CHANNEL_CREATE .
`CCF_SEEK_BY_PARAMS`	If this flag is set, the parameters `SeekPos` , `SeekSet` , `SeekIncr` , and `SeekXtnd` are passed to the channels of this class, and the channel must support them.

maxNumChannels (ChannelClassDescription)

Type: int32

The number of channels of this class that may be instantiated. If there is no particular limit, the plugin should set this to ‐1.

channelSizeOfPrivate (ChannelClassDescription)

Type: int32

The amount of memory, in bytes, that the RIP should allocate to a channel of this class when one is instantiated.

A pointer to the memory is assigned to the memory field of the channelState of the channelContext

structure. If set to zero, no memory is allocated, and the memory field is set to NULL .

channelClassSizeofPrivate (ChannelClassDescription)

Type: int32

The number of bytes the RIP should allocate for the channel class. The RIP assigns a pointer to the memory it allocates to the memory field of the channelClassState of the channelClassContext structure. If set to zero, no memory is allocated, and the memory field is set to NULL .

defaultChannelClassTickle (ChannelClassDescription)

Type: int32

If the channel class indicates in the channelClassFlags field that it needs a tickle call independent of the channel tickle calls, then the plugin sets this field to specify the minimum initial interval between tickles in milliseconds. The RIP calls the D_IP_OBJECT_TICKLE selector for the channel class as soon as is feasible each time this interval expires.

A value of ‐1 indicates that the tickle is not time‐critical: the RIP should tickle the channel class about once every second, but will not guarantee to do so.

defaultChannelTickle (ChannelClassDescription)

Type: int32

The plugin sets this to the minimum initial interval required between tickle calls for channels of this class. The RIP calls the D_IP_OBJECT_TICKLE selector for each channel of the class as soon as possible each time this interval expires.

A value of ‐1 indicates that the time between tickles is not critical: the RIP then tickles the channel twice a second while it is not open for reading (when it will always tickle as quickly as possible), but will not guarantee to do so.

On rare occasions a tickle is not possible under any circumstances. For example, a tickle is not possible while the channel is having a parameter changed, or the channel is in the process of being created or destroyed.

The channel is not tickled at all when inputs are not running, or the particular channel is not enabled.

spare (ChannelClassDescription)

Type: int32[]

Not used at present. The plugin must set the elements of this array to zero.