The irInit(3IRAPI) and irInitGroup(3IRAPI) functions support requests to gain ownership of a channel. irInit(3IRAPI) attempts to gain ownership of a particular channel, while irInitGroup(3IRAPI) attempts to gain ownership of some channel in a group. The concept of channel groups is unchanged from prior releases and groups are administered in the same way. However, the following special groups are defined with the IRAPI:

• IRD_REAL_CHANS – Includes all channels associated with a physical network connection
• IRD_VIRTUAL_CHANS – Includes all channels defined through the IRP_VIRTUAL_CHANS global parameter. Virtual channels allow applications to run on channels that are not associated with a physical network port. Virtual channels support a subset of IRAPI operations.

Gaining ownership of a channel depends on current ownership and activity. If a channel was just irExec'ed or irSubProg'ed to an application, the channel is, in effect, unowned for a short period of time. The processes receiving the IRE_EXEC event (the irExec'ed or irSubProg'ed process) should take ownership of the channel immediately via irInit(3IRAPI). The IRAPI does not allow the channel to go unowned for more than 5 seconds; if the target process does not take ownership, ownership returns to the default owner. If, after receiving an IRE_EXEC event, a process immediately calls irInit(3IRAPI) on the channel, channel ownership is granted immediately [as indicated by a return code of IRR_OK from irInit(3IRAPI)].

A process may attempt to "seize'' ownership of a channel. For example, processes may seize channels as a result of a request to start an outbound call. irInit(3IRAPI) should be used to seize ownership of a particular channel and irInitGroup(3IRAPI) should be used to seize ownership of any idle channel from a particular group.

When seizing a channel, a process must wait for channel ownership since negotiations must be carried out with the current channel owner. Therefore, a request for channel ownership not made as a result of an IRE_EXEC event returns either IRR_FAIL or IRR_PENDING.

A channel requested from another process is removed from the current owner if both of the following are true:

1. IRP_CHAN_NEGOTIATION is set to IRD_ALLOW
2. The channel is idle; that is, the service state is IRD_INACTIVE and the library state is IRS_IDLE

When a channel is taken away from a process in this manner, an IRE_CHAN_REMOVED event is sent to the previous owner.

If IRP_CHAN_NEGOTIATION is set to IRD_CONDITIONAL, the current owner receives the IRE_CHAN_REQUESTED event. The current owner may ignore the event or release the channel via irDeinit(3IRAPI) or irReturn(3IRAPI).

AD sets IRP_CHAN_NEGOTIATION to IRD_ALLOW; therefore, unless AD is dispatching a call on the channel (that is, the service state is not IRD_INACTIVE), AD gives up ownership of channels immediately upon request.

A process secures ownership of a channel when:

• irInit returns IRR_OK
• The IRE_CHAN_GRANT event is received following a return of IRR_PENDING from irInit

IRE_CHAN_DENY is returned if the current owner does not release the channel after an irInit(3IRAPI), or if no channel in the group specified with irInitGroup(3IRAPI) is released before the timeout specified in return_mode.

The outcalling version of chantest (chantest_oc.c) uses irInit(3IRAPI) to seize an idle channel.

© 2006 Avaya Inc. All Rights Reserved.