(Page 1 of 1 in this chapter)

Chapter 6

Digital CAS Call Control Overview

6.1 Introduction
6.2 Initializing CT Access
6.2.1 Obtaining CTA Handles
6.3 Digital CAS Protocol Call Control Operations
6.3.1 Call Control Functions and Events
6.3.2 Call Control Functions and Solicited Events
6.3.3 Unsolicited Events

6.1 Introduction

This chapter:

For more information about call control, refer to the ADI Service Developer's Manual.

6.2 Initializing CT Access

To begin call control operations, initialize CT Access and acquire control of a physical trunk channel. The following sequence shows the steps the application must take to initialize CT Access:

  1. Initialize CT Access by invoking ctaInitialize.

    

  2. Create one or more event queues, using ctaCreateQueue. Each call creates a queue and returns a CTA context handle. Make sure at least one queue is attached to the ADI Service Manager.
    

    

  3. Create one or more CTA contexts and obtain CTA context handles, using ctaCreateContext. Each call creates a CTA context and returns a CTA context handle.
    

    

  4. Open services (including the ADI Service) on the CTA contexts with ctaOpenServices.
    




For more information about initializing CT Access, refer to the CT Access Developer's Reference Manual.


 






6.2.1	 Obtaining CTA Handles





When obtaining CTA context handles with ctaOpenServices the application must specify:




These values are included in the CTA_MVIP_ADDR structure referenced in the function call.


 MVIP Stream and Timeslot



CT Access uses these values to determine which MVIP streams and timeslots are assigned to which CTA context. The stream and timeslot specify a base stream:timeslot for the context, while the mode dictates how many additional stream:timeslots are allocated.



For AG boards with MVIP switches (such as the AG-T1 and AG-E1), the base streams are typically set to MVIP-95 LOCAL,4 and LOCAL,5 (MVIP-90 stream 18), which are the in and out voice streams to the on-board DSPs. 



For AG Quad boards, the base stream is typically set to MVIP-95 LOCAL,16 and LOCAL,17 (there is no MVIP-90 equivalent), which are the in and out voice streams to the on-board DSPs.



For more information about MVIP switching, refer to the Getting Started with MVIP Switching.


 Mode



For CAS protocol applications, set the mode to full duplex. This mode allows both voice (in-band) and telephone network signaling transmission and reception. If full duplex is specified, four timeslots are associated with the context. The first two timeslots reside on the specified base stream and are used for in-band media (for example, voice, and fax) transmission and reception. The second timeslot pair is for telephone network signaling transmission and reception. It resides on the specified base stream plus 1(or plus 2 for MVIP-95). 






6.3	 Digital CAS Protocol Call Control Operations





The following table shows call control operations supported by digital CAS TCPs:  





 Operation



 Level of Protocol Support



 Documentation




 Receiving inbound calls



 Fully supported.



 Chapter 7 of this manual




 Placing outbound calls



 Once a call is connected, all voice and tone detection is supported. However, an application cannot detect tones before connection. 


 Telephone network tone detection, precise tone detection and broadband tone detection are not applicable to digital CAS protocols.



 Chapter 7 of this manual




 Releasing calls



 Fully supported.



 CT Access Developer's Reference Manual




 Call blocking and unblocking



 Fully supported.



 Chapter 7 of this manual




 Call transfer



 Not supported by digital CAS TCPs.



 ---



















6.3.1	 Call Control Functions and Events





There are two types of CT Access events associated with call control operations:




The eventmask parameter in the ADI_CALLCTL_PARMS structure dictates whether certain informational call control events are generated. For detailed information about this structure, refer to the ADI Service Function Reference Manual.






6.3.2	 Call Control Functions and Solicited Events





The following table lists call control-related functions and associated events. For detailed documentation of the functions, parameters and events, refer to the ADI Service Function Reference Manual.


  





 Function



 Description/Associated Events




 adiAcceptCall



 Directs the TCP to accept an incoming call without answering it. The application can then perform other operations before answering or rejecting the call. The application can accept a call using any of the following methods:


·	 ADI_ACCEPT_PLAY_RING


·	 ADI_ACCEPT_QUIET


·	 ADI_ACCEPT_USER_AUDIO


 Associated Events:


·	 ADIEVN_ACCEPTING_CALL: The TCP is accepting the call, using the specified method. 


·	 ADIEVN_CALL_DISCONNECTED: A DISCONNECT message was received from the network, indicating that the remote party has hung up. The event value field contains the reason.


