Starts a telephony protocol on a specified CTA context.

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

ctahd CTA context handle returned by ctaCreateContext.

protoname Name of the protocol trunk control program (TCP).

protoparms Pointer to a protocol-specific parameter structure (NULL uses the protocol's default parameter values), such as:

ADI_WNK_PARMS

ADI_OGT_PARMS

ADI_DID_PARMS

ADI_LPS_PARMS

ADI_MFC_PARMS

ADI_EAM_PARMS

Refer to the AG CAS for Natural Call Control Installation and Developer's Manual or the AG CAS for for the ADI Service Installation and Developer's Manual for a complete listing of parameter values for various TCPs.

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;

• SUCCESS
• CTAERR_BAD_ARGUMENT
  protoname is invalid or NULL or parms contains an invalid size field.
• CTAERR_FUNCTION_NOT_ACTIVE
  This error is returned when a function call is made to ADI call control when the NCC service is active.
• CTAERR_INVALID_CTAHD
• CTAERR_INVALID_STATE

• 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.
• ADIEVN_INCOMING_CALL
  An inbound call has been received. All incoming call information has been collected.
• ADIEVN_PROTOCOL_EVENT
  If the application sets the debugmask of ADI_CALLCTL_PARMS, the value field contains debug events. Valid debug events change with each protocol.
• ADIEVN_PROTOCOL_ERROR
  Anomalous signaling event from the network. For example, if an incoming call is abandoned before ADIEVN_INCOMING_CALL is sent, a false seizure is reported.

For AG and CG hardware, this function initiates a protocol for the specified port and CTA context. The protocol name associates both a default parameter block and a Trunk Control Program (TCP) with the specified port and CTA context. The TCP must have been previously downloaded to the board at load time. Note that customer-specific protocols do not have default values within the ADI service.

For QX hardware, this function initiates a protocol for the specified port and CTA context. The protocol name associates both a default parameter block and a Dynamic Link Library (DLL) with the specified port and CTA context. A typical example is LPS0 for loop start on QX 2000/100-4L boards.

Refer to the AG CAS for the ADI Service Installation and Developer's Manual for valid protocol names and their associated data structures, as well as information about controlling calls under specific TCPs. Some examples of protocol names are LPS0 for loop start on AG-8 boards, and WNK0 for DID on AG-8 boards or T1 lines. For applications that are not using protocol-independent call control, NOCC (no call control) may be passed as the protoname.

The ADI_START_PARMS data structure comprises these substructures:

ADI_CALLCTL_PARMS, which controls the operation of the following aspects of call control:

• Which low-level protocol events are reported to the application.

• Which functions are auto-started upon entering the Conversation state.

• Which method is used for blocking calls.

• Which low-level diagnostic events are reported to the application.

The ADI_CALLCTL_PARMS structure is defined as:

typedef struct

{ /* call control parameters: */

DWORD size; /* size of this structure */

DWORD eventmask; /* report low-level call-control events: */

#define ADI_CC_REPTSEIZURE 0x0001

/* ADIEVN_SEIZURE_DETECTED */

#define ADI_CC_REPTPROCEEDING 0x0002

/* ADIEVN_PROCEEDING */

#define ADI_CC_REPTALERTING 0x0004

/* ADIEVN_REMOTE_ALERTING */

#define ADI_CC_REPTANSWERED 0x0008

/* ADIEVN_REMOTE_ANSWERED */

#define ADI_CC_REPTDIGITS 0x0010

/* ADIEVN_INCOMING_DIGIT */

#define ADI_CC_REPTBILLING 0x0020

/* ADIEVN_BILLING_PULSE */

#define ADI_CC_REPTSTATUSINFO 0x0040

/* ADIEVN_INCOMING_STATUSINFO */

DWORD mediamask; /* functions to run during conversation: */

#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; /* method of blocking: */

#define ADI_CC_BLOCK_REJECTALL 0

/* do not answer subsequent calls */

#define ADI_CC_BLOCK_MAKEBUSY 1

/* assert reverse make busy */

DWORD debugmask; /* protocol debug (low-level events): */

#define ADI_CC_DBGDIGITS 0x0001

/* report all digits received */

#define ADI_CC_DBGRINGS 0x0002

/* report all ring begin/ends */

#define ADI_CC_DBGRINGTONE 0x0004

/* report all ringtone events */

#define ADI_CC_DBGCID 0x0008

/* report all CID errors */

} ADI_CALLCTL_PARMS;

• ADI_DIAL_PARMS specifies how dialing is to be performed during adiPlaceCall. 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 auto-started by the protocol. Refer to adiStartDTMFDetector for the structure definition.

• ADI_CLEARDOWN_PARMS controls cleardown (or inband remote disconnect) if required by the protocol. The ADI_CLEARDOWN_PARMS structure is defined as:

  
   typedef struct
  
  
   {    
  
  
    DWORD size; /* size of this structure */
  
  
    DWORD freq1; /* frequency to detect */
  
  
    DWORD bandw1; /* bandwidth */
  
  
    DWORD freq2; /* 2nd frequency to detect (dualtone) */
  
  
    DWORD bandw2; /* 2nd bandwidth */
  
  
    INT32 qualampl; /* broadband qual level (in dBm) */
  
  
    DWORD qualtime; /* qualification time (in ms) */
  
  
    DWORD reflevel; /* qual thresh,output of filter (IDUs) */
  
  
    DWORD reserved; /* reserved, must be 0 */
  
  
    DWORD tonecount; /* # of tones, or 0 for continuous tones */
  
  
    DWORD minontime; /* shortest allowable tone */
  
  
    DWORD maxontime; /* longest allowable tone */
  
  
    DWORD minofftime; /* shortest silence between tones */
  
  
    DWORD maxofftime; /* longest silence between tones */
  
  
   } ADI_CLEARDOWN_PARMS;
  
  
   
  
  

• ADI_ECHOCANCEL_PARMS controls the application of an echo cancellation algorithm to the CTA 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 Appendix C for default values and a more detailed explanation of the fields in the above structures.

adiStartProtocol must be called before any call control functions are invoked. After the protocol is started, call control functions, such as adiPlaceCall, may be issued and detection of inbound calls will be reported.

Note: If the protocol is NOCC, then the application may execute any function once the ADIEVN_STARTPROTOCOL_DONE event is received, but may not issue call control functions.

The unsolicited events ADIEVN_INCOMING_CALL and ADIEVN_PROTOCOL_EVENT may be received immediately after the protocol is started or during the span of a call.

For details about using telephony protocols in your application, refer to the AG CAS for Natural Call Control Installation and Developer's Manual or the AG CAS for the ADI Service Installation and Developer's Manual.

adiStopProtocol

int myStartProtocol( CTAHD ctahd, char *protocolname )
{
 CTA_EVENT event;

    /* start specified protocol with all default parameters */
    if( adiStartProtocol( ctahd, protocolname, 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 */
}