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.
|
|
|
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
|
|
3 |
|
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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.