D_IP_CHANNEL_OPEN

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

D_IP_CHANNEL_OPEN Selector

Parameter: channelOpenParam *param

Call type: Multi‐call

The RIP makes this call to tell the plugin to prepare to read or write data from or to the channel. This is usually done in response to a PostScript language file operator, which, in the case of an incoming job, will have been caused by the plugin setting the dataAvailable field of the channelContext belonging to this channel. (It is possible for a plugin to be opened for both reading and writing in one call.)

A file opened explicitly from a PostScript language fragment can be opened for reading, writing or both. However separate “open” calls are made for both reading (which normally succeeds) and writing. In this case, if the plugin fails to open the channel in the writing direction (returning IPS_WRITE_NOT_AVAIL ), data is written to the monitor window instead. This allows data such as PostScript language error messages to be returned to the sender of the job if a return channel is available, or to the monitor window if not.

Only after a successful “open” call, and before the plugin receives any other calls, will the appropriate PLUGIN_BUFFER structures be initialized in the channelContext . Hence the plugin should not attempt to place any data into the dataInBuffer , or read any from the dataOutBuffer during the “open” call itself.

See D_IP_OBJECT_TICKLE for details of how to indicate that the data has reached the end of file on reading.

TEXT

      typedef struct ChannelOpenParam { int32 version ; ChannelContext *channelContext ; uint32 openFlags ; MultiCallData multi ;
      IPStatus status ;
    } ChannelOpenParam ;

version

The version field should be ignored.

channelContext

A pointer to data the RIP holds about the channel. In particular the channelSTIOData may need to be consulted to determine parameter settings for the channel.

openFlags

The RIP sets this field to indicate whether the channel is to be opened for reading, writing, or both. It should be set to COF_READ , or COF_WRITE , or both ORed together, respectively.

Separate open calls are usually made for a channel used for reading and writing. Only when explicitly opened as (r+) or (w+) from a PostScript language fragment would both flags be set.

multi

Controls the sequence of calls to the selector. See The MultiCallData structure .

status

The plugin should set the IPmajor field of this IPStatus structure as follows:

`IPS_OK`	The call was successful. This is the only return code from which the RIP will proceed to process data through the channel.
`IPS_READ_NOT_AVAIL`	`COF_READ` was set in `openFlags` , but the channel does not support reading.
`IPS_WRITE_NOT_AVAIL`	`COF_WRITE` was set in `openFlags` , but the channel does not support writing.
`IPS_READ_ERR`	`COF_READ` was set in `openFlags` and the channel supports reading, but there is some error preventing the channel from being opened for reading.
`IPS_WRITE_ERR`	`COF_WRITE` was set in `openFlags` and the channel supports writing, but there is some error preventing the channel from being opened for writing.
`IPS_READ_AND_WRITE_ERR`	Both `COF_READ` and `COF_WRITE` were set and the channel supports both reading and writing, but errors prevent the channel being opened for both simultaneously.