2.4.2.2 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 (e.g., data type, higher level protocol) of this media stream. The Telephony SPI allows the TAPI 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. Note that 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 determination is done, the TAPI DLL is simply informed about media mode changes on a call.

The media modes defined by the SPI 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 human 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 human at the application's end (i.e., this could be an answering machine application). It is unlikely that a Service Provider will be able to distinguish between interactive and automated voice for incoming calls. Consequently, it should treat or report incoming voice calls that it cannot distinguish as interactive voice.
digital data - A digital data stream of unspecified format.
G3 fax - A group 3 fax session on the call.
G4 fax - A group 4 fax session on the call.
data modem - A modem session on the call. Note that 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. How the service provider makes this determination is its choice. 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.
teletex, videotex, mixed - These corresponds to the telematic services with the same names.
TDD - The call's media stream uses the Telephony Devices for the Deaf protocol.
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/disabled via TSPI_lineMonitorMedia. The TAPI DLL specifies which media modes it is interested in monitoring. If enabled, the detection of a media mode causes the TAPI DLL to be notified via the LINE_MONITORMEDIA callback. The callback provides the call handle on which the media mode change was detected as well as the new media mode.

TSPI_lineMonitorMedia

Enables or disables media mode notification on a specified call.

LINE_MONITORMEDIA

Notifies the TAPI DLL about a media mode change.

There is a distinction between the media mode of a call as reported by TSPI_lineGetCallInfo, and the media mode event reports by LINE_MONITORMEDIA messages. A call's media mode is determined exclusively by the TAPI 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 the TAPI DLL.

Note that 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 TAPI DLL can obtain device IDs for various Windows 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 ID for the device of the given device class that is associated with the open line device, address, or call. If the device class is line, then the device ID of the line device is returned. If the device class is mci waveaudio, then the device ID of an mci waveaudio device is returned (if supported) that allows the recording/playback etc. of audio over the call on the line.

TSPI_lineGetID

Retrieves a device ID associated with the specified open line, address, or call.

The TAPI DLL can use the returned device ID with the corresponding media API to query the device's capabilities and subsequently open the media device. For example, if the TAPI DLL's client application needs to use the line as a waveform device, it will first have to call waveInGetDevCaps and/or waveOutGetDevCaps to determine the waveform capabilities of the device. The typical wave form data format supported by telephony in North America is 8-bit m-law at 8000 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, address, or call device 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 has not been answered yet when invoking the function, for example, the waveOutOpen driver may return an error code message to the application allowing it to put up a dialog box 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 can deal with it.