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.