A line device is a physical channel composed of a telephone line and the hardware that controls it, such as a fax board, a modem, or an ISDN card. The simplest kind of line device corresponds to exactly one telephone line. In general, telephony allows a line to contain a pool of multiple homogeneous channels that can be used to establish calls. A service provider that implements a line as a pool of channels allocates those channels out of a set of physical lines it controls, or multiplexes multiple channels onto a single physical line. Although the term line often connotes something with two endpoints, within TAPI the term refers just to one endpoint of a communication channel or point of entry into a telephone switching network.
Depending on the environment, a service provider can restrict calls to one per line as in POTS, allow switching between several calls on a single line while others go on hold, or allow multiple calls to be active concurrently.
The following illustration displays the variety of hardware (driven by the same TSPI functions) that can exist within one configuration.
Although the four lines in the preceding illustration employ different hardware and are used for different functions, their respective service providers abstract them to the same device type, and they are controlled through the same TSPI functions. In the case of the voice-oriented Line 4, its service provider may allow the line to be directly connected to a telephone handset for incoming or outgoing calls. The service provider may also allow software access to the phone by making it available as an instance of the phone-device class, which is described in Device Classes.
TAPI requires that every TAPI-capable line device support all of Basic Telephony. If an application needs to use capabilities beyond those of Basic Telephony (namely Supplementary or Extended Telephony), it must first determine the line device's capabilities, which can vary according to network configuration (client versus client/server), hardware, service-provider software, and the telephone network.
The TSPI_lineGetDevCaps function queries a specified line device to determine its telephony capabilities. The returned information is valid for all addresses on the line device. The dwExtVersion parameter of TSPI_lineGetDevCaps indicates the version number of the extension information requested. If it is zero, no extension information is requested. If it is nonzero, it holds a value that was already negotiated for this device with the TSPI_lineNegotiateExtVersion function. The service provider should fill in device- and vendor-specific extended information according to the extension version specified.
Note The service provider should also fill in all the members of the LINDEVCAPS data structure, except for dwTotalSize, which is filled in by tapi32.dll. The service provider must not overwrite the dwTotalSize member.