adiStartProtocol

Starts the NOCC protocol on a specified context.

Supported board types

Prototype

DWORD adiStartProtocol ( CTAHD ctahd, char *protoname, WORD *protoparms, ADI_START_PARMS *parms)

Argument	Description
ctahd	Context handle returned by ctaCreateContext or ctaAttachContext.
protoname	Name of the protocol trunk control program (TCP). The valid value is NOCC.
protoparms	Valid value is NULL.
parms	Pointer to an ADI_START_PARMS structure, as shown (NULL uses default parameter values): typedef struct { DWORD size; /* size of this structure / ADI_CALLCTL_PARMS callctl; / call control parms / ADI_DIAL_PARMS dial; / dial control parms / ADI_DTMFDETECT_PARMS dtmfdet; / DTMF detection parms / ADI_CLEARDOWN_PARMS cleardown; / cleardown detect. parms/ ADI_ECHOCANCEL_PARMS echocancel; / echo canceller parms */ } ADI_START_PARMS; Refer to ADI_START_PARMS for field descriptions.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	protoname is invalid or NULL or parms contains an invalid size field.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_INVALID_STATE	Function not valid in the current port state.
CTAERR_SVR_COMM	Server communication error.

Events

Event

Description

ADIEVN_STARTPROTOCOL_DONE

If successful, the value field contains CTA_REASON_FINISHED; otherwise, the value contains an error code, such as:

CTAERR_BAD_ARGUMENT

Invalid protocol name; the protocol associated with protoname was not specified in the configuration file.

Details

Use adiStartProtocol to specify the NOCC protocol. The function initializes the ADI service and by default starts the DTMF detector.

The ADI_START_PARMS data structure consists of the following substructures:

ADI_CALLCTL_PARMS controls which functions are started automatically by adiStartProtocol.

The ADI_CALLCTL_PARMS structure is defined as:

typedef struct
{                   /* call control parameters:                */
DWORD size;       /* size of this structure                  */
DWORD eventmask; /* not used                                */
DWORD mediamask; /* functions to run:   */
          #define ADI_CC_RESVDTMF 0x0001
                  /* reserve dtmf detection                  */
          #define ADI_CC_RESVSILENCE 0x0002
                  /* reserve silence detector                */
          #define ADI_CC_RESVCLRDWN 0x0004
               /* reserve clear-down det.                */
          #define ADI_CC_AUTODTMF 0x0008
                   /* start DTMF detection                   */
         #define ADI_CC_AUTOECHO 0x0010
                /* start echo canceller                    */
          #define ADI_CC_ALLMEDIA(ADI_CC_RESVDTMF|\
                  ADI_CC_RESVSILENCE|ADI_CC_RESVCLRDWN|\
                  ADI_CC_AUTODTMF|ADI_CC_AUTOECHO)
DWORD blockmode; /* not used                                */
DWORD debugmask; /* not used                                */
} ADI_CALLCTL_PARMS;

ADI_DIAL_PARMS specifies how to perform dialing. Refer to adiStartDial for the structure definition.
ADI_DTMFDETECT_PARMS controls DTMF detection if required by the protocol, as well as initial DTMF detection in the conversation (connected) state if started automatically by the protocol. Refer to adiStartDTMFDetector for the structure definition.

ADI_ECHOCANCEL_PARMS controls the application of an echo cancellation algorithm to the context in the connected state and is defined as:

typedef struct
{                    /* parameters for echo cancellation*/
DWORD size;        /* size of this structure          */
DWORD mode;        /* echo canceller mode             */
DWORD filterlength;/* filter length (msec)            */
DWORD adapttime;   /* filter adaptation time (msec)   */
DWORD predelay;    /* offset of input sample (msec)   */
INT32 gain;        /* receive gain (db)               */
} ADI_ECHOCANCEL_PARMS ;

Refer to the Parameters section for default values and a more detailed explanation of the fields in these structures.

When the protocol is NOCC, adiStartProtocol must be called before any ADI functions are invoked. The application can execute any function once ADIEVN_STARTPROTOCOL_DONE is received.

For details about using telephony protocols in the application, refer to the NMS CAS for Natural Call Control Developer's Manual.

Example

int myStartProtocol( CTAHD ctahd )
{
CTA_EVENT event;

          /* start "no call control" protocol with all default parameters */
if( adiStartProtocol( ctahd, "NOCC", NULL, NULL ) != SUCCESS )
   return MYFAILURE;

do
{
    myGetEvent( &event );             /* see ctaWaitEvent example */
} while( event.id != ADIEVN_STARTPROTOCOL_DONE );

if( CTA_IS_ERROR( event.value ) )
   return MYFAILURE;                 /* API error                */
else
     return SUCCESS;                   /* started successfully     */
}