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, arrived messages, phone calls, and so forth).

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 isAudioSupported(). If it does, then you can use the associated "start" and "stop" control methods to use that type of alert (for example, startAudio(short[], int) and stopAudio().

If the device does not support a particular kind of alert, then invoking the control methods has no effect.

Since:
JDE 3.6.0
See Also:
AlertListener

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)
          Enabled or disables PWM sync.
static int getVolume()
          gets the master volume.
static boolean isADPCMSupported()
          Determines if this device provides ADPCM support.
static boolean isAudioSupported()
          Determines if this device provides audio support.
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 toggle)
          toggles the device between mute (volume 0) and loud state and persists the current volume level any call to setVolume will override mute state any later call to mute(false) will return the volume to the cached value
static void playBuzzer(short[] tune, int volume)
          Deprecated. Replaced by startBuzzer(short[],int,boolean)
static void setADPCMVolume(int volume)
          Sets the volume for ADPCM.
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)
          Starts an ADPCM alert.
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()
          Cancels an ADPCM alert in progress.
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
Since:
JDE 4.0.0

ALERT_ERROR_UNKNOWN

public static final int ALERT_ERROR_UNKNOWN
Unknown error
Since:
JDE 4.0.0

ALERT_ERROR_BAD_DATA

public static final int ALERT_ERROR_BAD_DATA
Invalid data was provided
Since:
JDE 4.0.0

ALERT_ERROR_BAD_STATE

public static final int ALERT_ERROR_BAD_STATE
Playback is already in progress
Since:
JDE 4.0.2

ALERT_ERROR_FILESYSTEM_FULL

public static final int ALERT_ERROR_FILESYSTEM_FULL
Filesystem is full
Since:
JDE 4.0.2
Method Detail

isAudioSupported

public static boolean isAudioSupported()
Determines if this device provides audio support.
Returns:
True if this device provides audio support; otherwise, false.
Since:
JDE 4.0.0

startAudio

public static void startAudio(short[] tune,
                              int volume)
Starts an audio alert.

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

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

Note:

  • Tune data arrays consist of frequency, duration pairs (both a short).
  • Consecutive notes of the same frequency will appear to bleed together. Therefore, if staccato type effects are required, insert brief 0 frequency pauses into the note array.
  • Devices vary in their frequency response. The 5800, 6200 and 6700 series devices 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 1 to 100.
Since:
JDE 4.0.2
See Also:
AlertListener.audioDone(int)

stopAudio

public static void stopAudio()
Cancels an audio alert in progress.
Since:
JDE 3.6.0

isBuzzerSupported

public static boolean isBuzzerSupported()
Determines if this device provides buzzer support.
Returns:
True if this device provides buzzer support; otherwise, false.
Since:
JDE 4.0.0

startBuzzer

public static void startBuzzer(short[] tune,
                               int volume)
Starts a buzzer alert.

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

Note:

  • Tune data arrays consist of frequency, duration pairs (both a short).
  • Consecutive notes of the same frequency will appear to bleed together. Therefore, if staccato type effects are required, insert brief 0 frequency pauses into the note array.
  • Devices vary in their frequency response. The 5800, 6200 and 6700 series devices 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 1 to 100.
Since:
JDE 4.0.2
See Also:
AlertListener.buzzerDone(int)

startBuzzer

public static void startBuzzer(short[] tune,
                               int volume,
                               boolean interruptable)
Starts a buzzer alert.

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

Note:

  • Tune data arrays consist of frequency, duration pairs (both a short).
  • Consecutive notes of the same frequency will appear to bleed together. Therefore, if staccato type effects are required, insert brief 0 frequency pauses into the note array.
  • Devices vary in their frequency response. The 5800, 6200 and 6700 series devices 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 1 to 100.
interruptable - If true, the tune may be interrupted by keypad or trackwheel activity; otherwise, the tune may not be interrupted.
Since:
JDE 4.0.2
See Also:
AlertListener.buzzerDone(int)

playBuzzer

public static void playBuzzer(short[] tune,
                              int volume)
Deprecated. Replaced by startBuzzer(short[],int,boolean)

Plays a buzzer alert.

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

