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.