# adiStartProtocol

Starts the NOCC
protocol on a specified context.

#### Supported board types

- AG

- CG

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

#### See also

adiStopProtocol

#### 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 */
}