The TSPI_lineMonitorMedia function enables and disables the detection of media modes on the specified call. When a media mode is detected, a LINE_MONITORMEDIA message is sent to TAPI.
LONG TSPI_lineMonitorMedia(
HDRVCALL hdCall,
DWORD dwMediaModes
);
Note INTERACTIVEVOICE and AUTOMATEDVOICE are equivalent for monitoring purposes.
Note INTERACTIVEVOICE and AUTOMATEDVOICE are equivalent for monitoring purposes.
A value of 0 for the dwMediaModes parameter cancels all media mode monitoring.
Returns zero if the function succeeds, or an error number if an error occurs. Possible return values are as follows:
LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.
The service provider returns LINEERR_INVALMEDIAMODE if the list of media types to be monitored contains invalid information.
This function returns zero (success) when media mode monitoring has been correctly initiated, not when media mode monitoring has terminated. Media monitoring for a given media mode remains in effect until it is explicitly disabled by calling TSPI_lineMonitorMedia with a dwMediaModes parameter with the media mode set to zero, or until the call transitions to idle.
TSPI_lineMonitorMedia is primarily an event reporting mechanism. The media mode of a call, as indicated in LINECALLINFO, is not affected by the service provider's detection of the media mode. Only TAPI or a client application can change a call's indicated media mode using TSPI_lineSetMediaMode. The actual use of a particular media mode occurs through separate media stream APIs (such as Comm or WAVE).
Default media monitoring performed by the service provider for a new call appearance corresponds to the union of all media modes specified by TSPI_lineSetDefaultMediaDetection. Shortly after a new call is established, TAPI typically calls TSPI_lineMonitorMedia to reduce the set of media modes detected and reported for this call to the union of all media modes desired by the call's client applications.
The service provider must cancel media monitoring when a call goes idle. TAPI must compute the union of media modes desired by all clients, and pass the result to this function. The service provider uses the set passed to this function by TAPI.
Although this function can be invoked in any call state, a call's media mode can typically only be detected while the call is in certain call states. These states can be device specific. For example, in ISDN a message can indicate the media mode of the media stream before the media stream exists. Similarly, distinctive ringing or the called ID information about the call can be used to identify the media mode of a call. Otherwise, the call may have to be answered (call in the connected state) to allow a service provider to determine the call's media mode by filtering of the media stream. Because filtering of a call's media stream implies a computational overhead, TAPI typically uses this procedure to disable media monitoring when it is not required.
Because media-mode detection enabled by TSPI_lineMonitorMedia is implemented as a read-only operation of the call's media stream, it is not disruptive. No signals are sent on the line as a result of setting TSPI_lineMonitorMedia.
Regarding the passed media mode, TAPI guarantees that there are no reserved bits set. The service provider must perform any further validity checks on the media modes, such as checking whether any media modes are indeed supported by the service provider.
LINE_MONITORMEDIA, LINECALLINFO, LINEDEVCAPS, LINEMEDIAMODE_ Constants TSPI_lineConditionalMediaDetection, TSPI_lineGetDevCaps, TSPI_lineSetDefaultMediaDetection, TSPI_lineSetMediaControl, TSPI_lineSetMediaMode