Note:

  • Tune data arrays consist of frequency, duration pairs (both a short).
  • Consecutive notes of the same frequency will appear to bleed together. Therefore, if staccato type effects are required, insert brief 0 frequency pauses into the note array.
  • Devices vary in their frequency response. The 5800, 6200 and 6700 series devices 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 1 to 100.
Since:
JDE 4.0.2
See Also:
AlertListener.buzzerDone(int)

stopBuzzer

public static void stopBuzzer()
Cancels a buzzer alert in progress.
Since:
JDE 3.6.0

isVibrateSupported

public static boolean isVibrateSupported()
Determines if this device provides vibration support.
Returns:
True if this device provides vibration support; otherwise, false.
Since:
JDE 4.0.0

startVibrate

public static void startVibrate(int duration)
Starts a vibrate alert.

The device will vibrate for the specified amount of time. When the alert is completed, the AlertListener.buzzerDone(int) method is invoked on the event thread.

Parameters:
duration - Vibration time in milliseconds, from 0 to 25500.
Since:
JDE 4.0.2
See Also:
AlertListener.vibrateDone(int)

stopVibrate

public static void stopVibrate()
Cancels a vibrate alert in progress.
Since:
JDE 3.6.0

isMIDISupported

public static boolean isMIDISupported()
Determines if this device provides MIDI support.
Returns:
True if this device provides MIDI support; otherwise, false.
Since:
JDE 4.0.0

startMIDI

public static int startMIDI(byte[] tune,
                            boolean interruptable)
Starts a MIDI alert.

The specified tune is played via the polyphonic device at the specified volume. When the alert is completed, the AlertListener2.midiDone(int) method is invoked on the event thread.

Parameters:
tune - Tune to play.
interruptable - If true, the tune may be interrupted by keypad or trackwheel activity; otherwise, the tune may note be interrupted.
Returns:
One of the ALERT_ values.
Since:
JDE 4.0.2
See Also:
AlertListener2.midiDone(int)

stopMIDI

public static void stopMIDI()
Cancels a MIDI alert in progress.
Since:
JDE 4.0.0

isADPCMSupported

public static boolean isADPCMSupported()
Determines if this device provides ADPCM support.
Returns:
True if this device provides ADPCM support; otherwise, false.
Since:
JDE 4.0.0

startADPCM

public static int startADPCM(byte[] tune,
                             boolean interruptable)
Starts an ADPCM alert.

The specified tune is played via the polyphonic device at the specified volume. When the alert is completed, the AlertListener2.adpcmDone(int) method is invoked on the event thread.

Parameters:
tune - Tune to play.
interruptable - If true, the tune may be interrupted by keypad or trackwheel activity; otherwise, the tune may note be interrupted.
Returns:
One of the ALERT_* values.
Since:
JDE 4.0.2
See Also:
AlertListener2.adpcmDone(int)

stopADPCM

public static void stopADPCM()
Cancels an ADPCM alert in progress.
Since:
JDE 4.0.0

enablePWMSync

public static void enablePWMSync(boolean enable)
Enabled or disables PWM sync.
Since:
JDE 4.0.2

setADPCMVolume

public static void setADPCMVolume(int volume)
Sets the volume for ADPCM.

This is multiplied with the master volume.

Parameters:
volume - Percentage of total capable volume, from 0 to 100.
Since:
JDE 4.0.2

setBuzzerVolume

public static void setBuzzerVolume(int volume)

Sets the volume for the buzzer.

This is multiplied with the master volume.

Parameters:
volume - Percentage of total capable volume, from 0 to 100.
Since:
JDE 4.0.2

setVolume

public static void setVolume(int volume)
Sets the master volume.
Parameters:
volume - Percentage of total capable volume, from 0 to 100.
Since:
JDE 4.0.2

getVolume

public static int getVolume()
gets the master volume.
Returns:
volume Percentage of total capable volume, from 0 to 100.
Since:
JDE 4.0.2

mute

public static void mute(boolean toggle)

toggles the device between mute (volume 0) and loud state and persists the current volume level

any call to setVolume will override mute state

any later call to mute(false) will return the volume to the cached value

Parameters:
toggle - sets the mute if true, returns the volume to the previous value if false
Since:
JDE 4.0.2


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.