net.rim.device.api.system
Class Alert

java.lang.Object
  net.rim.device.api.system.Alert

public final class Alert
extends Object

Provides access to the device's audio system.

Applications can use the device's audio system to notify the device's operator of interesting events (for example, new messages or phone calls).

This class provides a number of alert type query methods you can use to determine whether the host device supports a particular kind of alert (for example Alert.isAudioSupported()). If the device does support a particular kind of alert, then you can use the associated start and stop control methods to use that type of alert (for example, Alert.startAudio(short[], int) and Alert.stopAudio()).

To start an audio alert, you must pass an array containing the coding for a tune, and the volume level as a percentage of the maximum.

The following code sample illustrates how to play a tune:

 // The TUNE (bar 1 and 2 of Islamey by Balakirev)
 private static final short BFlat = 466;   //466.16
 private static final short AFlat = 415;     //415.30
 private static final short A = 440; //440.00
 private static final short GFlat = 370;     //369.99
 private static final short DFlat = 554;     //554.37
 private static final short C = 523; //523.25
 private static final short F = 349; //349.32
 
 private static final short TEMPO = 125;
 
 // Duration of a 16th note, arbitrary, in ms.
 private static final short d16 = 1 * TEMPO;
 
 // Duration of an eighth note, arbitrary, in ms.
 private static final short d8 = d16 << 1;
 
 // 10 ms pause.
 private static final short dpause = 10;
 
 // Zero frequency pause.
 private static final short pause = 0;
 
 private static final short[] TUNE = new short[]
 {
     BFlat, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     A, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     GFlat, d16, pause, dpause,
     GFlat, d16, pause, dpause,
     A, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     DFlat, d16, pause, dpause,
     C, d16, pause, dpause, //bar 1
     AFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     F, d16, pause, dpause,
     GFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     F, d8 + d16 //bar 2
 };
 
 // % volume
 private static final int VOLUME = 80;
 
 if ( Alert.isAudioSupported())
 {
     Alert.startAudio(TUNE, VOLUME);
 }
 

On completion, AlertListener.audioDone() is invoked on the event thread.

To start a MIDI alert, you must pass an array containing the coding for a tune, and a flag that determines whether the tune can be interrupted by keyboard or trackwheel activity. On completion, AlertListener2.midiDone() will be invoked on the event thread.

See Also:

AlertListener

Since:

BlackBerry API 3.6.0

Field Summary
static int	ALERT_ERROR_BAD_DATA Invalid data was provided
static int	ALERT_ERROR_BAD_STATE Playback is already in progress
static int	ALERT_ERROR_FILESYSTEM_FULL Filesystem is full
static int	ALERT_ERROR_UNKNOWN Unknown error
static int	ALERT_OK Playback has begun

Method Summary
static void	enablePWMSync(boolean enable) Deprecated. This is no longer supported.
static int	getVolume() Retrieves the master volume.
static boolean	isADPCMSupported() Deprecated. ADPCM is no longer supported.
static boolean	isAudioSupported() Determines if this device provides support for playing audio alerts via Alert.startAudio(short[], int).
static boolean	isBuzzerSupported() Determines if this device provides buzzer support.
static boolean	isMIDISupported() Determines if this device provides MIDI support.
static boolean	isVibrateSupported() Determines if this device provides vibration support.
static void	mute(boolean newMuteState) Toggles the device between mute (volume 0) and loud state, and persists the current volume level.
static void	playBuzzer(short[] tune, int volume) Deprecated. Replaced by Alert.startBuzzer(short[],int,boolean)
static void	setADPCMVolume(int volume) Deprecated. ADPCM is no longer supported.
static void	setBuzzerVolume(int volume) Sets the volume for the buzzer.
static void	setVolume(int volume) Sets the master volume.
static int	startADPCM(byte[] tune, boolean interruptable) Deprecated. ADPCM is no longer supported.
static void	startAudio(short[] tune, int volume) Starts an audio alert.
static void	startBuzzer(short[] tune, int volume) Starts a buzzer alert.
static void	startBuzzer(short[] tune, int volume, boolean interruptable) Starts a buzzer alert.
static int	startMIDI(byte[] tune, boolean interruptable) Starts a MIDI alert.
static void	startVibrate(int duration) Starts a vibrate alert.
static void	stopADPCM() Deprecated. ADPCM is no longer supported.
static void	stopAudio() Cancels an audio alert in progress.
static void	stopBuzzer() Cancels a buzzer alert in progress.
static void	stopMIDI() Cancels a MIDI alert in progress.
static void	stopVibrate() Cancels a vibrate alert in progress.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALERT_OK

