Starts a telephony protocol on a specified context.

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

ctahd Context handle returned by adiOpenPort.

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

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_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 loaded with agmon.
• 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.

This function initiates a protocol for the specified port and context. The protocol name associates both a default parameter block and a Trunk Control Program (TCP) with the specified port and context. The TCP must have been previously downloaded to the board (using agmon) at load time. Note that customer-specific protocols do not have default values within AG Access.

Refer to Appendix C for valid protocol names and their associated data structures. Some examples of protocol names are "LPS0" for loop-start on AG-8s, and "DID0" for DID on AG-8s or T1 lines. For applications that are not using protocol-independent call control, "NOCC" ("no call control") may be passed as the protoname.

Note that the ADI_START_PARMS data structure comprises the following substructures:

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

• which low-level protocol events should be reported to the application;

• which functions should be auto-started upon entering the conversation state;

• which method should be used for blocking calls;

• which low-level diagnostic events should be 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    */

 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  
   /* don't 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 the function 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 context in the connected state and is defined as:

  typedef struct
  {       /* parameters for echo cancellation     */
   DWORD size;    /* size of this structure               */
   DWORD mode;    /* 1- board default  2- custom          */
   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 ;
  
  

See Appendix D 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, see the AG Access Developer's Manual.

adiStopProtocol

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

    /* start specified protocol with all default parameters */
    if( adiStartProtocol( ctahd, protocolname, NULL, NULL ) != SUCCESS )
        return MYFAILURE;

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

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