Closing Lines

An application should close a line it has open in the following cases:

• Before exiting An application should always close all lines it has open before it becomes inactive.
• For non-TAPI applications TAPI applications should cooperate with non-TAPI applications that use media stream devices such as COM ports. If your TAPI device is a serial device accessed through a COM port (such as a modem) and the line is open, the service provider needs to have the COM port open. But with the COM port open, non-TAPI applications and console applications are prevented from accessing the COM port. Therefore, a TAPI application should open the line (and keep it open) only if it is waiting for incoming calls or it is actively engaged in placing an outgoing call.
• Non-telephony communications applications may need to share resources with telephony applications.

The data structure LINEDEVCAPS contains a capabilities bit (LINEDEVCAPFLAGS_CLOSEDROP) that tells whether closing a line while a call is still active causes calls on the line to be dropped. If TRUE, the service provider drops (clears) all active calls on the line when the last application having that line open closes it using the lineClose function. If the bit is set to FALSE, the service provider does not drop active calls on the line; instead, it leaves these calls active and under the control of an external device or devices, such as phones.

Therefore, an application can examine LINEDEVCAPS to detect in advance whether closing a line will cause this active call to be dropped. The application should warn all appropriate users that the call is about to be dropped, perhaps by displaying an OK/Cancel dialog box that lets the user keep the line open.

For example, if a desktop computer and a phone set are both connected directly to an analog line (in a party-line configuration), the service provider should set the flag to FALSE, as the offhook phone would automatically keep the call active even after the computer is shut down.

As another example, a user is speaking on the phone on a call owned by an active application. The user decides to leave the office for the day and shuts down the system. The operating system in turn shuts down the active telephony application, which attempts to close the lines it has open. Whether the call is automatically disconnected depends on whether the LINEDEVCAPFLAGS_CLOSEDROP bit in LINEDEVCAPS is set or not and whether the phone is offhook.

If other applications are monitoring the call, the service provider will not even be informed that one application has closed the line. It is only when the last application that has a handle to the call closes the line that the service provider is informed (with TSPI_lineClose). At that point, it is up to the service provider to handle any remaining calls. If the service provider is required to drop the calls, it should do so but it should first warn applications about this requirement with the LINEDEVCAPFLAGS_CLOSEDROP flag.

Closing an application should ideally perform the following cleanup tasks:

• Dispose of all calls.
• Close all open lines and phones.
• Shut down the usage of the Telephony API.

Failure to do so may leave calls in indeterminate states.