public static final int ALERT_OK

Playback has begun

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

ALERT_ERROR_UNKNOWN

public static final int ALERT_ERROR_UNKNOWN

Unknown error

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

ALERT_ERROR_BAD_DATA

public static final int ALERT_ERROR_BAD_DATA

Invalid data was provided

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

ALERT_ERROR_BAD_STATE

public static final int ALERT_ERROR_BAD_STATE

Playback is already in progress

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.2

ALERT_ERROR_FILESYSTEM_FULL

public static final int ALERT_ERROR_FILESYSTEM_FULL

Filesystem is full

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.2

Method Detail

isAudioSupported

public static boolean isAudioSupported()

Determines if this device provides support for playing audio alerts via Alert.startAudio(short[], int).

Returns:

True if this device provides audio support; false otherwise.

Since:

BlackBerry API 4.0.0

startAudio

public static void startAudio(short[] tune,
                              int volume)

Starts an audio alert.

The specified tune is played using the currently selected audio channel at the specified volume. (Typically using the headset if the device is so equipped.)

When the alert is complete, AlertListener.audioDone(int) is invoked on the event thread.

Notes:

Tune data arrays consist of frequency, duration pairs (both a short). Consecutive notes of the same frequency appear to bleed together. To create staccato-type effects, insert brief 0 frequency pauses into the note array. Devices vary in their frequency response. The BlackBerry 5800 Series, BlackBerry 6200 Series, and BlackBerry 6700 Series all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data. The elements of the array are the note frequency in hertz and the duration of the note in milliseconds.

volume - Percentage of capable volume level, from 0 to 100.

Throws:

IllegalArgumentException - if the specified volume is outside the range 0 to 100.

See Also:

AlertListener.audioDone(int)

Since:

BlackBerry API 3.6.0

stopAudio

public static void stopAudio()

Cancels an audio alert in progress.

Since:

BlackBerry API 3.6.0

isBuzzerSupported

public static boolean isBuzzerSupported()

Determines if this device provides buzzer support.

Returns:

True if this device provides buzzer support; false otherwise.

Since:

BlackBerry API 4.0.0

startBuzzer

public static void startBuzzer(short[] tune,
                               int volume)

Starts a buzzer alert.

The specified tune is played using the piezoelectric buzzer at the specified volume. When the alert is complete, AlertListener.buzzerDone(int) is invoked on the event thread. The tune is interrupted by any keypad or trackwheel activity.

If the device does not support the buzzer, then invoking this method has no effect.

Notes:

Tune data arrays consist of frequency, duration pairs (both a short). Consecutive notes of the same frequency appear to bleed together. To create staccato-type effects, insert brief 0 frequency pauses into the note array. Devices vary in their frequency response. The BlackBerry 5800 Series, BlackBerry 6200 Series, and BlackBerry 6700 Series all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data. The array elements are the note frequency in hertz and the duration of the note in milliseconds.

volume - Percentage of capable volume level, from 0 to 100.

Throws:

IllegalArgumentException - if the specified volume is outside the range 0 to 100.

See Also:

AlertListener.buzzerDone(int)

Since:

BlackBerry API 3.6.0

startBuzzer

