Opening and Closing Line Devices

After performing basic initialization and possibly having retrieved device capabilities, tapi32.dll must open the line device before it can access telephony functions on that line. When a line device is opened successfully, tapi32.dll is returned a handle representing the open line. The TSPI_lineOpen function opens a specified line device for providing subsequent monitoring and/or control of the line. TSPI_lineClose closes a specified line device.

At the TAPI level, a line device can be specified to lineOpen in one of two ways:

• A specific line device is selected by means of its line device identifier. The lineOpen request opens the specified line device, possibly resulting in a TSPI_lineOpen call to the service provider (that is, if the line was not already open). Applications interested in handling inbound calls typically use specific line devices.
• The application can specify that it wants to use any line device that has certain properties. The LINEMAPPER indication is used instead of a specific line device identifier. The properties are specified by means of the call parameters that the application intends to use. The tapi32.dll satisfies this Open request with any available line device that supports the specified call parameters, but this may fail. If successful, the caller can determine the line device identifier by calling lineGetID on the handle to the open line device returned by lineOpen.

To support LINEMAPPER selection of lines, the service provider must implement the TSPI_lineConditionalMediaDetection function. This function does two things: (1) it tests a line's ability to support the requested call parameters and media mode, and (2) if successful, it commits the service provider to monitoring for the new media mode. The tapi32.dll uses this function for different line devices to hunt for a line that meets the application's Open requirements.