Version

Chapter 2

Function Summary

2.1 Introduction

2.2 Managing Telephony Protocols

2.3 Call Control

2.4 Voice Play and Record

: 2.4.1 Play and Record Functions
: 2.4.2 Terminating Play or Record
: 2.4.3 Buffer Management Functions
: 2.4.4 Status and Modification Functions

2.5 Collecting Digits (DTMFs)

2.6 Generating Tones and DTMFs

2.7 Detecting DTMFs and MFs

2.8 Echo Cancellation

2.9 Detecting Energy and Specific Tones

2.10 Managing Call Progress Analysis

2.11 Sending and Receiving Frequency Shift Key (FSK) Data

2.12 Low-Level Call Control Functions

2.13 Using an On-Board Timer

2.14 Utility Functions

2.1 Introduction

This chapter groups the ADI service functions according to the tasks a typical telephony application may perform. Such tasks include: Managing telephony protocols Call control* Voice play and record Collecting digits (DTMF) Generating tones and DTMFs Detecting DTMFs and MFs Echo cancelling Detecting energy and specific tones Call progress analysis Sending and receiving Frequency Shift Key (FSK) data Low-level call control Using an on-board timer
*The Natural Call Control (NCC) service API is the new standard call control API for NMS products. The NCC service provides an extended and enhanced version of the call control portion of the ADI service API. If your application currently uses the ADI service for call control, consider migrating to the NCC service for better performance, new features, and more control over your application's call control functionality.
With the release of CT Access 3.0, the call control functions within ADI will be considered to be deprecated functions. Eventually, the ADI call control API will be phased out entirely.
Refer to the Natural Call Control Service Developer's Reference Manual and to the AG CAS for Natural Call Control Developer's Manual for further information.

2.2 Managing Telephony Protocols

After setting up the ADI service, you must start a telephony protocol on each CTA context in order to perform telephony activities. The ADI service provides a null protocol, NOCC, for applications that do not require call control. Refer to the AG CAS for ADI Service Installation and Developer's Manual for a listing of telephony protocols and parameters.
For more information about controlling calls under specific trunk control protocols (TCPs), refer to the AG CAS Installation and Developer's Manual.
The ADI service provides the following functions to manage telephony protocols:

Function

S/A¹

Description

adiStartProtocol

A

Loads a Trunk Control Program (TCP) on AG boards or a Dynamic Link Library (DLL) for QX boards and enables the use of functions requiring DSP resources.

adiStopProtocol

A

Halts the port's TCP, terminates functions on the port, and unloads the TCP.

¹ Synchronous or Asynchronous

Note: The Natural Call Control service API includes nccStartProtocol, a functional counterpart to the ADI service's adiStartProtocol. Once nccStartProtocol has been called, subsequent calls to most ADI call control related functions will return the error CTAERR_FUNCTION_NOT_ACTIVE.

Function	S/A¹	Description
adiStartProtocol	A	Loads a Trunk Control Program (TCP) on AG boards or a Dynamic Link Library (DLL) for QX boards and enables the use of functions requiring DSP resources.
adiStopProtocol	A	Halts the port's TCP, terminates functions on the port, and unloads the TCP.

2.3 Call Control

The call control functions are abstractions for establishing and tearing down inbound and outbound calls. These functions relieve the programmer of network signaling and procedures required for connection establishment and maintenance. They control a single channel and operate on telephony protocols, but are independent of any specific line interface protocol. For more information about call control, refer to the ADI Service Developer's Manual. Note: The Natural Call Control service supersedes ADI call control. For more information about the NCC service, refer to the Natural Call Control Service Developer's Reference Manual.
The ADI service provides the following functions to manage call control: Function S/A¹ Description adiAcceptCall A Accepts an incoming call. adiAcceptIncomingAddress A Presents an incoming call without waiting for all digits. adiAnswerCall A Answers an incoming call. adiRejectCall A Rejects an incoming call. adiPlaceCall A Places an outbound call. adiBlockCalls A Blocks subsequent calls. adiUnBlockCalls A Unblocks previously blocked calls. adiReleaseCall A Releases an active call. adiGetCallStatus S Gets the current call control status. adiTransferCall A Transfers the call. adiPlaceSecondCall A Places a second call. adiReleaseSecondCall A Releases a second call. ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiAcceptCall	A	Accepts an incoming call.
adiAcceptIncomingAddress	A	Presents an incoming call without waiting for all digits.
adiAnswerCall	A	Answers an incoming call.
adiRejectCall	A	Rejects an incoming call.
adiPlaceCall	A	Places an outbound call.
adiBlockCalls	A	Blocks subsequent calls.
adiUnBlockCalls	A	Unblocks previously blocked calls.
adiReleaseCall	A	Releases an active call.
adiGetCallStatus	S	Gets the current call control status.
adiTransferCall	A	Transfers the call.
adiPlaceSecondCall	A	Places a second call.
adiReleaseSecondCall	A	Releases a second call.