public static void startBuzzer(short[] tune,
                               int volume,
                               boolean interruptable)

Starts a buzzer alert.

The specified tune is played using the piezoelectric buzzer at the specified volume. When the alert is complete, AlertListener.buzzerDone(int) is invoked on the event thread. The tune is interrupted by any keypad or trackwheel activity.

If the device does not support the buzzer, then invoking this method has no effect.

Notes:

Tune data arrays consist of frequency, duration pairs (both a short). Consecutive notes of the same frequency appear to bleed together. To create staccato-type effects, insert brief 0 frequency pauses into the note array. Devices vary in their frequency response. The BlackBerry 5800 Series, BlackBerry 6200 Series, and BlackBerry 6700 Series all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data. The array elements are the note frequency in hertz and the duration of the note in milliseconds.

volume - Percentage of capable volume level, from 0 to 100.

interruptable - If true, the tune might be interrupted by keypad or trackwheel activity; otherwise, the tune will not be interrupted.

Throws:

IllegalArgumentException - if the specified volume is outside the range 0 to 100.

See Also:

AlertListener.buzzerDone(int)

Since:

BlackBerry API 4.0.0

playBuzzer

public static void playBuzzer(short[] tune,
                              int volume)

Deprecated. Replaced by Alert.startBuzzer(short[],int,boolean)

Plays a buzzer alert.

The specified tune is played using the piezoelectric buzzer at the specified volume. When the alert is complete, AlertListener.buzzerDone(int) is invoked on the event thread. The tune is not interrupted by keypad or trackwheel activity.

If the device does not support the buzzer, then invoking this method has no effect.

Notes:

Tune data arrays consist of frequency, duration pairs (both a short). Consecutive notes of the same frequency appear to bleed together. To create staccato-type effects, insert brief 0 frequency pauses into the note array. Devices vary in their frequency response. The BlackBerry 5800 Series, BlackBerry 6200 Series, and BlackBerry 6700 Series all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data (elements are the note frequency in hertz and the duration of the note in milliseconds).

volume - Percentage of capable volume level, from 0 to 100.

Throws:

IllegalArgumentException - if the specified volume is outside the range 0 to 100.

See Also:

AlertListener.buzzerDone(int)

Since:

BlackBerry API 3.7.0

stopBuzzer

public static void stopBuzzer()

Cancels a buzzer alert in progress.

If the device does not support the buzzer, then invoking this method has no effect.

Since:

BlackBerry API 3.6.0

isVibrateSupported

public static boolean isVibrateSupported()

Determines if this device provides vibration support.

Returns:

True if this device provides vibration support; false otherwise.

Since:

BlackBerry API 4.0.0

startVibrate

public static void startVibrate(int duration)

Starts a vibrate alert.

The device vibrates for the specified amount of time. When the alert is complete, AlertListener.vibrateDone(int) is invoked on the event thread.

Parameters:

duration - Vibration time in milliseconds, from 0 to 25500.

Throws:

IllegalArgumentException - if the specified duration is outside the range 0 to 25500.

See Also:

AlertListener.vibrateDone(int)

Since:

BlackBerry API 3.6.0

stopVibrate

public static void stopVibrate()

Cancels a vibrate alert in progress.

Since:

BlackBerry API 3.6.0

isMIDISupported

public static boolean isMIDISupported()

Determines if this device provides MIDI support.

Returns:

True if this device provides MIDI support; false otherwise.

Since:

BlackBerry API 4.0.0

startMIDI

public static int startMIDI(byte[] tune,
                            boolean interruptable)

Starts a MIDI alert.

The specified tune is played using the polyphonic device. When the alert is complete, AlertListener2.midiDone(int) is invoked on the event thread.

If the device does not support a MIDI alert, invoking this method throws an UnsupportedOperationException.

Parameters:

tune - Tune to play.

interruptable - If true, the tune might be interrupted by keypad or trackwheel activity; otherwise, the tune will not be interrupted.

