2.4.1.8 Call States and Events

Strictly speaking, a connection is not fully established until both parties are communicating, but there are, in fact, several stages involved in establishing and clearing a call. Events occur on a call that cause the call to transition through several call states as it comes into existence, is used to exchange information, and terminates. Call state transitions result from both solicited and unsolicited events. A solicited event is one caused by the application controlling the call (e.g., by invoking operations in the API, through the TAPI DLL to the TSPI), while the switch, the telephone network, or the actions of the remote party cause unsolicited events. Note that operations on line devices, addresses, and calls may require the line, address, or call upon which they operate to be in certain specific states.

Whenever a call changes state, the SPI reports the new state in a callback to the TAPI DLL. Due to the asynchronous way in which these reports arrive and are forwarded to the TAPI DLL's client applications, the programming model the application developer should follow is not one that preassumes a rigid call state machine, but one where the application should react to the events reported to the application. In other words, call state notification does not report transitions that, depending on the current state of the call (known to the application), may force a transition to another state (computed by the application). Instead the notification simply tells the application what the call's new state is.

Some of the Telephony SPI defined call states and events are exclusive to inbound or outbound call processing, while others occur in both cases. Several of these call states provide additional information that may be of use to the application. For example, the busy state signifies that a call cannot be completed because a resource between the originator and the destination is unavailable. Information supplied with the busy state includes station busy or trunk busy. Station busy indicates that the destination's station was busy (e.g., phone is offhook); trunk busy means a circuit in the switch or network was busy. Call states defined by the Telephony SPI are listed below.

LINE_CALLSTATE

Sent to an application to notify it about changes in a call's state.

TSPI_lineGetCallInfo

Returns mostly constant information about a call as a data structure of type LINECALLINFO.

TSPI_lineGetCallStatus

Returns complete call status information for the specified call as a data structure of type LINECALLSTATUS.

The call information data structure maintained for each call contains an application-specific field that applications can read and write. This field is not interpreted by the SPI. Apps can use it to "tag" calls in application-specific ways. Writing the field such that the change becomes visible to other applications requires that the application use TSPI_lineSetAppSpecific.

TSPI_lineSetAppSpecific

Sets the application specific field of a call's information structure.