(v13) The ChannelContext structure

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

Whenever a selector call pertains to a channel, the RIP passes this structure as a parameter. It gives the channel class the channel belongs to as well as data associated with the channel class.

TEXT

      typedef struct channelContext { int32 version ;
      int32 channelClassID ;
      uint8 *channelName ;
      PluginState  channelState ; ChannelClassContext *channelClassContext ; void *channelSTIOData ;
      PLUGIN_BUFFER dataInBuffer ;
      PLUGIN_BUFFER dataOutBuffer ;
      IPStatus dataInStatus ;
      IPStatus dataOutStatus ;
      int32 dataAvailable ;
      SWStatus swStatus ;
      uint32 flags;
      int32 spare1, spare2;
    } ChannelContext ;

version (ChannelContext)

version N

Type: int32

The plugin should ignore this field. It is obsolete.

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

channelClassID (ChannelContext)

Type: int32

The identifier of the channel class of which this channel is an instance. The identifier is as returned from the D_IP_GET_CHANNEL_CLASS_DESCRIPTIONS call in the ChannelClassDescription structure.

channelName (ChannelContext)

Type: uint8*

The name of the channel. This comes either from the Input Manager's New or Edit dialogs, if the user named the channel, or from the device if mounted explicitly from a PostScript language fragment.

The plugin need not use the name at all. For example, it might not do so if the channel is a serial line. But the name can be useful on other occasions, for example to use as a printer name to be published on a network.

This field is encoded using the Harlequin character encoding scheme.

channelState (ChannelContext)

Type: PluginState

A reference to the memory allocated in response to the channelSizeOfPrivate field of the

ChannelClassDescription structure. See PluginState in (v13) The PluginState structure .

channelClassContext (ChannelContext)

Type: ChannelClassContext*

A reference to the channel class information as described in (v13) The ChannelClassContext structure for the class of which this channel is an instance.

Note: The channelClassID s in this structure and in the channelClassContext to which it refers are the same.

channelSTIOData (ChannelContext)

Type: void*

The plugin parameter data for the channel. This data represents values entered by the user in the Input Manager's Configure dialog, or set with the PostScript language setdevparams operator. See (v13) Input and output plugin parameters and plugin dialogs for details of how this field is used.

dataInBuffer (ChannelContext)

Type: PLUGIN_BUFFER

This structure is used to move the data arriving on the channel from the plugin to the RIP, and is writ‐ ten indirectly by the plugin during a tickle call.

Warning: Its fields should never be accessed directly, but only via the plugin library calls of the form PluginLib_ip_in_... provided for this purpose. See (v13) Functions for sending input to the RIP for details.

dataOutBuffer (ChannelContext)

Type: PLUGIN_BUFFER

This structure is used to move the data stream for the channel from the RIP to the plugin during a tickle call.

Warning: Its fields should never be accessed directly, but only via the plugin library calls of the form PluginLib_ip_out_... provided for this purpose. See (v13) Functions for receiving output from the RIP for details.

dataInStatus (ChannelContext)

Type: IPStatus

The plugin sets this in the tickle call, to show the validity of data in the dataInBuffer . It is an IPStatus structure as described in (v13) The IPStatus structure . The plugin should set the IPmajor field as follows:

`IPS_OK`	If there is any data in the buffer, it is valid. (The RIP sets this as the default value before passing the structure in the call.)
`IPS_EOF`	Once the buffer has been emptied, the channel has reached its end of file, and the job is to terminate, or the PostScript language file is to close.
`IPS_FILTER_DATA`	When implementing a PostScript language filter, the plugin always receives data in the `dataOutBuffer` and writes it into the `dataInBuffer` . The plugin sets `IPmajor` to this value when it requires more data from the RIP before it can return any more data to the `dataInBuffer` . The RIP resets the status to `IPS_OK` once it has done so.
`IPS_INTERRUPTED`	The plugin has detected that it must stop prematurely and that the RIP must stop processing this channel. This usually results in a PostScript language `interrupt` error. For example, this situation might happen in AppleTalk if the user aborts the job by pressing Command‐. (Command‐period) on the Macintosh sending the data.
`IPS_READ_ERR`	Some error has been detected, and the plugin is incapable of dealing with it. This usually results in a PostScript language `ioerror` error.

dataOutStatus (ChannelContext)

Type: IPStatus

The plugin sets this in the tickle call to show whether it can deal with data in the dataOutBuffer correctly. The plugin should set the IPmajor field as follows:

`IPS_OK`	The plugin is able to accept data in the `dataOutBuffer` . The RIP will initially set the status to this value.
`IPS_INTERRUPTED`	The plugin has detected that it must stop prematurely. This will usually result in a PostScript language `interrupt` error.
`IPS_WRITE_ERR`	Some error has been detected, and the plugin is incapable of dealing with it. This usually results in a PostScript language `ioerror` error.

dataAvailable (ChannelContext)

Type: int32

The plugin sets this field during a tickle call (see (v13) D_IP_OBJECT_TICKLE ) to tell the RIP that there is a job ready to be processed on this channel.

It is only relevant if the CCF_NOT_POLLED flag is set in the channelClassFlags of the channelClassDescription structure.

If the CCF_ASYNCHRONOUS_ACTION flag is set in the channelClassFlags , the job is processed as an asynchronous action (see Asynchronous actions ). Otherwise, it is treated as an ordinary job.

The RIP sets the field to zero when the channel is enabled, and whenever a job is completed. When the channel tickle call detects that the channel is ready to send data to the RIP, the plugin should set the field to a non‐zero value.

If the plugin does not know in advance how much data is expected, dataAvailable should be set to a negative value. In these cases, the progress dial that usually shows the proportion of the job completed just shows the amount of data received.

If the plugin does know in advance how much data will be sent, dataAvailable should be set to that value, in bytes. In such cases, the progress dial will show the proportion of the job completed.

Once set, the plugin should not change dataAvailable until the job has been processed.

swStatus (ChannelContext)

Type: SWStatus

Contains information about the state of the interpreter, which can be passed back to the originator of the data arriving on the channel. For example, this could be used to implement Control‐T status requests on a serial line. This structure is explained in more detail in (v13) The SWStatus structure .

flags (ChannelContext)

Type: uint32

This field is comprised of a set of 1‐bit flags indicating status conditions which the plugin should handle as described below. It can be tested by ANDing with the following values:

CHANNELCONTEXTFLAG_WILLSTOP

The RIP sets this flag if the channel is going to shut down shortly: when the job in progress, if any, has finished. The input plugin should take this as an indication that it should not run any more jobs once it has completed the jobs it is already committed to running.

The plugin must ensure that CHANNELCONTEXTFLAG_WILLSTOP is clear before polling for a job.

If the plugin can detect jobs without committing itself to running them, and CHANNELCONTEXTFLAG_JOB is clear, it is permitted to clear dataAvailable , to avoid running any job it has already detected when the input queue is being shut down.

Caution: If CHANNELCONTEXTFLAG_WILLSTOP is not tested, a condition can arise where the channel will not shut down because there is a continuous stream of jobs being signaled as ready to run. When the RIP quits, this may cause an untidy, forced shutdown.

CHANNELCONTEXTFLAG_JOB

The RIP sets this flag once it has detected that an input plugin has set dataAvailable , and has decided that it will take this plugin as the source of its next job. The flag remains set for the duration of the job. While this flag is set, the input plugin should not set dataAvailable to zero, except when aborting the job.

spare1, spare2 (ChannelContext)

Type: int32

Not used at present.