Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function rings the specified open phone device using the specified ring mode and volume.

Syntax 

LONG TSPIAPI TSPI_phoneSetRing(
  DRV_REQUESTID 
dwRequestID,  
  HDRVPHONE 
hdPhone, 
  DWORD 
dwRingMode, 
  DWORD 
dwVolume 
);

Parameters

dwRequestID

Identifier of the asynchronous request.

hdPhone

andle to the phone to be rung.

dwRingMode

Ringing pattern with which to ring the phone. This parameter must be within the range from zero through the value of the dwNumRingModesmember in the PHONECAPSstructure. If dwNumRingModesis zero, the ring mode of the phone cannot be controlled; if dwNumRingModesis 1, a value of zero for dwRingModeindicates that the phone should not be rung (silence), and other values from 1 through dwNumRingModesare valid ring modes for the phone device.

dwVolume

Volume level with which the phone is to be rung. This is a number in the range from 0x00000000 (silence) through 0x0000FFFF (maximum volume). The actual granularity and quantization of volume settings in this range are service-provider specific. A value for dwVolumethat is out of range is clamped by TAPI to the nearest value in range.

Return Value

Returns dwRequestIDor an error number if an error occurs. The lResultactual parameter of the corresponding ASYNC_COMPLETIONis zero if the function succeeds or it is an error number if an error occurs. The following table shows the return values for this method.

Value Description

PHONEERR_INVALPHONEHANDLE

The handle to the phone is invalid.

PHONEERR_RESOURCEUNAVAIL

The resource is unavailable.

PHONEERR_INVALPHONESTATE

The phone state is invalid.

PHONEERR_OPERATIONFAILED

The operation failed.

PHONEERR_INVALRINGMODE

The ring mode is invalid.

PHONEERR_OPERATIONUNAVAIL

The operation is unavailable.

PHONEERR_NOMEM

Not enough memory is available.

Remarks

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

Requirements

Header tapicomn.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also