(v13) D_IP_OBJECT_TICKLE

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

D_IP_OBJECT_TICKLE Selector

Parameter: TickleParam *param

Call type: Single‐call

This is the main call available to a channel or channel class for interaction with the outside world. It is from here that data is transferred to the RIP via the plugin, and also where jobs are noticed to be arriving.

Once a channel has been created, D_IP_OBJECT_TICKLE calls are made to it, at intervals determined initially by the defaultChannelTickle field of the channelClassDescription structure.

If the channel receives PostScript language jobs, D_IP_OBJECT_TICKLE will mainly need to monitor the channel for incoming data and set the channelContext ’s dataAvailable field when some arrives.

However, it may also need to respond to status requests, depending on the protocol of the input device. (Channel classes may also ask to be tickled if necessary. This is done by setting the CCF_CHANNEL_CLASS_NEEDS_TICKLE flag in the ChannelClassDescription structure.)

Once the channel is open, the tickles become more frequent: they occur as frequently as the RIP can possibly make them. Data is transferred to and from the RIP as it becomes available. This is done using the plugin library calls to access the dataInBuffer and dataOutBuffer of the channelContext . See (v13) Input and filter plugin buffer access functions .

When the plugin detects end‐of‐file status in its data it sets the status code IPS_EOF in the

dataInStatus field of the channelContext . Once the RIP has emptied the buffer, it closes the channel.

A filter plugin both takes data from the dataOutBuffer and puts it into the dataInBuffer , using plugin library calls discussed in (v13) Input and filter plugin buffer access functions to do so. It

detects that there is no more data to be transformed by checking for IPS_EOF in the dataOutStatus of the channelContext .

TEXT

      typedef struct tickleParam { int32 version ;
      int32 objectType ;
      void *objectContext ; IPStatus status ;
    } TickleParam ;

version

The version field should be ignored.

objectType

The RIP sets this field to indicate that the call refers to a channel with OBJTYPE_CHANNEL , or to a channel class with OBJTYPE_CHANNELCLASS . Calls are only made for a channel class if the CCF_CHANNEL_CLASS_NEEDS_TICKLE flag of the channelClassDescription structure is set.

objectContext

If the call refers to a channel (objectType is OBJTYPE_CHANNEL ) this is a pointer to the channelContext structure for the channel. If the call refers to a channel class (objectType is OBJTYPE_CHANNELCLASS ) this is a pointer to the channelClassContext structure for the channel class.

status

The plugin must set the IPmajor field of this IPStatus structure to IPS_OK .

Note: It must not set this field to indicate a read or write error or end‐of‐file for a channel. This is done by setting the dataInStatus or dataOutStatus field of the channelContext structure.