Share via

TSPI_lineMonitorMedia (Compact 2013)

  • Article

3/26/2014

This function enables and disables the detection of media types on the specified call. When a media type is detected, a LINE_MONITORMEDIA message is sent to TAPI.

Syntax

LONG TSPIAPI TSPI_lineMonitorMedia(
  HDRVCALL hdCall, 
  DWORD dwMediaModes 
);

Parameters

  • hdCall
    Handle to the call for which media monitoring is to be set. The call state of hdCall can be any state except idle.

  • dwMediaModes
    Media types to be monitored. The dwMediaModes parameter can have one of the LINEMEDIAMODE constants.

    A value of zero cancels all media type monitoring.

Return Value

Returns zero if the function succeeds, or an error number if an error occurs. The following table shows the return values for this function.

Value

Description

LINEERR_INVALCALLHANDLE

The handle to the call is invalid.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

LINEERR_INVALCALLSTATE

The call state is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALMEDIAMODE

The media mode is invalid.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

LINEERR_NOMEM

Not enough memory is available.

Remarks

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 type monitoring has been correctly initiated, not when media type monitoring has terminated. Media monitoring for a given media type remains in effect until it is explicitly disabled by calling TSPI_lineMonitorMedia with a dwMediaModes parameter with the media type set to zero, or until the call transitions to idle.

TSPI_lineMonitorMedia is primarily an event reporting mechanism. The media type of a call, as indicated in the LINECALLINFO structure, is not affected by the service provider's detection of the media type. Only TAPI or a client application can change a call's indicated media type using TSPI_lineSetMediaMode. The actual use of a particular media type 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 types specified by the TSPI_lineSetDefaultMediaDetection function. Shortly after a new call is established, TAPI typically calls TSPI_lineMonitorMedia to reduce the set of media types detected and reported for this call to the union of all media types 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 types 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 type 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 type 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 type 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 type 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 type, TAPI guarantees that there are no reserved bits set. The service provider must perform any further validity checks on the media types, such as checking whether any media types are indeed supported by the service provider.

Requirements

Header

tspi.h

Library

CellTSP.dll

See Also

Reference

TSPI Line Device Functions
TSPI_lineConditionalMediaDetection
TSPI_lineGetDevCaps
TSPI_lineSetDefaultMediaDetection
TSPI_lineSetMediaMode