D_IP_CHANNEL_CREATE

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

D_IP_CHANNEL_CREATE Selector

Parameter: ChannelCreateParam *param

Call type: Multi‐call

The RIP makes this call-in response to a channel starting up. When this happens depends on whether the channel is managed via the PostScript language. (See channelClassFlags (ChannelClassDescription) .)

Channels not managed via the PostScript language are started up if one of the following is true :

• Start Inputs is selected. (In which case all enabled channels are created.)
• Inputs are already running, and a new channel is turned on.
• The RIP starts with its inputs already turned on.

Channels managed via the PostScript language start up when the PostScript language device’s DeviceType parameter is set to 15 with setdevparams , having previously been mounted with the devmount operator.

The D_IP_CHANNEL_CREATE call is the point at which a channel becomes responsive to input from the outside world. It may involve publishing printer names in some directory (UNIX), registry (in Windows) or name binding service (AppleTalk), according to the kind of input it services. If required, the plugin can also set up interrupt handler hardware at this point.

Sometimes, more than one channel of a certain class is to be created during the call. This happens if CCF_GROUP_CHANNEL_CREATES in the ChannelClassDescription structure is set: all channels of the class are grouped together to be created in one call. (See channelClassFlags (ChannelClassDescription) ) You might want to do this if, for example, a network protocol allows several printers to be published simultaneously, but the call takes ten seconds however many are published at once. In such a case it is worth grouping all channel instantiations into one call.

When such a multiple channel instantiation occurs, the fields groupSize , processed and groupStatus are used to say how many channels have been processed and when. On each consecutive call within one multi‐call, a new channel is passed to the plugin, out of a total of groupSize . On each occasion, the plugin can use the processed field to indicate how many of the accumulated channels it has dealt with (either successfully or not; the plugin normally builds up a list until it is ready to handle a complete group).

If there are no more channels to create, the multi‐call continues, with channelContext set to NULL until the multiple‐create completes.

      typedef struct channelCreateParam { int32 version ;
      int32 channelClassID ; ChannelContext *channelContext ; MultiCallData multi ;
      IPStatus status ;
      int32 groupSize ;
      int32 processed ;
      IPStatus groupStatus ;
    } ChannelCreateParam ;

version

The version field should be ignored.

channelClassID

The identifier of the channel class for the channel to which this call refers. This identifier is as returned in the channel class’s ChannelClassDescription during the D_IP_GET_CHANNEL_CLASS_DESCRIPTIONS multi‐call.

channelContext

A pointer to data the RIP holds about the channel. The channelName field can be used as a name under which to publish the printer. The memory field of the channelState in this structure is set to point to memory the plugin requested in the ChannelClassDescription for the channel class to which this channel belongs. The channelSTIOData contains the channel’s parameters.

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 to IPS_OK if the call is successful and IPS_FAIL otherwise.

groupSize

When the CCF_GROUP_CHANNEL_CREATES channel class flag is set, the RIP sets this value to the number of channels waiting to be created in one or more combined operations. It is incremented as each channel is introduced to the plugin (as described above), and as the plugin consumes channels, the number of channels, shown by processed , is subtracted from it. The multi‐call continues until the groupSize reaches zero or an error occurs.

processed

When the CCF_GROUP_CHANNEL_CREATES channel class flag is set, the plugin should set processed to the number of channels that have been successfully created during that single call. As channels are accumulated in the plugin, awaiting creation, and while creation is taking place (since that is likely to be a time‐consuming operation for it to be worthwhile using this grouping mechanism), the value remains zero, which is what the RIP sets it to before each call.

groupStatus

When the CCF_GROUP_CHANNEL_CREATES channel class flag is set, the plugin can set the IPmajor field of this IPStatus structure to IPS_FAIL to indicate that the channels shown as having been processed during this call could not be created.

The RIP initializes groupStatus.IPmajor to IPS_OK before each call. For example, if the third of six channels could not be created, on the first call the plugin would set processed to 2 with groupStatus.IPmajor left as IPS_OK . On the second call, processed would be 1 with IPS_FAIL , and on the third call processed would be 3, for the remaining successful channels, with IPS_OK .

In this way, the plugin can indicate during group creation that a particular channel could not be created, providing it keeps a record of the order in which the channels were supplied.