Media Monitoring

When a call is in the connected state, information can be transported over the call. A call's media mode provides an indication of the type of information (for example, the datatype or higher-level protocol) of this media stream. TSPI allows tapi32.dll to be provided with a callback notification about changes in a call's media mode. The notification provides an indication of the call's new media mode. 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 mode, 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 mode is determined, tapi32.dll is simply informed about media mode changes on a call.

The media modes defined by Win32 Telephony include:

• Unknown The media mode of the call is not currently known; the call is unclassified.
• Interactive voice Voice energy was detected on the call, and the call is handled as an interactive voice call with a person at the application's end.
• Automated voice Voice energy was detected on the call, and the call is handled as a voice call but with no person at the application's end, such as with an answering-machine application. When the service provider cannot distinguish between interactive and automated voice on an incoming call, it should treat or report the call as interactive voice.
• Data modem A modem session on the call. Current modem protocols require the called station to initiate the handshake. For an inbound data modem call, the application can typically make no positive detection. The service provider chooses how to make this determination. For example, a period of silence just after answering an inbound call may be used as a heuristic to decide that this might be a data modem call.
• G3 fax A group 3 fax session on the call.
• TDD The call's media stream uses the Telephony Devices for the Deaf (TDD) protocol.
• G4 fax A group 4 fax session on the call.
• Digital data A digital data stream of unspecified format.
• Teletex, Videotex, Telex, Mixed These correspond to the telematic services of the same names.
• ADSI An Analog Display Services Interface session on the call. ADSI enhances voice calls with alphanumeric information downloaded to the phone and the use of soft buttons on the phone.

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

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

Default media mode monitoring for calls is performed for the media modes for which the line device has been set. This allows an inbound call's media mode to be determined early based on what is needed by tapi32.dll.

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.

The tapi32.dll 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.

The tapi32.dll 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 tapi32.dll 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.