·	 ADIEVN_REJECTING_CALL: The application failed to invoke adiAnswerCall, adiAcceptCall or adiRejectCall within the period specified by the protocol's parameters. The call is automatically rejected. The event value field contains ADI_REJ_HOST_TIMEOUT. In this situation, a tone is played to the network. 




 adiAcceptIncomingAddress



 Causes the TCP to present the incoming call to the application, even if not all call information has arrived.




 adiAnswerCall



 Directs the TCP to answer a call after a specified number of rings.


 Associated Events:


·	 ADIEVN_ANSWERING_CALL: Returns when TCP is answering.


·	 ADIEVN_CALL_CONNECTED: Returns when telephone network connection is established.


·	 ADIEVN_CALL_DISCONNECTED: Returns when the remote party hangs up while the ring tone is being sent. The event value field contains the reason.


·	 ADIEVN_REJECTING_CALL: Returns when the application  to invoke adiAnswerCall within the period specified by the protocol's parameters (this is a race condition). The call is automatically rejected. The event value field contains ADI_REJ_HOST_TIMEOUT.




 adiBlockCalls



 Requests the TCP to block all incoming calls. The line remains in the blocked state until adiUnBlockCalls is called.


 Associated Events:


 ADIEVN_CALLS_BLOCKED: Returns when request has been granted.




 adiGetCallStatus



 Once the ADIEVN_INCOMING_CALL event is received, this function retrieves the current status of the call. It is typically called after ADIEVN_INCOMING_CALL is received, but can also be useful on other occasions.


 Associated Events: None.




 adiPlaceCall



 Directs the TCP to place a call to a specified number, using call placement parameters from the ADI_PLACECALL_PARMS structure.


 Associated Events:


·	 ADIEVN_PLACING_CALL: The TCP has seized an outbound trunk and resolved glare, and is dialing the digits.


·	 ADIEVN_CALL_PROCEEDING: All of the digits have been offered to the telephone network. This is a low-level event which is enabled only if the ADI_CC_REPTPROCEEDING bit is set in the ADI_CALLCTRL_PARMS eventmask passed to adiStartProtocol (see the source code of inoutcta.c for an example). 


·	 ADIEVN_REMOTE_ALERTING: The remote party is ringing. This is a low-level event which is enabled only if the ADI_CC_REPTALERTING bit is set in the ADI_CALLCTRL_PARMS eventmask passed to adiStartProtocol (see the source code of inoutcta.c for an example). 


·	 ADIEVN_REMOTE_ANSWERED: The remote party has answered.This is a low-level event which is enabled only if the ADI_CC_REPTANSWERED bit is set in the ADI_CALLCTRL_PARMS eventmask passed to adiStartProtocol (see the source code of inoutcta.c for an example). 


·	 ADIEVN_CALL_CONNECTED: The call has been answered, and the application has control of the DSPs. It can now play and record voice files, generate and detect DTMF tones. The event value field indicates the reason why the connected state was achieved.


·	 ADIEVN_CALL_DISCONNECTED: The call has been rejected (the line was busy, or the number did not exist), or was never answered (the timer waiting for an answer expired). The event value field contains the reason.


·	 ADIEVN_STATUSINFO_UPDATE: Information has been received regarding the status of the call.




 adiRejectCall 



 Directs the TCP to reject an incoming call using one of the following methods:


·	 ADI_REJ_PLAY_BUSY


·	 ADI_REJ_PLAY_REORDER


·	 ADI_REJ_USER_AUDIO


 Associated Events:


·	 ADIEVN_REJECTING_CALL: The reject sequence is initiated, or the application has failed to invoke either adiAnswerCall or adiRejectCall within the period specified by the protocol's parameters. The event value field contains the rejection method code, or ADI_REJ_HOST_TIMEOUT if the host timed out.


·	 ADIEVN_CALL_DISCONNECTED: The remote party has hung up.




 adiReleaseCall



 Directs the TCP to perform one of the following actions:


·	 Initiate connection tear down


·	 Abandon call placement


·	 Acknowledge a telephone network disconnect event


 Associated Events:


·	 ADIEVN_CALL_RELEASED: The call has been released (hung up).




 adiSetBilling



 Sets billing information relative to an incoming call (for protocols that support this feature).


 Associated Events:


·	 ADIEVN_BILLING_SET: The billing information was sent to the network. The value field contains the actual call rate.


 Note that this event does not indicate whether the requested rate was accepted by the network or not. If the network rejected the request, but did not provide a figure for the rate, the rate is set to ADI_BILLINGRATE_DEFAULT.


·	 ADIEVN_PROTOCOL_SEQUENCE_ERROR: The TCP was not in a valid state when it received adiSetBilling. The billing rate can be set while the TCP is in the Idle state or the Incoming Call state.


