2.2.4.1.6.20 SetRing

The SetRing packet is transmitted from a TAPI client to a TAPI server in a remote procedure call. Sending this packet MUST ring the specified open phone device by using the specified ring mode and volume.

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

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_INVALRINGMODE	0x00000017
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): An unsigned 32-bit integer. The identifier of the asynchronous request.

hPhone (4 bytes): An HPHONE. The handle to the phone to be rung. This field MUST have been obtained by sending the Open packet.

dwRingMode (4 bytes): An unsigned 32-bit integer. The ringing pattern with which to ring the phone. This parameter MUST be within the range from zero through the value of the dwNumRingModes member in the PHONECAPS packet. If dwNumRingModes is zero, the ring mode of the phone cannot be controlled; if dwNumRingModes is 1, a value of 0 for dwRingMode indicates that the phone SHOULD NOT be rung (silence); and other values from 1 through dwNumRingModes are valid ring modes for the phone device.

dwVolume (4 bytes): An unsigned 32-bit integer. The volume level with which the phone is to be rung. This MUST be in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are specific to the service provider. A value for dwVolume that is out of range is clamped by TAPI to the nearest value in range.

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.