lineGetNumRings  C33HY4 

The lineGetNumRings function determines the number of rings an inbound call on the given address should ring prior to answering the call.

LONG lineGetNumRings(

Parameters

hLine

A handle to the open line device.

dwAddressID

An address on the line device.

lpdwNumRings

The number of rings that is the minimum of all current lineSetNumRings_8ZHKV requests.

Return Values

Returns zero if the request is successful or a negative error number if an error has occurred. Possible return values are:

LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Remarks

The lineGetNumRings and lineSetNumRings functions, when used in combination, provide a mechanism to support the implementation of toll-saver features across multiple independent applications.

An application that receives a handle for a call in the offering state and a LINE_LINEDEVSTATE1F9WSNT ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll-saver settings across all applications. The lineGetNumRings function returns the minimum of all application's number of rings specified by lineSetNumRings. Because this number may vary dynamically, an application should invoke lineGetNumRings each time it has the option to answer a call. If no application has called lineSetNumRings, the number or rings returned is 0xFFFFFFFF. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle.

If call classification is performed by TAPI of answering all calls of unknown media mode and filtering the media stream, TAPI honors this number as well.

Note that this operation is purely informational and does not in itself affect the state of any calls on the line device.

See Also