2.4 Voice Play and Record

The ADI service provides functions for recording and playing speech data. There are three methods by which the application can transfer speech data to and from the AG or QX board using the ADI service: Transfer Method Description Single memory transaction The application submits a single data buffer to the ADI service. Asynchronous transfer The application serially submits multiple data buffers by exchanging commands and events with the ADI service. Callback transfer The ADI service manages the buffers and invokes an application callback procedure to retrieve or store data.

Transfer Method	Description
Single memory transaction	The application submits a single data buffer to the ADI service.
Asynchronous transfer	The application serially submits multiple data buffers by exchanging commands and events with the ADI service.
Callback transfer	The ADI service manages the buffers and invokes an application callback procedure to retrieve or store data.

2.4.1 Play and Record Functions

Choose a set of functions to initiate play or record operations as appropriate to your applications's data transfer method, according to the following table: Operation Memory Transaction Asynchronous Callback Play adiPlayFromMemory adiPlayAsync adiStartPlaying* Record adiRecordToMemory adiRecordAsync adiStartRecording*
*These functions are not supported while CT Access is running in Client/Server mode.

Operation	Memory Transaction	Asynchronous	Callback
Play	adiPlayFromMemory	adiPlayAsync	adiStartPlaying*
Record	adiRecordToMemory	adiRecordAsync	adiStartRecording*

2.4.2 Terminating Play or Record

The ADI service provides the following functions to stop play or record regardless of the data transfer method: Function S/A¹ Description adiStopPlaying A Terminates playing. adiStopRecording A Terminates recording. ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiStopPlaying	A	Terminates playing.
adiStopRecording	A	Terminates recording.

2.4.3 Buffer Management Functions

For the asynchronous data transfer methods, each buffer is submitted using one of the following functions: Function S/A¹ Description adiSubmitPlayBuffer A Supplies a buffer to an asynchronous play operation. adiSubmitRecordBuffer A Supplies a buffer for an asynchronous record operation. ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiSubmitPlayBuffer	A	Supplies a buffer to an asynchronous play operation.
adiSubmitRecordBuffer	A	Supplies a buffer for an asynchronous record operation.

2.4.4 Status and Modification Functions

The following functions provide status information or modify an active play or record operation: Function S/A¹ Description adiModifyPlayGain S Changes the gain applied to the speech while playing. adiModifyPlaySpeed S Changes the play speed while playing. adiGetPlayStatus S Retrieves play (or last play) status. adiGetRecordStatus S Retrieves record (or last record) status. adiGetEncodingInfo S Returns frame size, data rate, and max buffer size for a given encoding format. ¹ Synchronous or Asynchronous Note: adiModifyPlaySpeed is not supported on the QX 2000 board. If this function is called on the QX 2000 board, CTAERR_FUNCTION_NOT_AVAIL is returned.

Function	S/A¹	Description
adiModifyPlayGain	S	Changes the gain applied to the speech while playing.
adiModifyPlaySpeed	S	Changes the play speed while playing.
adiGetPlayStatus	S	Retrieves play (or last play) status.
adiGetRecordStatus	S	Retrieves record (or last record) status.
adiGetEncodingInfo	S	Returns frame size, data rate, and max buffer size for a given encoding format.

2.5 Collecting Digits (DTMFs)

