# 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.

Refer to Ringing for more information.

#### See also

cdiStopRing