TSPI_lineSetMediaMode

The TSPI_lineSetMediaMode function changes the call's media as stored in the call's LINECALLINFO structure.

LONG TSPI_lineSetMediaMode(
  HDRVCALL hdCall,  
  DWORD dwMediaMode 
);
 

Parameters

hdCall

The handle to the call undergoing a change in media mode. The call state of hdCall can be any state.

dwMediaMode

The new media mode(s) for the call. As long as the LINEMEDIAMODE_UNKNOWN media mode flag is set, multiple other media mode flags can be set as well. This is used to identify a call's media mode as not fully determined, but narrowed down to one of just a small set of specified media modes. If the LINEMEDIAMODE_UNKNOWN flag is not set, only a single media mode can be specified. LINEMEDIAMODE_ constant values are:

LINEMEDIAMODE_UNKNOWN

The anticipated media type is not fully classified.

LINEMEDIAMODE_INTERACTIVEVOICE

The anticipated media type is interactive voice media mode, namely live conversations.

LINEMEDIAMODE_AUTOMATEDVOICE

TAPI can handle calls in which there is voice data, but the voice is handled by an automated application. Most service providers cannot distinguish between automated and interactive voice. In such a case any request for voice or detection of voice is treated as interactive voice.

LINEMEDIAMODE_DATAMODEM

The anticipated media type is data modem media mode.

LINEMEDIAMODE_G3FAX

The anticipated media type is group 3 fax media mode.

LINEMEDIAMODE_TDD

The anticipated media type is TDD (Telephony Devices for the Deaf) media mode.

LINEMEDIAMODE_G4FAX

The anticipated media type is group 4 fax media mode.

LINEMEDIAMODE_DIGITALDATA

The anticipated media type is digital data calls.

LINEMEDIAMODE_TELETEX

The anticipated media type is teletex media mode.

LINEMEDIAMODE_VIDEOTEX

The anticipated media type is videotex media mode.

LINEMEDIAMODE_TELEX

The anticipated media type is telex media mode.

LINEMEDIAMODE_MIXED

The anticipated media type is ISDN mixed media mode.

LINEMEDIAMODE_ADSI

The anticipated media type is ADSI (Analog Display Services Interface) media mode.

LINEMEDIAMODE_VOICEVIEW

The media mode of the call is VoiceView.

Return Values

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_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Remarks

Other than changing the call's media as stored in the call's LINECALLINFO structure, this procedure is simply advisory in the sense that it indicates an expected media change that is about to occur, rather than forcing a specific change to the call. Typical usage is to set a call's media mode to a specific known media mode, or to exclude possible media modes as long as the call's media mode is not fully known (the UNKNOWN media mode flag is set).

TAPI makes the following guarantees regarding the passed media mode: (1) there is at least one bit set, (2) there are no reserved bits set, and (3) if more than one bit is set, "Unknown" is also 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.

See Also

LINECALLINFO, LINEMEDIAMODE_ Constants, TSPI_lineGetCallInfo