The ADI service provides both synchronous and asynchronous digit collection functions. Refer to the ADI Service Developer's Manual for a detailed discussion on digit collection and how to incorporate it into your application.
The following ADI functions control digit collection: Function S/A¹ Description adiGetDigit S Retrieves a single digit from the internal digit collection queue. adiPeekDigit S Reads the first digit from the internal digit collection queue without removing it. adiFlushDigitQueue S Flushes the internal digit collection queue. adiCollectDigits A Starts asynchronous digit collection. adiStopCollection A Terminates digit collection. ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiGetDigit	S	Retrieves a single digit from the internal digit collection queue.
adiPeekDigit	S	Reads the first digit from the internal digit collection queue without removing it.
adiFlushDigitQueue	S	Flushes the internal digit collection queue.
adiCollectDigits	A	Starts asynchronous digit collection.
adiStopCollection	A	Terminates digit collection.

2.6 Generating Tones and DTMFs

AG boards are capable of generating single and dual frequency tones. The following ADI functions control tone generation: Function S/A¹ Description adiStartTones A Plays a sequence of user-defined tones. adiStartDTMF A Starts playing a sequence of DTMF tones; MF tones can also be generated. adiStopTones A Terminates playing tones. ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiStartTones	A	Plays a sequence of user-defined tones.
adiStartDTMF	A	Starts playing a sequence of DTMF tones; MF tones can also be generated.
adiStopTones	A	Terminates playing tones.

2.7 Detecting DTMFs and MFs

