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).

          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_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. 

          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.  

          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.  Blind CCA is turned on by default, but has 
          few detection events to report.

          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).

     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/03 of this man page.