The lineGetNumRings function can be used by any application to determine the number of times an incoming call on the given address should ring before the call is to be answered. Waiting a certain number of rings allows callers to be spared the charge of a call connection if it seems that the call will not be answered by the desired party (usually a person). This feature is sometimes called toll-saver support. Applications can use the lineGetNumRings and lineSetNumRings functions in combination to provide a mechanism to support toll-saver features for multiple independent applications.
Any application that receives a handle for a call in the offering state and a LINE_LINEDEVSTATE 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 number of rings any application has specified with the lineSetNumRings function. Because this number may vary dynamically, an application should call lineGetNumRings each time it has the option to answer a call—that is, when it is the owner of a call still in the offering state. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle.
If the service provider is set to auto-answer calls, it answers after a certain number of rings. Service providers do not have access to the minimum-ring information established by lineSetNumRings, and therefore will make their own determination of when to automatically answer an incoming call. When a call has been so answered by a service provider, it will be initially delivered to the owning application already in the connected state, so the application will not need to be concerned with counting rings or with answering the call.