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.

idle - This corresponds to the "null" state; no activity exists on the call (no call really exists).
offering (inbound) - The switch informs the PC of the arrival of a new incoming call. Note that the offering state is different from having the phone or PC ring. When a call is offered, the PC is not necessarily instructed to alert the user. Let's look at a real life example. An incoming call on a shared call appearance will be offered to all stations that share the appearance; however, typically only the station that has the appearance as its primary address will be instructed to ring. If that station does not answer after some amount of time, the bridging stations may be instructed to ring as well.
accepted (inbound) - An application has accepted an offering call. In ISDN, this has the side effect of initiating the alerting of the user at both the caller's side and the called party side. An offering call can always be answered without first being accepted.
dialtone (outbound) - The call is receiving a dial tone from the switch. The presence of a dial tone indicates that the switch is ready to receive a dialable number. Additional information includes:
- normal dialtone - The "normal" everyday dial tone. This is most often a continuous tone.
- special dialtone - A special dial tone is often used to signal certain conditions such as message-waiting. This is usually an interrupted dial tone.
dialing (outbound) - The originator is dialing digits on the call. The dialed digits are collected by the switch.
proceeding (outbound) - The call is proceeding through the network. This occurs after dialing is complete and prior to the call reaching the dialed party via ringback, busy, or answer.
special info (outbound) - The call is receiving a special information signal. A special information signal precedes a prerecorded announcement indicating why a call cannot be competed.
- no circuit - A no circuit or emergency announcement.
- customer irregularity - This typically means that the dialed number is not correct.
- reorder - A reorder or equipment irregularity announcement.
busy (outbound) - The call is receiving a busy signal. Busy indicates that some resource is not available and the call cannot be normally completed at this time. Additional information consists of:
- station busy - The station at the other end is off-hook (station busy).
- trunk busy - The network is congested. This usually uses a fast busy.
ringback (outbound) - The station to be called has been reached and the destination's switch is generating a ring tone back to the PC. A ringback means that the destination address is being alerted to the call.
connected (inbound and outbound) - Information is being exchanged over the call.
on hold (inbound and outbound) - The call is currently held by the switch. This frees up the physical line, and allows another call to use the line.
conferenced (inbound and outbound) - The call is a member of a conference call and is logically in the connected state (to the conference bridge). A call in the conferenced state refers to a conference call (in the connected, onHold, ... state).
on hold pending conference (inbound and outbound) - This conference call is currently on hold and waiting for the user to add another party.
on hold pending transfer (inbound and outbound) - The call is on hold in preparation of being transferred.
disconnected (inbound and outbound) - The call has been disconnected by the remote party.
unknown (inbound and outbound) - The call exists, but its state is currently unknown. This may be the result of poor call progress detection. Although, under normal circumstances, an outbound call is likely to transition from idle to connected via a number of intermediate states (dial tone, dialing, proceeding, ringback) other paths are often possible. For example, the ringback state may be skipped; a hot phone or non dialed phone may transition directly from idle to connected, etc.
An application should always process call state event notifications. Call state transitions valid for one switch or configuration may be invalid for another. For example, consider a line from the switch that via a simple Y-connector physically terminates both at the PC and at a separate phone set, creating a party line configuration between the PC and the phone set. The PC termination and, therefore, the application using the Telephony API, may have no knowledge about the activities on the line handled by the phone set; i.e., the line may be in use without the service provider being aware of this. An application that wants to make an outbound call will succeed in allocating a call appearance from the API, but really ends up sharing in the active call on the line. Blindly sending a DTMF dial string without checking for dialtone first may not result in intended (or polite) behavior.

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.