NAME
irCall - place a telephone call with call progress detection
SYNOPSIS
#include <irapi.h>
int irCall (channel_id cid, int tag, const char
*dial_string);
DESCRIPTION
The irCall function places a telephone call to dial_string
on the channel specified by cid. irCall automatically places
cid in the IRD_ACTIVE channel service state.
The tag is a user-supplied number that associates the irCall
with a subsequent event.
The dial_string is the telephone number of the call destina-
tion. Valid values for dial_string are listed in
IrDIALSTRINGS(4IRAPI). irCall can be used on TipRing chan-
nels to take the channel offhook and resolve glare without
actually dialing a number by calling irCall with the
dial_string equal to the NULL string, and the
IRP_OUTCALL_CCALEVEL set to IRD_BLIND_CCA. In this case,
irCall will return the appropriate event after detecting
dialtone or detecting glare.
The irCall function monitors call progress via Call Classif-
ication Analysis (CCA). Intermediate CCA results are
returned to applications via IRE_CALL_PROG or
IRE_DISCONNECT_TONE events [see IrEVENTS(4IRAPI)]. Unlike
irDial(3IRAPI), irCall will automatically start and stop CCA
as needed [see irCCA(3IRAPI)].
IRAPI library parameters IRP_RESOURCE_RETURNMODE,
IRP_OUTCALL_DIALTYPE, IRP_OUTCALL_CCALEVEL,
IRP_OUTCALL_ANSDET, and IRP_OUTCALL_MAXRINGS [see
IrPARAMETERS(4IRAPI)] affect operation of irCall.
IRP_RESOURCE_RETURNMODE indicates what to do when resources
are not immediately available. IRP_OUTCALL_DIALTYPE defines
type of dialing to be used. Dialing types supported are
IRD_DIALTYPE_DP (dial pulse), IRD_DIALTYPE_TT (touch tone)
and IRD_DIALTYPE_MF (multiple frequency; for future use
only). IRP_OUTCALL_CCALEVEL specifies the CCA level
(IRD_BLIND_CCA, IRD_SIMPLE_CCA, IRD_FULL_CCA) to be used for
CCA. Blind CCA does no call classification. Simple CCA is
done on the telephony board itself while full CCA requires
an SP card. IRP_OUTCALL_ANSDET indicates how to detect that
a call has been answered when Full CCA is being used.
IRP_OUTCALL_MAXRINGS specifies number of rings to wait for
an answer after dialing. If there is no answer within
IRP_OUTCALL_MAXRINGS number of rings, an IRE_CALL_DONE event
with an event modifier of IREM_NOANSWER is generated.
Existing values of these parameters can be retrieved using
irGetParam(3IRAPI) while a new value can be assigned to them
using irSetParam(3IRAPI). Default IRP_RESOURCE_RETURNMODE
is IRD_IMMEDIATE, IRP_OUTCALL_DIALTYPE is IRD_DIALTYPE_TT,
IRP_OUTCALL_CCALEVEL is IRD_BLIND_CCA, IRP_OUTCALL_ANSDET is
IRD_DEFAULT, and IRP_OUTCALL_MAXRINGS is 5.
WARNING: The parameters described above must be changed
before calling irCall or after receiving the IRE_CALL_DONE
event. Changing them while a call attempt is in progress
can lead to unexpected results.
Calling irStop(3IRAPI) aborts (if possible) a call attempt
that is in in the IRS_CALL_PENDING state after irCall has
returned IRR_PENDING. Applications can also call irStop
then irDisconnect(3IRAPI) to stop a call attempt in the
IRS_CALLING state after irCall has returned IRR_OK (but
before the IRE_CALL_DONE event is received). Depending on
the telephony type, the irStop may not be able to terminate
the call attempt before the IRE_CALL_DONE event is returned.
The irDisconnect(3IRAPI) function must be called to ter-
minate a call after the IRE_CALL_DONE event has occurred.
The application must call irDisconnect before attempting
further calls even if the modifier to IRE_CALL_DONE indi-
cates that the call was not completed (IREM_BUSY, etc.) or
that an error occurred (IREM_ERROR). The application must
also call irDisconnect before attempting further calls after
receiving an IRE_DISCONNECT event. The IRAPI library
automatically performs the irDisconnect when a channel is
being de-initialized with irDeinit(3IRAPI) or
irReturn(3IRAPI)
Invocations of irCall cannot be intermixed on the queue with
any other voice processing functions.
The channel will go to the IRS_CALL_PENDING library state if
waiting for CCA or other resources. It will go to the
IRS_CALLING library state while waiting for the
IRE_CALL_DONE event.
EVENT
Intermediate call results are returned to an application via
IRE_CALL_PROG or IRE_DISCONNECT_TONE events with event
modifiers that provide more information about the status of
the call. Final call results are returned to the applica-
tion via the IRE_CALL_DONE event with event modifiers that
report the disposition of the call. In some cases, addi-
tional IRE_CALL_PROG events may occur after the
IRE_CALL_DONE event.
An IRE_CALL_DONE event with an IREM_GLARE event modifier may
occur if there is already an incoming call on the cid. The
recommended action is to call irExecDefOwn with the
IRD_AD_STARTUP argument to release the channel and to then
allow the Application Dispatch process to pass the call to
an application that will answer the incoming call. In gen-
eral, the application receiving the IRE_CALL_DONE with
IREM_GLARE should attempt the outbound call on another chan-
nel.
An IRE_CALL_DONE event with an IREM_COT event modifier may
occur if SS7 continuity testing prevented the outbound call
from succeeding on the cid. In general, the application
receiving the IRE_CALL_DONE with IREM_COT should attempt the
outbound call on another channel. The current channel
should be released by calling irDeinit and continuity check-
ing will continue to occur on that channel. The IREM_COT is
not necessarily an indication of service affecting problems
within the voice system or it's connection to the SS7
switch, so no alarm should be generated by the application
receiving this event.
RETURN VALUE
IRR_OK is returned if irCall is successfully initiated.
IRR_PENDING is returned if resources are currently not
available and IRP_RESOURCE_RETURNMODE is not set to
IRD_IMMEDIATE.
IRR_FAIL is returned if an error occurs.
ERROR
irError is set as follows if an error occurs:
IRER_INVALID if the dial_string is too long or otherwise
invalid or if the cid is invalid
IRER_SYSERROR if a system call failure occurs (see
irSysError for additional information)
IRER_DRIVER_ERROR if a driver call failure occurs (see
irSysError for additional information)
IRER_BADSTATE if the channel is not in the IRS_IDLE library
state
IRER_RESOURCEBUSY if there are no resources available and
IRP_RESOURCE_RETURNMODE is set to IRD_IMMEDIATE
IRER_NORESOURCES if the CCA function has not been assigned
to any in-service resource card
IRER_RESTRICTED if the channel is restricted from using the
required resources
IRER_SERVICESTATE if the channel is not in the IRD_INACTIVE
service state
SEE ALSO
irDial(3IRAPI), irSetParam(3IRAPI), IrEVENTS(4IRAPI)
VERSION
This is version 3/14/01 of this man page.