3.1 Introduction

3.2 CX 2000 Modes

3.3 Enabling Station Power

3.4 Monitoring Signaling Bits

3.4.1 Stopping Signal Detection

3.5 Ringing

3.5.1 Stopping Ringing

3.6 DTMF Detection

3.6.1 Stopping DTMF Detection

3.7 Transmitting Tones

3.7.1 Stopping Tone Transmission

3.8 On-Board Timers

3.9 Sending and Receiving Signaling Patterns

3.9.1 Querying Signaling Bits

3.9.2 Asserting a Signaling Pattern at a Station

3.1 Introduction

This chapter describes the CDI service low-level call control functions. These functions manage call control, DTMF detection, and tone generation.

The CDI service provides the following station-oriented call control functionality:

• Tone generation

• DTMF detection

• Signaling (on-hook, off-hook, flash-hook, ringing)

• On-board timers

The following low level call control functions are available in the CDI service on a per-context basis:

If you want to...	Then use...
Supply power to the telephone	cdiEnableBattery
Remove the power from the telephone	cdiDisableBattery
Start monitoring the signaling bits	cdiStartSignalDetector
Stop monitoring the signaling bits	cdiStopSignalDetector
Enable the DTMF detector	cdiStartDTMFDetector
Disable the DTMF detector	cdiStopDTMFDetector
Start the transmission of a tone	cdiStartTones
Stop the tone transmission	cdiStopTones
Start ringing a station	cdiStartRing
Stop ringing a station	cdiStopRing
Start (or restart) a timer	cdiStartTimer
Abort the timer operation	cdiStopTimer
Assert a supervisory signaling pattern to the line	cdiAssertSignal
Get the current state of the supervisory signaling pattern	cdiGetSignalState

See Chapter 5 for a detailed function reference. See Appendix C for default parameters.

3.2 CX 2000 Modes

The CX 2000 and CX 2000C DSP software normally operates in enhanced mode. In this mode, the Digital Signal Processor (DSP) performs various operations that otherwise would have to be taken on by the host application (for example, stopping tones or DTMF detection upon on-hook). In enhanced mode, the DSP also performs extra contextual error-checking (for example, denying DTMF detection if on-hook or denying ring if off-hook).

Enhanced mode:

• Lowers the host-DSP message traffic.

• Improves system response time.

• Maximizes the use of shared resources, if any (for example, DTMF detector resources).

• Assists debugging of user applications by providing contextual errors.

• Provides flash-hook detection.

In limited situations, you may find it useful to disable enhanced mode, for legacy software needs, or for prototyping or debugging purposes. To enable or disable enhanced mode, set or clear the EnhancedMode parameter in the CDI_GLOBAL_PARMS structure. (See Appendix C.)

The behavior of the following four functions is affected by whether enhanced mode is enabled:

• cdiStartDTMFDetector

• cdiStartRing

• cdiStartSignalDetector

• cdiStartTones

Enhanced mode is enabled by default.

3.3 Enabling Station Power

Before a station can be used, power (battery) must be supplied to it. To supply power to a station attached to a board, invoke cdiEnableBattery with the context handle to the board. This function connects the DC loop power to the station and enables the audio. cdiEnableBattery returns SUCCESS or an error code.

To disable power to a station, invoke cdiDisableBattery with the context handle to the board. This function removes the DC loop power from the station and disables the audio.

3.4 Monitoring Signaling Bits

Once battery is enabled, the DSP can monitor signaling bits. To start on-board monitoring of the A signaling bit for a station, invoke cdiStartSignalDetector. In the invocation, pass a pointer to the CDI_SIGNALDETECTOR_PARMS structure:

typedef struct
{
DWORD size;                  /* Size of this structure                   */
DWORD timeon;                /* Off-hook deglitch time                   */
DWORD timeoff;               /* On-hook deglitch time                    */
DWORD min_flash_hook;        /* Minimum time to qualify for flash-hook   */
DWORD max_flash_hook;        /* Beyond this time, this is a disconnect   */
} CDI_SIGNALDETECTOR_PARMS;

If monitoring is started successfully, cdiStartSignalDetector returns SUCCESS, and signal monitoring events are enabled. Subsequent events indicate bit state changes.

Monitoring operates differently depending upon whether the DSP is running in enhanced mode or not. When operating in enhanced mode, the DSP qualifies bit changes, and events are presented to the application as described in the following table:

