RingControl Class Reference
[QtTelephonyModule]

Detailed Description

The RingControl class controls the system ring for incoming calls and messages.

The RingControl provides a Qt Extended Server Task. Qt Extended Server Tasks are documented in full in the QtopiaServerApplication class documentation.

The RingControl class plays ring tones and enables vibration on incoming calls and messages. The specifics of the tones and vibrations generated are controlled by the active QPhoneProfile.

The RingControl class only supports a single simultaneous ring tone. If both an incoming call and an incoming message are received together, the call ring takes priority and the message ring is discarded. Likewise, if a message ring is in progress when an incoming call is received, the message ring is stopped and the phone ring commenced.

The RingControl class utilizes video ringtones if the VideoRingtone task is deployed. The communications between the two classes is based on messages on the QPE/VideoRingtone QCop channel. For more details see VideoRingtone.

This class is part of the Qt Extended server and cannot be used by other Qt Extended applications.

See also VideoRingtone.

Member Type Documentation

enum RingControl::RingType

The RingType enumeration represents the current in-progress ring type.

Member Function Documentation

bool RingControl::callRingEnabled () const

Returns true if call ring control is enabled, otherwise false. If enabled, the RingControl class will play ring tones and vibrate subject to the rules for call rings outlined above. If disabled, the RingControl class will not perform any ring control for calls.

By default, call ring control is enabled.

See also setCallRingEnabled().

bool RingControl::messageRingEnabled () const

Returns true if message ring control is enabled, otherwise false. If enabled, the RingControl class will play ring tones and vibrate subject to the rules for message rings outlined above. If disabled, the RingControl class will not perform any ring control for messages.

By default, message ring control is enabled.

See also setMessageRingEnabled().

int RingControl::msgRingTime () const

Return the message ring time, in milliseconds.

See also setMsgRingTime().

void RingControl::muteRing ()   [slot]

Stops audible ringing, but vibration will continue if it was already in progress. To stop both audible ringing and vibration, use stopRing().

void RingControl::playSound ( const QString & soundFile )

Play the soundFile. The sound file will be played at the current ring volume and terminated if another ring even occurs. Sounds may only be played through this API if the ring type is NotRinging.

int RingControl::ringTime () const

Return the time, in milliseconds, the current ring has been in progress. If there is no in-progress ring, returns 0.

RingType RingControl::ringType () const

Returns the in-progress ring tpe, or NotRinging if there is no in-progress ring.

void RingControl::ringTypeChanged ( RingControl::RingType type )   [signal]

Emitted whenever the current ring type changes. type will be the new value.

void RingControl::setCallRingEnabled ( bool enabled )

Sets whether call ring control is enabled.

See also callRingEnabled().

void RingControl::setMessageRingEnabled ( bool enabled )

Sets whether message ring control is enabled.

See also messageRingEnabled().

void RingControl::setMsgRingTime ( int time )

Set the message ring time to time milliseconds.

See also msgRingTime().

void RingControl::setVibrateDuration ( int duration )

Sets the duration in milliseconds of the vibration period. When vibration is active, the vibration will toggle on for duration then off for duration milliseconds.

See also vibrateDuration().

void RingControl::setVolume ( int volume )

Sets the volume at which the rings will be played. volume may be from 0 (silent) to 5 (loudest).

The ring volume only effects non-ascending rings. Ascending rings always commence at the lowest volume and slowly increase to the maximum volume. Generally setVolume() should not be called directly as it will be overridden by any change to the active QPhoneProfile.

void RingControl::stopMessageAlert ()   [slot]

Stop the message alert sound. Does nothing if no message alert is in progress.

void RingControl::stopRing ()

Stop all ringing and vibration. Does nothing if no ring is in progress.

int RingControl::vibrateDuration () const

Return the duration of the vibration period in milliseconds.

See also setVibrateDuration().