cdiStartRing

Starts station ringing.

Prototype

DWORD cdiStartRing ( CTAHD ctahd, CDI_RING_PARMS *parms )

Argument

Description

ctahd

Context handle.

parms

Pointer to a structure specifying ring cadence:

typedef struct
{
DWORD size;
DWORD cadence_type;
} CDI_RING_PARMS

Refer to the Details section for more information.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	Argument is not in the valid range.
CTAERR_BOARD_ERROR	Board is overheating, and has reached the protection state. At this stage, the board does not accept or place calls on any ports. Refer to Monitoring board temperature for more information.
CTAERR_FUNCTION_ACTIVE	Function was already invoked, and the DSP is ringing the station.
CTAERR_INVALID_CTAHD	Handle is invalid.
CTAERR_INVALID_STATE	Port must be on-hook to invoke this function.

Events

Event	Description
CDIEVN_RING_IS_OFF	Ring cycle finished. FSK transmission is allowed.
CDIEVN_RING_IS_ON	Ring cycle started. FSK transmission is not allowed until CDIEVN_RING_IS_OFF is received.

Details

cdiStartRing causes an on-hook station to ring. The cadence_type parameter in CDI_RING_PARMS determines the pattern (cadence) of the ring. CX 2000 products are preconfigured with three different 6-second cadences to choose from:

cadence_type setting	Cadence
0	"ring...ring..."
1	"ring ring...ring ring..."
2	"ring ring ring...ring ring ring..."

You can change one or more of these cadences. For more information, refer to the CX 2000 Installation and Developer's Manual or the CX 2000C Installation and Developer's Manual.

If the board is running in enhanced mode, the DSP automatically stops ringing when the station is taken off-hook. Otherwise, invoke cdiStopRing to stop ringing a station.

Coordinating caller ID FSK with ring

CX boards can be configured to generate events that track ring cycles. The primary application for this is FSK caller ID generation. An application can determine when the first ring cycle is complete and can switch through and enable FSK generation on another resource board in the system to send caller ID between the first two ring cycles.

To enable the ring cycle events after cdiStartRing is invoked, use the OR operator to include RING_CYCLE_EVENTS_MASK in the EnhancedMode variable of the CDI_GLOBAL_PARMS structure. These events track ring cycles, not the individual ring bursts comprised in the cadence of the ring cycle.

Note: Depending upon the exact timing of when cdiStopRing is called, a trailing ring event may occur after calling cdiStopRing.