NAME
irStartCCA, irStopCCA, irCheckCCA - start/stop call classif-
ication analysis on a channel
SYNOPSIS
#include <irapi.h>
int irStartCCA (channel_id cid, int tag);
int irStopCCA (channel_id cid);
int irCheckCCA (channel_id cid);
DESCRIPTION
When the IRAPI library parameter IRP_OUTCALL_CCALEVEL is set
to IRD_FULL_CCA, the irStartCCA function starts Full Call
Classification Analysis (Full CCA) on the specified channel
cid. It is used by applications to start Full CCA indepen-
dent of irCall(3IRAPI). This function allows applications
to use Full CCA, for instance, when doing a flash transfer
via irFlash and dialing a string of digits via irDial.
irStartCCA should be called before the irDial to ensure that
the necessary SP resources are reserved and available to
interpret the response to the dial.
When the IRAPI library parameter IRP_OUTCALL_CCALEVEL is set
to IRD_BLIND_CCA, irStartCCA does not need to be called
since IRE_CALL_PROG or IRE_DISCONNECT_TONE events detected
by the network interface card for blind cca are generated
(subject to event masking) regardless of whether irStartCCA
has been executed. In other words, the IRAPI library acts
as if CCA is always on for IRD_BLIND_CCA.
irStartCCA does not need to be called when using irCall
since irCall internally takes care of using irStartCCA when
necessary.
The tag argument is a user-supplied number that associates
the irStartCCA with a subsequent IRE_GRANT or IRE_DENY
event. The tag included with IRE_CALL_PROG events is unde-
fined (most likely a 0).
Various call progress events are generated in response to
changing state of the call [see IrEVENTS(4IRAPI)]. The
event is returned in an event structure (ir_event) that is
accessed by irCheck(3IRAPI) or irWCheck(3IRAPI).
IRAPI library parameters IRP_RESOURCE_RETURNMODE,
IRP_OUTCALL_CCALEVEL, IRP_OUTCALL_ANSDET, and
IRP_OUTCALL_MAXRINGS [see IrPARAMETERS(4IRAPI)] affect the
operation of irStartCCA. IRP_RESOURCE_RETURNMODE indicates
whether to wait for the necessary SP resources when Full CCA
is being requested. IRP_OUTCALL_MAXRINGS specifies the
number of rings to wait for before generating IRE_CALL_PROG
event. IRP_OUTCALL_CCALEVEL specifies the CCA level
(IRD_BLIND_CCA, IRD_SIMPLE_CCA, IRD_FULL_CCA) to be used for
CCA. Simple CCA is done on the telephony hardware itself
while Full CCA requires an SP or SSP assigned to CCA.
IRP_OUTCALL_ANSDET applies only to Full CCA and specifies
whether answer supervision or speech energy detection should
be used to determine that a call has been answered.
Values for these parameters can be retrieved using
irGetParam(3IRAPI) while new values can be assigned to them
using irSetParam(3IRAPI). The default for
IRP_OUTCALL_MAXRINGS is 5 and for IRP_OUTCALL_CCALEVEL is
IRD_BLIND_CCA. The default for IRP_OUTCALL_ANSDET is
IRD_DEFAULT which means that the most appropriate form of
answer detection for the network interface is used. All the
outcall related parameters must be set to the desired values
before CCA starts.
Full CCA is turned off by default and is turned off automat-
ically after a call classification has been made. Depending
upon the telephony type, Call Progress Tone (CPT) detection
used for simple CCA may occur automatically all the time or
only when the detectors have been enabled by a call to
irStartCCA. It is now recommended that irStartCCA be used
to explicitly enable the detectors when CPT detection (for
simple CCA) is desired. It is also recommended that
irStopCCA be used to explicitly disable the detectors when
CPT detection is no longer needed (WARNING: The AYC21 cannot
detect DTMF tones when CPT detection is enabled). Blind CCA
is turned on by default, but has few detection events to
report.
Running Full CCA only when required reduces load on the SP
card(s) when IRD_FULL_CCA is used and therefore improves
performance.
irStopCCA stops Full CCA on the cid. Depending on the
telephony type, irStopCCA may leave simple CCA on, or it may
turn off simple CCA. irStopCCA leaves blind CCA on, but
returns IRR_OK.
irCheckCCA returns the status of CCA (on or off).
WARNING
The AYC21 cannot simultaneously detect DTMF tones and the
CPT tones used for simple CCA for LST1 and LSE1. Applica-
tions must be sure to call irStopCCA after determining the
disposition of a call so as to be able to detect DTMF tones.
EVENT
For irStartCCA only, IRE_GRANT and IRE_DENY indicate a
return of IRR_PENDING returned if CCA resources are not
available when requested. The tag provided with the
IRE_GRANT or IRE_DENY event is the tag provided in the call
to irStartCCA.
Regardless of the CCA level and whether Full CCA is on, CCA
results are returned to an application via IRE_CALL_DONE or
IRE_CALL_PROG event with different event modifiers. The tag
provided for an IRE_CALL_PROG event is undefined (typically
0).
RETURN VALUE
For irStartCCA and irStopCCA IRR_OK is returned if the
request is successful.
For irStartCCA only, IRR_PENDING is returned if CCA
resources are not currently available and
IRP_RESOURCE_RETURNMODE is not set to IRD_IMMEDIATE. The
channel will remain in the IRS_CCA_PENDING library state
until the CCA resources are granted or denied, or until
irStopCCA is called to stop waiting for the CCA resources.
For irCheckCCA IRR_ON is returned if CCA is on and IRR_OFF
is returned if CCA is off.
All functions return IRR_FAIL if an error occurs.
ERROR
irError is set as follows if an error occurs:
IRER_INVALID if the cid is not valid or IRP_OUTCALL_CCALEVEL
has an invalid value
IRER_DRIVER_ERROR if a driver call failure occurs (see
irSysError for additional information)
IRER_SYSERROR if a system or driver call failure occurs (see
irSysError for additional information)
IRER_BADSTATE for irStartCCA if the library state is not
IRS_IDLE or IRS_CALLING
IRER_RESOURCEBUSY for irStartCCA 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
SEE ALSO
irSetParam(3IRAPI), irGetParam(3IRAPI), irCall(3IRAPI),
IrPARAMETERS(4IRAPI), IrDEFINES(4IRAPI), IrEVENTS(4IRAPI)
VERSION
This is version 8/31/00 of this man page.