If bits indicate state change from:	This event is presented to the application:
Qualified on-hook to off-hook (more than timeon ms).	CDIEVN_OFF_HOOK
All off-hook to on-hook transitions less than min_flash_hook are ignored.	No events.
Qualified off-hook to on-hook (more than min_flash_hook and remains on for less than max_flash_hook).	CDIEVN_FLASH_HOOK
Qualified off-hook to on-hook (more than max_flash_hook).	CDIEVN_ON_HOOK

If enhanced mode is disabled, cdiStartSignalDetector indicates if the A bit is on or off whenever its status changes. The following events are returned:

Bit state change	Event presented to app:
Qualified off to on (more than timeon).	CDIEVN_A_CHANGE_ON
Qualified on to off (more than timeoff).	CDIEVN_A_CHANGE_OFF

3.4.1 Stopping Signal Detection

If enhanced mode is enabled, the DSP automatically stops detecting signaling from a station when the station goes on-hook (CDIEVN_ON_HOOK is returned). If enhanced mode is disabled, the application can invoke cdiStopSignalDetector to stop detection.

If the station is on-hook, and cdiStopSignalDetector is invoked, CTAERR_FUNCTION_NOT_ACTIVE is returned.

3.5 Ringing

As long as a station is on-hook, an application can cause it to ring. To cause a station to ring, invoke cdiStartRing. In the invocation, pass a pointer to the CDI_RING_PARMS structure:

typedef struct
{
DWORD size;                  /* Size of this structure              */
DWORD cadence_type;          /* Type of ring                        */
} CDI_RING_PARMS;

Set cadence_type to the ring pattern (cadence). CX 2000 products are pre-configured with three different 6-second cadences to choose from (see Figure 2):

Figure 2. CX 2000/C Pre-Configured Ring Cadences

Note: You can change one or more of these cadences, if you wish. For more information, see the CX 2000 and CX 2000C Installation and Developer's Manual.

cdiStartRing cannot be invoked for a station while that station is ringing. If this function is invoked during an ongoing ring, CTAERR_FUNCTION_ACTIVE is returned.

3.5.1 Stopping Ringing

If enhanced mode is enabled, the DSP automatically stops ringing a station when the station goes off-hook (CDIEVN_OFF_HOOK is returned). If enhanced mode is disabled, the application can invoke cdiStopRing to stop an ongoing ring.

If the station is off-hook, and cdiStopRing is invoked, CTAERR_FUNCTION_NOT_ACTIVE is returned.

3.6 DTMF Detection

When a station is off-hook, the DSP can detect DTMF tones and return their values to the application. To start DTMF detection, invoke cdiStartDTMFDetector. In the invocation, pass a pointer to the CDI_DTMFDETECTOR_PARMS structure:

typedef struct
{
DWORD size;                  /* Size of this structure                     */
DWORD onqualtime;            /* Minimum duration for DTMF detected         */
DWORD offqualtime;           /* Minimum duration for end of DTMF detected  */
DWORD DTMF_mode;             /* Mode of DTMF detection                     */
} CDI_DTMFDETECTOR_PARMS;

If detection is started successfully, cdiStartDTMFDetector returns SUCCESS. Subsequent events indicate detected tones.

A CDIEVN_DTMF_STARTED event is generated for each detected tone that lasts longer than onqualtime. The event value field contains the ASCII representation of the key. When the tone ends, CDIEVN_DTMF_ENDED is generated.

DTMF_mode determines precisely when the CDIEVN_DTMF_STARTED event is sent to the application:

If DTMF_mode is...	CDIEVN_DTMF_STARTED is generated:
0	After the qualification time (onqualtime).
1	When the key is released.

The offqualtime parameter determines the minimum interval of silence between tones for the detector to consider them two distinct tones.

If cdiStartDTMFDetector is invoked, and the DSP does not have enough MIPS to satisfy the request, CTAERR_OUT_OF_RESOURCES is returned.

3.6.1 Stopping DTMF Detection

If enhanced mode is enabled, the DSP automatically stops DTMF detection for a station when the station goes on-hook (CDIEVN_ON_HOOK is returned). If enhanced mode is disabled, the application can invoke cdiStopDTMFDetector to stop detection.

If the station is on-hook, and cdiStopDTMFDetector is invoked, CTAERR_FUNCTION_NOT_ACTIVE is returned.

3.7 Transmitting Tones

When a station is off-hook, you can cause your CX 2000 or CX 2000C board to transmit tones to the station. Each tone can consist of one or two frequency components, each at different amplitudes. You can also set up a pattern (cadence) of up to two iterations of the tone, each of different lengths.

