2.2.4.1.6.17 SetGain

The SetGain packet is transmitted from a TAPI client to a TAPI server in a remote procedure call. Sending this packet MUST set the gain of the microphone of the specified hookswitch device to the specified gain level.


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

dwRequestID

hPhone

dwHookSwitchDev

dwGain

Reserved2

Reserved3

Reserved4

Reserved5

Reserved6

Reserved7

Reserved8

Reserved9

Reserved10

Req_Func (4 bytes): The identifier of the function that will be invoked on the remote server. This value MUST be set to 113.

Return Values

On completion of ClientRequest, this field MUST contain the result of the encapsulated telephony request. A nonzero request ID value indicates that the request is in progress and will complete asynchronously, and a PHONEERR_Constants value indicates synchronous failure.

Returns a positive request identifier if the function will be completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding PHONE_REPLY packet is 0 if the function succeeds, or is a negative error number if an error occurs. If the client specified a nonzero value in the dwRequestID field of the packet, the same value MUST be used for the returned positive request identifier. The following table lists common return values.

Name

Value

PHONEERR_INVALPHONEHANDLE

0x00000013

PHONEERR_RESOURCEUNAVAIL

0x0000001F

PHONEERR_INVALPHONESTATE

0x00000014

PHONEERR_OPERATIONFAILED

0x0000001C

PHONEERR_INVALHOOKSWITCHDEV

0x0000000F

PHONEERR_OPERATIONUNAVAIL

0x0000001D

PHONEERR_NOMEM

0x0000001A

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

dwRequestID (4 bytes): The identifier of the asynchronous request.

hPhone (4 bytes): An HPHONE. The handle to the phone that contains the hookswitch device whose gain is to be set. This field MUST have been obtained by sending the Open packet.

dwHookSwitchDev (4 bytes): The hookswitch device whose microphone gain is to be set. This parameter MUST use one of the PHONEHOOKSWITCHDEV_Constants.

dwGain (4 bytes): A DWORD-sized location that contains the desired new gain setting of the device. This MUST be in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of gain settings in this range are specific to the service provider. A value for dwGain that is out of range is clamped by TAPI to the nearest in-range value.

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.

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

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

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

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

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

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

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

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