2.4.1.2 Lines
A line device can represent a pool of homogeneous resources (i.e., channels) that are used to establish calls. The Telephony SPI in a client PC typically provides access to one or more line devices.
All line devices support at least the basic telephony services. If the TAPI DLL's client application is interested in using supplementary and/or extended telephony services, then the application must first determine the exact capabilities of the line device. Telephony capabilities vary with configuration (e.g., client versus client/server), hardware, service provider software, and the telephone network. Applications should make no assumptions as to what telephony capabilities are available beyond just basic telephony services. The TAPI DLL determines the line's device capabilities on behalf of an application via TSPI_lineGetDevCaps.
TSPI_lineGetDevCaps
Returns the supplementary and extended capabilities of a given line device as a data structure of type LINEDEVCAPS.
Here are some examples of how a service provider might model various configurations:
Example 1 - A single POTS line in the phone-centric or PC-centric connection models would most straightforwardly be modeled as a single line device with one channel.
Example 2 - A single BRI-ISDN line in the phone-centric or PC-centric models. The service provider has a number of options as to how it may want to model this. Some are described below.
- Model the BRI line as a single line device with a pool of two channels allowing both channels to be combined for establishing 128 kbps calls.
- Model each B-channel as a separate line device and disallow both channels to be combined into a single 128 kbps channel.
- Model the BRI connection as two separate line devices, each drawing up to 2 channels from a shared pool of 2 B-channels.
- Model as three line devices, one for each B-channel, and one for the combination. Clearly in the latter two models, resources may be assigned to different line devices at different times.
Example 3 - In client/server systems a pool of telephone ports attached to a server may be shared among multiple client PCs via a local area network. The pool may be administered to assign a maximum number of line devices (quota) to each client workstation. It is not unusual for the sum of all quotas to exceed the total number of lines. Furthermore, a given client with quota equal to 2 may be satisfied by using ports 1 and 2 at one time and ports 7 and 11 at a later time. The service provider for the pool may model this arrangement by providing each client workstation access to two line devices.
Suppose that the configuration of Service Providers for a given PC is such that this particular Service Provider gets a DeviceIDBase of 3. This implies that the (fixed) device IDs for this client are 3 and 4. If later the application calls lineGetDevCaps for device 3 and again for device 4, it should be able to assume that the device capabilities for each of these devices will be constant, since that is the Windows device model. As long as the given PC's Service Provider configuration remains constant, the device IDs that appear at the TSPI level remain constant even if the server changes port allocations. For server based devices that are pooled as described in the example above, this only holds for line devices that have identical device capabilities. Of course, if the given PC's Service Provider configuration is changed such that this Service Provider gets a different DeviceIDBase, device IDs will change correspondingly.
Example 4 - Switch-to-host link.
- To provide personal telephony to each desktop, the service provider could model the PBX line paired with the PC as a single line device with one channel. Each client PC would have one line device available.
- Model each third party station as a separate line device. This enables the application to control calls on other stations. This solution requires that the application open each line it wants to manipulate or monitor, which may be fine if only a small number of lines is of interest, but may generate a lot of overhead if a large number of lines is involved.
- Model the set of all third party stations as a single line device with one address (e.g., phone number) assigned to it per station. Only a single device is to be opened, providing monitoring and control of all addresses on the line (i.e., all stations). To originate a call on any of these stations, the application only needs to specify the station's address to the operation that makes the call. No extra open operations are required. This modeling does imply that all stations have the same line device capabilities, although their address capabilities could be different.
Note that all of the examples discussed are simply different ways that a service provider may choose to implement the mapping of line device behavior onto some physical realization.
The TAPI DLL is notified about changes in the status of a line device via the LINE_LINEDEVSTATE callback message. The TAPI DLL can control line status items for which it wants to be notified via the function TSPI_lineSetStatusMessages. It can determine the complete status of a line device by calling TSPI_lineGetLineDevStatus.
TSPI_lineGetLineDevStatus
Returns current status of the specified open line device via a structure of type LINEDEVSTATUS.
LINE_LINEDEVSTATE
Sent to the application to notify it about changes in the line status. This message indicates which status item has changed.
TSPI_lineSetStatusMessages
Select the line and address (see further) for which the app wants to receive status change notification messages. The messages controlled by this operation are LINE_LINEDEVSTATE and LINE_ADDRESSSTATE.