Returns:

One of the ALERT_ values.

Throws:

UnsupportedOperationException - if the device does not support MIDI.

See Also:

AlertListener2.midiDone(int)

Since:

BlackBerry API 4.0.0

stopMIDI

public static void stopMIDI()

Cancels a MIDI alert in progress.

If the device does not support a MIDI alert, invoking this method throws an UnsupportedOperationException.

Throws:

UnsupportedOperationException - if the device does not support MIDI.

Since:

BlackBerry API 4.0.0

isADPCMSupported

public static boolean isADPCMSupported()

Deprecated. ADPCM is no longer supported.

Determines if this device provides ADPCM support.

Returns:

True if this device provides ADPCM support; false otherwise.

Since:

BlackBerry API 4.0.0

startADPCM

public static int startADPCM(byte[] tune,
                             boolean interruptable)

Deprecated. ADPCM is no longer supported.

Starts an ADPCM alert.

The specified tune is played using the polyphonic device. When the alert is complete, AlertListener2#adpcmDone is invoked on the event thread.

If the device does not support an ADPCM alert, invoking this method throws an UnsupportedOperationException.

Parameters:

tune - Tune to play.

interruptable - If true, the tune might be interrupted by keypad or trackwheel activity; otherwise, the tune will not be interrupted.

Returns:

One of the ALERT_* values.

Throws:

UnsupportedOperationException - if the device does not support ADPCM.

Since:

BlackBerry API 4.0.0

stopADPCM

public static void stopADPCM()

Deprecated. ADPCM is no longer supported.

Cancels an ADPCM alert in progress.

If the device does not support an ADPCM alert, invoking this method throws an UnsupportedOperationException.

Throws:

UnsupportedOperationException - if the device does not support ADPCM.

Since:

BlackBerry API 4.0.0

enablePWMSync

public static void enablePWMSync(boolean enable)

Deprecated. This is no longer supported.

Enables or disables PWM sync.

Throws:

UnsupportedOperationException - if the device does not support ADPCM.

Since:

BlackBerry API 4.0.0

setADPCMVolume

public static void setADPCMVolume(int volume)

Deprecated. ADPCM is no longer supported.

Sets the volume for ADPCM.

Note: This value is multiplied with the master volume.

If the device does not support an ADPCM alert, invoking this method throws an UnsupportedOperationException.

Parameters:

volume - Percentage of total capable volume, from 0 to 100.

Throws:

UnsupportedOperationException - if the device does not support ADPCM.

IllegalArgumentException - if the specified volume is outside the range 0 to 100.

Since:

BlackBerry API 4.0.0

setBuzzerVolume

public static void setBuzzerVolume(int volume)

Sets the volume for the buzzer.

If the device does not support the buzzer, then invoking this method has no effect.

Note: This value is multiplied with the master volume.

Parameters:

volume - Percentage of total capable volume, from 0 to 100.

Throws:

IllegalArgumentException - if the specified volume is outside the range 0 to 100.

Since:

BlackBerry API 4.0.0

setVolume

public static void setVolume(int volume)

Sets the master volume.

Parameters:

volume - Percentage of total capable volume, from 0 to 100.

Throws:

IllegalArgumentException - if the specified volume is outside the range 0 to 100.

Since:

BlackBerry API 4.0.0

getVolume

public static int getVolume()

Retrieves the master volume.

Returns:

Percentage of total capable volume, from 0 to 100.

Since:

BlackBerry API 4.0.2

mute

public static void mute(boolean newMuteState)

Toggles the device between mute (volume 0) and loud state, and persists the current volume level. Any call to setVolume() overrides the current mute state. Any later call to mute(false) returns the volume to the cached value.

If newMuteState is equal to the current mute state, this method does nothing.

Parameters:

newMuteState - If true, mutes the device; otherwise, returns the volume to the value previous to muting.

Since:

BlackBerry API 4.0.2