2.2.4.1.3.72 SetMediaControl

The SetMediaControl packet is transmitted from a TAPI client to a TAPI server in a remote procedure call. Sending this packet MUST enable or disable control actions on the media stream that is associated with the specified line, address, or call.

Media control actions can be triggered by the detection of specified digits, media types, custom tones, and call states. The new specified media controls replace all the ones that were in effect for this line, address, or call prior to this request.


0


1


2


3


4


5


6


7


8


9

1
0


1


2


3


4


5


6


7


8


9

2
0


1


2


3


4


5


6


7


8


9

3
0


1

Req_Func

Reserved1

hLine

dwAddressID

hCall

dwSelect

lpDigitList

dwDigitNumEntries

lpMediaList

dwMediaNumEntries

lpToneList

dwToneNumEntries

lpCallStateList

dwCallStateNumEntries

Reserved2

VarData (variable)

...

Req_Func (4 bytes): An unsigned 32-bit integer. The identifier of the function that will be invoked on the remote server. This value MUST be set to 79.

Return Values

On completion of ClientRequest, this field MUST contain the result of the encapsulated telephony request. A value of 0 indicates success, and a LINEERR_Constants value indicates failure. The remote server MUST complete this call synchronously.

Returns zero if the function succeeds or an error number if an error occurs. Common return values are as follows:

Name

Value

LINEERR_INVALADDRESSID

0x80000011

LINEERR_INVALPOINTER

0x80000035

LINEERR_INVALCALLHANDLE

0x80000018

LINEERR_INVALTONELIST

0x8000003D

LINEERR_INVALCALLSELECT

0x8000001B

LINEERR_NOMEM

0x80000044

LINEERR_INVALCALLSTATELIST

0x8000001D

LINEERR_OPERATIONUNAVAIL

0x80000049

LINEERR_INVALDIGITLIST

0x80000026

LINEERR_OPERATIONFAILED

0x80000048

LINEERR_INVALLINEHANDLE

0x8000002B

LINEERR_RESOURCEUNAVAIL

0x8000004B

LINEERR_INVALMEDIALIST

0x8000002E

Reserved1 (4 bytes): An unsigned 32-bit integer. MUST be set to zero when sent and MUST be ignored on receipt.

hLine (4 bytes): An HLINE. The handle to a line. This field MUST have been obtained by sending the Open packet.

dwAddressID (4 bytes): An unsigned 32-bit integer. An address on the particular open line device. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades. TAPI does not validate this parameter when this function is called. A valid value of dwAddressID is in the range 0 to dwNumAddresses –1. The client obtains dwNumAddresses from the LINEDEVCAPS obtained by sending a GetDevCaps packet to the remote server.

hCall (4 bytes): An HCALL. The handle to a call. One way of obtaining a valid hCall is by sending the MakeCall packet. Also a valid hCall can be obtained from LINE_CALLSTATE packet sent by the remote server. The call state of hCall can be any state.

dwSelect (4 bytes): An unsigned 32-bit integer. Specifies whether the requested media control is associated with a single call; is the default for all calls on an address; or is the default for all calls on a line. This parameter MUST use the LINECALLSELECT_Constants.

lpDigitList (4 bytes): An unsigned 32-bit integer. The offset, in bytes, of a LINEMEDIACONTROLDIGIT packet in the VarData field that contains the digits to trigger media control actions.

dwDigitNumEntries (4 bytes): An unsigned 32-bit integer. This value is equal to the number of entries in the lpDigitList multiplied by the size of LINEMEDIACONTROLDIGIT. TAPI does not validate this parameter when this function is called.

lpMediaList (4 bytes): An unsigned 32-bit integer. The offset, in bytes, of a LINEMEDIACONTROLMEDIA packet in the VarData field that contains a media type to monitor, media-type specific information such as duration, and a media control field.

dwMediaNumEntries (4 bytes): An unsigned 32-bit integer. This value is equal to the number of entries in the lpMediaList multiplied by the size of LINEMEDIACONTROLMEDIA. TAPI does not validate this parameter when this function is called.

lpToneList (4 bytes): An unsigned 32-bit integer. The offset, in bytes, of a LINEMEDIACONTROLTONE packet in the VarData field that contains a description of a tone to monitor, the duration of the tone, and a media-control field.

dwToneNumEntries (4 bytes): An unsigned 32-bit integer. This value is equal to the number of entries in the lpToneList multiplied by the size of LINEMEDIACONTROLTONE. TAPI does not validate this parameter when this function is called.

lpCallStateList (4 bytes): An unsigned 32-bit integer. The offset, in bytes, of a LINEMEDIACONTROLCALLSTATE packet in the VarData field that contains a call state and a media control action.

dwCallStateNumEntries (4 bytes): An unsigned 32-bit integer. This value is equal to the number of entries in the lpCallStateList multiplied by the size of LINEMEDIACONTROLCALLSTATE. TAPI does not validate this parameter when this function is called.

Reserved2 (4 bytes): An unsigned 32-bit integer. This field is used for padding and MUST be ignored on receipt. It can be any value.

VarData (variable): MUST Contain an array of LINEMEDIACONTROLDIGIT packets that is indicated in the lpDigitList field; an array of LINEMEDIACONTROLMEDIA packets that is indicated in the lpMediaList field; an array of LINEMEDIACONTROLTONE packets that is indicated in the lpToneList field; and an array of LINEMEDIACONTROLCALLSTATE packets that is indicated in the lpCallStateList field.

The contents of this field are DWORD-aligned.