Filter channel events

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

The sequence of events for creating a filter channel is as follows.

When a PostScript language job uses the filter operator to start a filter that is implemented by an input plugin, for example:

/MyNameDecode << ... >> filter

parameters for the filter set in the dictionary operand of the filter operator are passed to the plugin using the D_IP_SETPARAMS selector.

The name of the channel is implicitly defined by the filter operator to be the same as the name of the channel class, which is also the name of the PostScript language filter.

The plugin receives an open request from the RIP with the D_IP_CHANNEL_OPEN selector. Only one D_IP_CHANNEL_OPEN selector call is made for decode filters this is for reading, and for encode filters this is for writing. The RIP determines which from the FilterType key in the defineresource opera‐ tor.

Note: It is not possible to have a filter open for both reading and writing. As noted earlier, encoding and decoding operations for a format should be implemented in two separate filters.

The plugin is continuously given time with D_IP_OBJECT_TICKLE selector calls from the RIP. Once open, it can assert that it requires some data to operate on by setting the dataInStatus field of the channelContext structure given to the tickle to IPS_FILTER_DATA . See dataInStatus (ChannelContext) .

Sometime later, data becomes available in the dataOutBuffer of the channelContext , detected during a tickle. (For example, using the plugin library call PluginLib_ip_out_available_total . See PluginLib_ip_out_available_total ). The plugin consumes the data in the buffer (accessed through other PluginLib_ip_out ... library calls) and puts the result into the dataInBuffer .

The plugin may have to use an intermediate buffer allocated by the RIP when the channel is created (according to the channelSizeOfPrivate field of the channelClassDescription see channelClassSizeofPrivate (ChannelClassDescription) ) if the result can only be determined when a sequence of input bytes is available, or if there is not enough room in the dataInBuffer to write the result.

Take care not to end up in deadlock, with the plugin waiting for a sequence of bytes that cannot be provided because the RIP is waiting for the plugin to consume some other data.

When the RIP has no more data to send to the plugin, it sets the dataOutStatus to IPS_EOF (it is normally set to IPS_FILTER_DATA ). The plugin must empty the dataOutBuffer before it signals completion by setting dataInStatus to IPS_EOF .

The plugin then receives a D_IP_CHANNEL_CLOSE call to close the channel.