irInit, irInitCancel - initialize a channel and obtain a channel ID
#include <irapi.h>
int irInit (int channel_nbr, channel_id *cid_ptr, int return_mode, int tag);
int irInitCancel (channel_id cid);
The irInit function initializes a channel specified by channel_nbr.
Except when it fails, this function sets *cid_ptr to the channel_id that is to be used by most of the other functions when referencing the channel.
return_mode indicates how the caller expects channel allocation to be handled. Allocation of channels behaves much like the allocation of other resources. The behavior determined by return_mode is summarized as follows:
tag is returned to the application with the subsequent IRE_CHAN_GRANT or IRE_CHAN_DENY event.
irInit's behavior is affected strongly by the current ownership of channel_nbr and the intent of the function call in the following two ways:
First, an application can request a channel from another process with irInit. If the channel is currently owned by another process, applications should expect a return code of IRR_PENDING, and therefore return_mode should be set to something other than IRD_IMMEDIATE. There is no hope of acquiring a channel from another process if the application is not willing to wait. The current owner indicates the availability of the channel by setting the IRP_CHAN_NEGOTIATION parameter. See subsequent paragraphs and IrPARAMETERS(4IRAPI) for more information on IRP_CHAN_NEGOTIATION. When a channel is owned by its default owner, in particular the Application Dispatch (AD) process, it is likely that the channel is granted as quickly as the library can inform AD that the channel has been removed. irInit still returns IRR_PENDING even in this case. Acquiring channel ownership in this manner is used typically, but not necessarily, to initiate an outbound call.
Second, applications should call irInit in response to IRE_EXEC events to acquire ownership for the channel. The call to irInit informs the library that the application is ready to take ownership of the channel. Since the library is ready to hand the channel to the calling processes, IRR_PENDING is not returned and return_mode may be set to IRD_IMMEDIATE without denial.
If irInit returns without error, irInit sets all channel parameters to their appropriate "save on exec" or default values. Some channel parameters are "saved on exec" and are preserved when the channel ownership has been transferred via a call to one of the irExec(3IRAPI) or irSubProg(3IRAPI) functions. The remaining parameters are set to the appropriate default value. When transfer of ownership has not occurred as the result of an irExec(3IRAPI) or irSubProg(3IRAPI) all parameters are set to their appropriate defaults.
If irInit returns IRR_OK, the channel is in the IRS_IDLE state [see IrSTATES(4IRAPI)]. If irInit returns IRR_PENDING, the channel is in the IRS_INIT_PENDING state. No voice operations are accepted for a channel_id in the IRS_INIT_PENDING state.
The application that owns the channel can control how the channel ownership passes from itself to the requester with the IRP_CHAN_NEGOTIATION parameter. This parameter can take two values: IRD_ALLOW (to allow all requests unconditionally) and IRD_CONDITIONAL (to allow the application to process the request and make a decision for itself).
If the owning application is always willing to give up the channel (that is, IRP_CHAN_NEGOTIATION is set to IRD_ALLOW), the IRAPI grants the channel to the requester, and sends a IRE_CHAN_REMOVED event to the former owner indicating that the channel has been deallocated. The application that previously owned the channel does not need to take any action to transfer ownership of the channel; however, that application must discontinue use of the channel_id it had been using for the channel.
An application that sets IRP_CHAN_NEGOTIATION to IRD_CONDITIONAL receives an IRE_CHAN_REQUESTED event when the channel it owns is requested. The application may choose to free the channel via irDeinit(3IRAPI) or irReturn(3IRAPI) or ignore the event and continue to use the channel. Part of the irDeinit(3IRAPI) and irReturn(3IRAPI) processing includes generating an IRE_CHAN_GRANT event for the requester indicating that the channel has been granted to it.
Regardless of the setting for IRP_CHAN_NEGOTIATION, if the channel is active as indicated by the library and service states, it is not taken from the current owner.
The irInitCancel function cancels a channel or group initialization request on a cid that is in the IRS_INIT_PENDING state. If the channel has already been granted, irInitCancel returns IRR_FAIL with irError set to IRER_BADSTATE. This condition may occur if the channel was granted to irWait(3IRAPI) between calls. The application should call irDeinit(3IRAPI) or irReturn(3IRAPI) upon receipt of IRE_CHAN_GRANT if ownership of the channel is no longer required.
The cid becomes invalid when irInitCancel is successful.
Multiple processes may compete for ownership of a channel. Channel ownership is granted on a first-come-first-served basis. Requests via irInit have priority over requests made via irInitGroup(3IRAPI).
The IRE_CHAN_GRANT event occurs if a call to irInit returns an IRR_PENDING value.
The IRE_CHAN_DENY event occurs if the channel cannot be granted within the time specified in the return_mode argument. The application should discontinue use of the channel_id after receiving the IRE_CHAN_DENY event.
IRR_OK is returned if the request is successful.
IRR_PENDING is returned if the channel has not yet been released by the prior application. The *cid_ptr is valid but no other functions may be called until the IRE_CHAN_GRANT event is received. This event indicates a state change from IRS_INIT_PENDING to IRS_IDLE.
IRR_FAIL is returned if an error occurs.
irError is set as follows if an error occurs:
IRER_INVALID if the channel_nbr specifies an invalid channel, return_mode is invalid, or cid_ptr is NULL
IRER_NOREGISTER, for irInit only, if the process has not previously called irRegister(3IRAPI)
IRER_SYSERROR if a system or driver call failure occurs (see irSysError for additional information)
IRER_RESOURCEBUSY if the channel is currently busy and return_mode is set to IRD_IMMEDIATE
IRER_BADSTATE, for irInitCancel, if the channel is not in the IRS_INIT_PENDING state or if the channel has been granted between calls to irWait(3IRAPI)
The following example is how to initialize a channel. Note the use of "&" before the cid argument to irInit in the following example:
int channel_nbr;
channel_id cid;
int retval;
int tag;
...
retval = irInit(channel_nbr, &cid, IRD_BLOCKFOREVER, tag);
switch (retval) {
case IRR_FAIL:
<report failure as appropriate>
break;
case IRR_OK:
irCall(cid, ...)
break;
case IRR_PENDING:
<wait for IRE_CHAN_GRANT or IRE_CHAN_DENY event>
break;
}
...
irDeinit(3IRAPI), irReturn(3IRAPI), IrPARAMETERS(4IRAPI), IrEVENTS(4IRAPI), irForceInit(3IRAPI).
Note: It is possible to configure a system where incoming and outgoing calls use the same set of ports. In this situation, an application can get a pseudo-glare condition, that is, an outbound application has acquired a channel, but has not yet initiated an outbound call. In this interval, a new call can arrive. The "right" behavior for an application is to release the channel and allow the incoming call to proceed. The application should irExec(3IRAPI) the channel back to the default owner, which is AD by default. The default owner is responsible for dispatching a new application.
This is version 12/16/02 of this man page.