·	 ADIEVN_CALL_DISCONNECTED: The remote party has hung up. In this situation, either a DISCONNECT or a RELEASE message has been received from the network. In this case, any subsequent billing events are not reported.


·	 ADIEVN_PROTOCOL_ERROR: The request to set the billing status is not supported by the protocol.




 adiStartProtocol



 Starts a TCP.


 Associated Events:


·	 ADIEVN_STARTPROTOCOL_DONE: The function has finished. The event value field describes whether the TCP started successfully. ADI_REASON_FINISHED means a normal completion. Any other value implies an error.


 On AG Quad boards using resource management, ADIERR_NOT_ENOUGH_RESOURCES indicates that the adiStartProtocol parameter mediamask was not set to zero. The application must restart the TCP with the mediamask value in the ADICALLCTL_PARMS structure set to zero. Refer to Section 5.3.1, Starting Digital CAS Protocols on AG Quad Boards for details about starting digital CAS protocols on AG Quad boards. 




 adiUnBlockCalls



 Requests the TCP to stop blocking calls.


 Associated Events:


·	 ADIEVN_CALLS_UNBLOCKED: The request to unblock the line has been granted.















 






6.3.3	 Unsolicited Events





The following table lists call-control-related unsolicited events:


  





 Event



 Description




 ADIEVN_BILLING_PULSE



 A billing pulse has been received by an outbound application. These are out-of-band pulses, that signify that a unit of cost has been billed to the current call.


 This is a low-level event which is enabled only if the ADI_CC_REPTBILLING bit is set in the ADI_CALLCTRL_PARMS eventmask passed to adiStartProtocol (see the source code of inoutcta.c for an example of this).




 ADIEVN_IN_SERVICE



 The line is back in service.




 ADIEVN_INCOMING_CALL



 The TCP has handled the setup of an incoming call, and is now waiting for the application to decide if the call must be answered, accepted, or rejected. The application may call adiGetCallStatus to retrieve information on the incoming call. The application may then answer, accept or reject the call as needed within a time period that is protocol specific (usually several seconds).




 ADIEVN_INCOMING_DIGIT



 With Digital CAS protocols, you can set up the TCP so when it receives digits during an incoming call, it sends them to the application one by one as they arrive, instead of all at once when all digits have been received. If the TCP is configured this way, this event indicates that a digit has arrived. The event value field is set to the value of the digit (a char). For more information, see Section 7.2.2, Retrieving Incoming Digits.


 ADIEVN_INCOMING_DIGIT is enabled only if the ADI_CC_REPTDIGITS and ADI_CC_REPTSEIZURE bits are set in the ADI_CALLCTRL_PARMS eventmask passed to adiStartProtocol (see the source code of inoutcta.c for an example).




 ADIEVN_OUT_OF_SERVICE



 The called party is blocking the line, or the line and associated hardware are not configured properly. The TCP will not accept commands until the line comes back into service again. Then the TCP returns to the idle state, and generates an ADIEVN_IN_SERVICE event.




 ADIEVN_PROTOCOL_ERROR



 The call failed because the digit string sent from the host with adiPlaceCall had incorrect syntax, a timer expired during call set up, or the protocol received an illegal tone for the country it was designed for. This event will be followed by an ADIEVN_CALL_DISCONNECTED event only if the call state is not idle. This occurs in the following circumstances:


·	 outbound calls: after the PLACING_CALL event has been received


·	 inbound calls: after the INCOMING_CALL event has been received




 ADIEVN_SEIZURE_DETECTED



 The line has been seized for an incoming call. It is the beginning of the call setup process for an incoming call.


 This is a low-level event which is enabled only if the ADI_CC_REPTSEIZURE bit is set in the ADI_CALLCTRL_PARMS eventmask passed to adiStartProtocol (see the source code of inoutcta.c for an example of this).


 Note: If the ADI_CC_REPTSEIZURE bit is not set, the ADIEVN_INCOMING_DIGIT event is also disabled.


 For MFC-R2, pulsed E and M, and MFS protocols, the call setup procedure may take several seconds. You may wish to enable your application to receive ADIEVN_SEIZURE_DETECTED to prepare to receive an incoming call. 




 ADIEVN_STATUSINFO_UPDATE



 A call status information event has been received by CT Access. This includes billing information for outgoing calls and ANI digits available in the R15 inbound TCP (r150).


 The applications receives this low level event only if the ADI_CC_REPTSTATUS_UPDATE bit is set in ADI_CALLCTRL_PARMS eventmask passed to adiStartProtocol. Upon receiving this event, the application can call adiGetCallStatus to analyze the conditional information.

































 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



Copyright © 1998, Natural MicroSystems, Inc.   All rights
reserved.