The ADI service provides functions for enabling and disabling DTMF and MF detection. By default, DTMF detection is enabled when a call is established (refer to the ADI Service Developer's Manual for more information).
The following functions enable and disable DTMF and MF tone detection: Function S/A¹ Description adiStartDTMFDetector A Starts DTMF detection (note that by default it is on). adiStopDTMFDetector A Stops DTMF detection. adiStartMFDetector A Starts the MF tone detector. adiStopMFDetector A Stops the MF tone detector. ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiStartDTMFDetector	A	Starts DTMF detection (note that by default it is on).
adiStopDTMFDetector	A	Stops DTMF detection.
adiStartMFDetector	A	Starts the MF tone detector.
adiStopMFDetector	A	Stops the MF tone detector.

2.8 Echo Cancellation

Echo cancellation improves DTMF/tone detection and/or speech recognition performance during playing by cancelling any leakage of the playback audio from the receive signal path. It also improves peer to peer human communications in an IP telephony gateway application by eliminating talker echo.
Echo cancellation is not enabled or disabled with a function call. It is configured as part of starting a protocol, see adiStartProtocol for more information. When the protocol for which it is configured is started, the echo canceller automatically starts when a call enters the conversation state. Refer to the ADI Service Developer's Manual for more information.
Use adiModifyEchoCanceller (asynchronous) to modify the echo canceller parameters, after it is started. This function is available for CT Access 4.0 only.

2.9 Detecting Energy and Specific Tones

The following functions enable and disable detectors of precise tones, raw energy, and silence: Function S/A¹ Description adiStartToneDetector A Starts a precise tone detector. adiStopToneDetector A Stops a precise tone detector. adiStartEnergyDetector A Starts the energy detector (energy vs. silence). adiStopEnergyDetector A Stops the energy detector (energy vs. silence). ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiStartToneDetector	A	Starts a precise tone detector.
adiStopToneDetector	A	Stops a precise tone detector.
adiStartEnergyDetector	A	Starts the energy detector (energy vs. silence).
adiStopEnergyDetector	A	Stops the energy detector (energy vs. silence).

2.10 Managing Call Progress Analysis

Call progress analysis primarily allows the application to control and monitor the placement of outbound calls when not using call control (for example, when using the NOCC protocol). Call progress analysis can also be used at any time after a call is connected. For example, when receiving an inbound call, an application can start up a call progress analysis operation to detect modem tones, fax terminal tones, or voice.
The following ADI functions start and stop call progress analysis: Function S/A¹ Description adiStartCallProgress A Starts call progress analysis. adiStopCallProgress A Stops call progress analysis. ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiStartCallProgress	A	Starts call progress analysis.
adiStopCallProgress	A	Stops call progress analysis.

2.11 Sending and Receiving Frequency Shift Key (FSK) Data

AG and QX boards (except for the QX 2000/80-4L) are capable of sending and receiving Frequency Shift Key (FSK) data. The transmit function is an implementation of the modem portion of Bellcore advisory TA-NWT-000030. The basic modulation is continuous-phase binary FSK at 1200 baud between 1200 Hz (mark) and 2200 Hz (space). The only supported baud rate is 1200.
The following functions are used to send or receive Frequency Shift Key data: Function S/A¹ Description adiStartSendingFSK A Initiates sending Frequency Shift Key data. adiStopSendingFSK A Stops the sending function. adiStartReceivingFSK A Receives Frequency Shift Key data. adiStopReceivingFSK A Stops the receive function. ¹ Synchronous or Asynchronous
FSK modems are the low-level building blocks for Analog Display Services Interface (ADSI). The ADI service does not provide an ADSI programming interface, but you can use the FSK functions to implement ADSI applications.

Function	S/A¹	Description
adiStartSendingFSK	A	Initiates sending Frequency Shift Key data.
adiStopSendingFSK	A	Stops the sending function.
adiStartReceivingFSK	A	Receives Frequency Shift Key data.
adiStopReceivingFSK	A	Stops the receive function.

2.12 Low-Level Call Control Functions

The following functions provide low-level access to the line interface. This access is typically only needed when using the NOCC (No Call Control) protocol. These functions are used when the application is directly controlling the line interface or when a CAS protocol is not needed. Care should be taken when using these functions (especially if you are running a telephony protocol). Note: The Natural Call Control service API does not include low-level call control functions at this time. Regardless of which service is used to start the NOCC protocol, the low-level call control functions listed in the following table remain accessible to the application.
The following ADI functions provide low-level call control: Function S/A¹ Description adiAssertSignal S Asserts an out-of-band signaling pattern. adiStartPulse A Pulses an out-of-band signaling pattern for a duration. adiStartSignalDetector A Starts detection of out-of-band signaling bits. adiStopSignalDetector A Stops detection of out-of-band signaling bits. adiQuerySignalState A Queries the current inbound out-of-band signaling bits. adiStartDial A Starts DTMF/MF/pulse dialing of digits. adiStopDial A Stops DTMF/MF/pulse dialing of digits. ¹ Synchronous or Asynchronous Note: adiAssertSignal returns before the pattern is actually asserted.

Function	S/A¹	Description
adiAssertSignal	S	Asserts an out-of-band signaling pattern.
adiStartPulse	A	Pulses an out-of-band signaling pattern for a duration.
adiStartSignalDetector	A	Starts detection of out-of-band signaling bits.
adiStopSignalDetector	A	Stops detection of out-of-band signaling bits.
adiQuerySignalState	A	Queries the current inbound out-of-band signaling bits.
adiStartDial	A	Starts DTMF/MF/pulse dialing of digits.
adiStopDial	A	Stops DTMF/MF/pulse dialing of digits.

2.13 Using an On-Board Timer

The ADI service supports one application timer per port. This on-board timer has 10 ms resolution and can be used when the application is controlling the protocol from application space. The following timer functions are provided by the ADI service: Function S/A¹ Description adiStartTimer A Starts an on-board timer. adiStopTimer A Stops an on-board timer. ¹ Synchronous or Asynchronous

Function	S/A¹	Description
adiStartTimer	A	Starts an on-board timer.
adiStopTimer	A	Stops an on-board timer.

2.14 Utility Functions

The following functions retrieve administrative information about your system configuration, or about a specific board: Function S/A¹ Description adiGetBoardInfo S Retrieves information about an AG or QX board. adiGetBoardSlots S Retrieves the board's MVIP configuration. adiGetContextInfo S Retrieves the context status and configuration. adiGetEEPromData S Retrieves OEM data for a given board. adiGetTimeStamp S Converts an event timestamp to a count of the seconds elapsed since January 1, 1970. ¹ Synchronous or Asynchronous Note: adiGetEEPromData and adiGetTimeStamp are not supported on the QX 2000 board. If this function is called on the QX 2000 board, CTAERR_FUNCTION_NOT_AVAIL is returned.

Function	S/A¹	Description
adiGetBoardInfo	S	Retrieves information about an AG or QX board.
adiGetBoardSlots	S	Retrieves the board's MVIP configuration.
adiGetContextInfo	S	Retrieves the context status and configuration.
adiGetEEPromData	S	Retrieves OEM data for a given board.
adiGetTimeStamp	S	Converts an event timestamp to a count of the seconds elapsed since January 1, 1970.

Version

Want to send us feedback on our documentation? Email: Tech_Pubs@nmss.com