To start the transmission of a tone, invoke cdiStartTones. In the invocation, pass a pointer to the CDI_TONE_PARMS structure:

typedef struct
{
DWORD size;        /* Size of this structure                              */
DWORD freq1;       /* First/only frequency of the generated tone          */
DWORD freq2;       /* Second frequency of the generated tone              */
INT32 ampl1;       /* Amplitude of the first/only frequency component     */
INT32 ampl2;       /* Amplitude of the second frequency component         */
DWORD ontime;      /* Duration of tone, single cadence generation         */
DWORD offtime;     /* Duration of silence between tones, single cadence   */
DWORD ontime2;     /* Duration of tone, double cadence generation         */
DWORD offtime2;    /* Duration of silence between tones, double cadence   */
INT32 iterations;  /* Number of repeats of the tone/silence period        */
} CDI_TONE_PARMS;

The parameters in this structure are described in Chapter 5.

Figure 3 illustrates how the parameters in CDI_TONE_PARMS determine the cadence:

Figure 3. Cadence Parameters

If the function invocation is successful, cdiStartTones returns SUCCESS. When tone transmission is complete, CDIEVN_TONE_DONE is generated.

cdiStartTones cannot be invoked for a station while the DSP is currently playing a tone at that station. If this function is invoked during an ongoing tone, CTAERR_FUNCTION_ACTIVE is returned.

3.7.1 Stopping Tone Transmission

If enhanced mode is enabled, the DSP automatically stops transmitting tones to a station when the station goes on-hook (CDIEVN_ON_HOOK is received), or a DTMF tone is detected (CDIEVN_DTMF_STARTED is received). If enhanced mode is disabled, the application can invoke cdiStopTones to stop transmission.

If the station is on-hook, and cdiStopTones is invoked, CTAERR_FUNCTION_NOT_ACTIVE is returned.

3.8 On-Board Timers

The CDI service supports one on-board timer per CTA context on a CX 2000 or CX 2000C board. You can set up this timer to run for a specified amount of time and then expire, returning an event to the application. Alternatively, you can configure the timer to tick, generating a specified number of tick events at a periodic rate before expiring.

To set up the timer, invoke cdiStartTimer with a context handle, and a timeout and count value.

To configure the timer to run once and then expire, set timeout to the timeout length (in ms), and set count to 1. When the timer is started, CDIEVN_TIMER_START is generated. When the timer expires, CDIEVN_TIMER_DONE is returned. The value field of this event contains CTA_REASON_FINISHED.

To configure the timer to "tick," set timeout to the tick rate (in ms), and set count to the number of ticks the application requires. When the timer is started, CDIEVN_TIMER_START is generated. As the timer ticks, CDIEVN_TIMER_TICK events are generated. On the final tick, CDIEVN_TIMER_DONE is returned. The value field of this event contains CTA_REASON_FINISHED.

The timer has a 2 ms resolution.

You can abort a timer by invoking cdiStopTimer with the context handle. cdiStopTimer returns SUCCESS if successfully invoked. When the timer is stopped, CDIEVN_TIMER_DONE is generated. The value field of this event contains CTA_REASON_STOPPED. If you invoke cdiStopTimer, and the timer has already stopped, CDIEVN_TIMER_STOPPED is generated.

3.9 Sending and Receiving Signaling Patterns

You can query the current state of the supervisory signaling bits, using cdiGetSignalState. You can also assert a supervisory signaling pattern at a station, using cdiAssertSignal.

These functions are not intended for use in typical applications. Ordinarily, the supervisory signaling is transparently controlled by the on-board DSP. Use these functions when special-purpose applications require explicit control of the supervisory signaling. In such cases, disable enhanced mode as described in Section 3.2.

3.9.1 Querying Signaling Bits

To get the current state of the supervisory signaling bits for a station, invoke cdiGetSignalState, passing the context handle to the station. cdiGetSignalState returns a pointer to a value indicating the state of the bits:

Pattern Value	Description
00000xxx1	The bits are low (the station is on-hook).
00001xxx	The bits are high (the station is off-hook).

1 xxx is any value.

Note: This function should not be used when enhanced mode is enabled.

3.9.2 Asserting a Signaling Pattern at a Station

To assert a signaling pattern at a station, invoke cdiAssertSignal. With the invocation, pass the context handle to the station, and one of the following values:

Pattern Value	Description
0x00	Battery off, no ringing
0x08	Battery on, no ringing
0x0C	Battery on, continuous ringing

Note: This function should not be used when enhanced mode is enabled.