net.rim.device.api.system
Class MagnetometerSensor.Channel

java.lang.Object
  extended by net.rim.device.api.system.MagnetometerSensor.Channel
Enclosing class:
MagnetometerSensor

public static class MagnetometerSensor.Channel
extends Object

Encapsulates an active connection to the magnetometer sensor. While the channel remains open, the sensor is queried for samples. To preserve battery power, invoke MagnetometerSensor.Channel.close() to close the channel and stop querying the sensor.

Since:
BlackBerry API 7.0.0

Method Summary
 void addMagnetometerListener(MagnetometerListener l)
          Register a magnetometer listener.
 void close()
          Closes the channel and stops querying the sensor.
 MagnetometerChannelConfig getConfig()
          Retrieves the magnetometer channel configuration.
 MagnetometerData getData()
          Returns the last captured magnetometer data.
 boolean isActive()
          Indicates whether the channel is currently active and collecting the requested data.
 boolean isCalibrating()
          Returns the calibration application status.
 boolean isOpen()
          Indicates whether the channel is open.
 void removeMagnetometerListener(MagnetometerListener l)
          Deregisters a magnetometer listener.
 void startCalibration()
          Starts the calibration process.
 void stopCalibration()
          Stops the calibration process.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

getConfig

public MagnetometerChannelConfig getConfig()
Retrieves the magnetometer channel configuration.

Returns:
The magnetometer channel configuration.
Since:
BlackBerry API 7.0.0

addMagnetometerListener

public void addMagnetometerListener(MagnetometerListener l)
Register a magnetometer listener.

Parameters:
l - The magnetometer listener, must not be null
Throws:
NullPointerException - if MagnetometerListener is null
IllegalStateException - if the application that owns this channel no longer exists
Since:
BlackBerry API 7.0.0

removeMagnetometerListener

public void removeMagnetometerListener(MagnetometerListener l)
Deregisters a magnetometer listener. This method does nothing if the listener isn't registered.

Parameters:
l - The magnetometer listener
Since:
BlackBerry API 7.0.0

close

public void close()
Closes the channel and stops querying the sensor. To preserve battery power, invoke this method as soon as the magnetometer data is no longer required.

Since:
BlackBerry API 7.0.0

getData

public MagnetometerData getData()
Returns the last captured magnetometer data. The frequency that this data is updated is based on this channel's configuration.

The MagnetometerData object returned from this method is reused by this channel. You can synchronize on this object to ensure the data doesn't change while using it.

Returns:
The magnetometer data.
Throws:
IllegalStateException - if the MagnetometerSensor.Channel is closed.
Since:
BlackBerry API 7.0.0

isCalibrating

public boolean isCalibrating()
Returns the calibration application status.

Returns:
true if the calibration application is running, false otherwise.
Since:
BlackBerry API 7.0.0

startCalibration

public void startCalibration()
                      throws IllegalStateException,
                             MagnetometerCalibrationException
Starts the calibration process.

If this channel's MagnetometerChannelConfig is set such that MagnetometerChannelConfig.isShowCalibration() returns false, calibration will be enabled, but no calibration instructions will be shown. It is then up to this channel's owner to invoke MagnetometerSensor.Channel.stopCalibration(). If MagnetometerChannelConfig.isShowCalibration() returns true then calibration instructions are shown, and calibration is stopped once it's either stopped programatically, or the instructions are dismissed by the user.

Throws:
MagnetometerCalibrationException - if the channel is inactive or calibration is already in progress.
IllegalStateException - if the MagnetometerSensor.Channel is closed.
Since:
BlackBerry API 7.0.0

stopCalibration

public void stopCalibration()
                     throws IllegalStateException,
                            MagnetometerCalibrationException
Stops the calibration process.

Calibration is stopped automatically when a channel becomes inactive or closed.

Throws:
MagnetometerCalibrationException - if calibration fails to stop.
IllegalStateException - if the MagnetometerSensor.Channel is closed.
Since:
BlackBerry API 7.0.0

isActive

public boolean isActive()
Indicates whether the channel is currently active and collecting the requested data. The channel can be inactive when the application is in background mode, and the channel was not requested to remain open in the background.

Returns:
true if the channel is open and active, false otherwise.
See Also:
MagnetometerSensor.Channel.isOpen()
Since:
BlackBerry API 7.0.0

isOpen

public boolean isOpen()
Indicates whether the channel is open.

Returns:
true if the channel is open, false otherwise.
See Also:
MagnetometerSensor.Channel.isActive()
Since:
BlackBerry API 7.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal