Media Monitoring

When a call is in the connected state, information can be transported over the call. A call's media type provides an indication of the type of information (for example, the datatype or higher-level protocol) of this media stream. TSPI allows TAPI to be provided with a callback notification about changes in a call's media type. The notification provides an indication of the call's new media type. The service provider decides how it wants to make this determination.

For example, the provider could use signal processing of the media stream to determine media type, or it could rely on distinctive ringing patterns assigned to different media streams, or on information elements passed in an out-of-band signaling protocol. Independent of how the media type is determined, TAPI is simply informed about media type changes on a call.

The media types defined by Microsoft Telephony can be found under LINEMEDIAMODE_ Constants.

Media monitoring can be enabled and disabled on a specified call with TSPI_lineMonitorMedia. TAPI specifies which media types it is interested in monitoring. If media monitoring is enabled, the detection of a media type causes TAPI to be notified in the LINE_MONITORMEDIA callback message, which notifies TAPI about a media type change. The callback provides the call handle on which the media type change was detected as well as the new media type.

There is a distinction between the media type of a call as reported by TSPI_lineGetCallInfo and the media type event reports in LINE_MONITORMEDIA messages. A call's media type is determined exclusively by TAPI and is not automatically changed by media monitoring events.

Default media type monitoring for calls is performed for the media types for which the line device has been set. This allows an inbound call's media type to be determined early based on what TAPI needs.

Note  The scope of a call's media monitoring of a call is bound by the lifetime of the call. Media monitoring on a call ends as soon the call disconnects or goes idle.

TAPI can obtain device identifiers for various Win32 device classes associated with an opened line by invoking TSPI_lineGetID. This function takes a line handle, address, or call handle and a device class description. It returns the device identifier for the device of the given device class that is associated with the open line device, address, or call. If the device class is tapi/line, the device identifier of the line device is returned. If the device class is mci wave, the device identifier of an mci waveaudio device (if supported) is returned that allows the manipulation such as recording or playback of audio over the call on the line.

TAPI can use the returned device identifier with the corresponding media API to query the device's capabilities and subsequently open the media device. For example, if the TAPI client application needs to use the line as a waveform device, it first needs to call waveInGetDevCaps and/or waveOutGetDevCaps to determine the waveform capabilities of the device. The typical waveform data format supported by telephony in North America is 8-bit m-law at 8,000 samples per second, although the wave device driver can convert this sample rate and companding to other more common multimedia audio formats.

To subsequently open a line or address for audio playback using the waveform API, an application calls the waveOutOpen function. The implementation of the waveOutOpen call is device-specific, and each implementation has a number of options for implementing this function. If the call is not answered at the time the function is invoked, for example, the waveOutOpen driver may return an error code message to the application allowing it to display a dialog box stating that "the phone is ringing." This is similar to requesting a CD to play back audio when no compact disc is in the player, and the existing definition of the waveform APIs should handle the situation.