com.docomostar.device.location
クラス Compass

Object
  com.docomostar.device.location.Compass

public class Compass
extends Object

[iアプリオプションAPI]

電子コンパス機能を提供します。

電子コンパス機能は地磁気センサにより、端末の方位角を取得する機能を提供します。 端末の方位角の値は、磁北を 0 度とし、時計回りを正の方向として取得します。

[Star-1.5 以降]
電子コンパス機能では、現在の方位角を得るワンショット計測の他に、 周期的に連続して方位角を得る周期計測を提供します。 また、計測する方向を PhoneSystem.DEV_EYE_DIRECTION で設定しておくことで、 Star アプリはユーザの視線の方向が反映された方位角を取得できます。 PhoneSystem.DEV_EYE_DIRECTION の設定は、ワンショット計測と周期計測の両方で有効です。

周期計測では、 ユーザの視線の方向を反映した計測結果を実装内部の計測データ蓄積バッファに蓄積します。
周期計測の計測結果は、周期計測中あるいは計測後に蓄積バッファ内から取得できます。 取得できる方位角は、DEGREE 単位で表した値のみとなります。 DMS 単位で表された方位角を取得する場合は、Degree クラスを利用して下さい。

周期計測中は、ユーザの視線の方向を設定することができません。 そのため、ユーザの視線の方向を再設定する前には、周期計測を停止し、 バッファから計測結果を取得しておいて下さい。

周期計測中に Canvas の座標系を変更する(Canvas2 を使用する)場合

蓄積バッファ内のデータの一貫性が保証されなくなるため、 Star アプリが期待する計測結果が得られないことがあります。 Star アプリが期待する結果を得るためには、 周期計測を停止させ蓄積バッファよりデータを取得してから、 Canvas の座標系を変更し、周期計測を再開して下さい。

導入されたバージョン:

Star-1.0

フィールドの概要

static double

BUFFER_EMPTY 周期計測の最新値を表す定数で、バッファにデータが存在していないことを表します(=-9999.0)。

コンストラクタの概要

protected

Compass() アプリケーションが直接このコンストラクタを呼び出して オブジェクトを生成することはできません。

メソッドの概要

void	disposeData() 周期計測用の蓄積バッファをクリアします。
Degree	getAzimuth() ワンショット計測により、現在の方位角を取得します。
static Compass	getCompass() 電子コンパス機能のインスタンスを返します。
double[]	getData() 周期計測用の蓄積データバッファから計測結果を取得します。
int	getDataSize() 周期計測用の蓄積データバッファに蓄積されているデータ数を取得します。
int	getIntervalResolution() 周期計測の計測間隔の解像度を取得します。
int	getMaxDataSize() 周期計測において実装内部で蓄積可能な最大データ数を取得します。
double	peekLatestData() 周期計測用の蓄積データバッファから最新の計測値を1つ取得します。
void	setEnabled(boolean enabled) 電子コンパス機能を有効化・無効化します。
void	start(int interval) 周期計測を開始します。
void	stop() 周期計測を停止します。

クラス Object から継承されたメソッド

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

フィールドの詳細

BUFFER_EMPTY

public static final double BUFFER_EMPTY

周期計測の最新値を表す定数で、バッファにデータが存在していないことを表します(=-9999.0)。

導入されたバージョン:

Star-1.5

関連項目:

定数フィールド値

コンストラクタの詳細

Compass

protected Compass()

アプリケーションが直接このコンストラクタを呼び出して オブジェクトを生成することはできません。

メソッドの詳細

getCompass

public static Compass getCompass()

電子コンパス機能のインスタンスを返します。 複数回呼び出された場合は、常に同じインスタンスを返します。

実装によっては、電子コンパス機能をサポートしていない場合があります。

戻り値:

電子コンパス機能のインスタンスを返します。

例外:

UnsupportedOperationException -
電子コンパス機能をサポートしていない場合に発生します。

DeviceException -
(NO_RESOURCES)
[Star-1.5 以降] 地磁気センサデバイスを確保できない場合に発生します。

getAzimuth

public Degree getAzimuth()

ワンショット計測により、現在の方位角を取得します。

このメソッドは、電子コンパス機能が有効化された状態で呼び出す必要があります。 無効化された状態で呼び出された場合には例外が発生します。

本メソッドの実行に成功すると、 周期測定用の測定結果蓄積バッファはクリアされます。

戻り値:

この端末が向いている方位角を表す Degree オブジェクトを返します。 様々な要因により、 正しい方位角を測定できていない可能性がある場合でも、 常に何らかの値を返します。

例外:

IllegalStateException -
電子コンパス機能が無効化されている場合に発生します。

DeviceException -
(ILLEGAL_STATE)
[Star-1.5 以降] 電子コンパス機能が周期計測中の場合に発生します。

start

public void start(int interval)

周期計測を開始します。

指定した間隔毎に周期計測を行います。 実装がサポートしている計測間隔は、 getIntervalResolution() で得られる解像度の倍数です。 実装サポート値以外の計測間隔を指定した場合、 指定した値以上で最も実装サポート値に近い値が指定されたものとして 扱われます。

周期計測を開始する前に、電子コンパス機能を有効化する必要があります。 無効化された状態で、このメソッドが呼び出された場合には例外が発生します。

周期計測を停止させるためには、 stop()メソッドを使用します。 周期計測中に電子コンパス機能が無効化された場合、 周期計測は停止します。

計測結果は、実装内部の計測結果蓄積バッファに蓄積されていきます。 蓄積可能な最大データ数は、 getMaxDataSize() により取得できます。 最大データ数を超えると、蓄積されたデータの 古いものから上書きします。 計測結果は、getData()により、 周期計測中および周期計測後に取得できます。 蓄積された計測結果は、 次にワンショット計測、または周期計測を行った場合、 またdisposeData()、 getData()を呼び出した場合、 アプリケーションを終了した場合にクリアされます。

周期計測中にサスペンドが発生した場合、 周期計測は自動的に停止します。 周期計測を再開する場合には、レジュームイベント処理において、 再度本メソッドを呼び出してください。 サスペンド前の計測値は getData()により取得して下さい。

getAzimuth()メソッド呼び出し中に 別のスレッドからこのメソッドが呼び出された場合、 getAzimuth()呼び出し終了までこの メソッドの実行は遅延されます。

本メソッドの実行に成功すると、 周期計測用の蓄積バッファはクリアされます。

パラメータ:

interval - 周期計測の間隔をミリ秒単位で指定します。

導入されたバージョン:

Star-1.5

例外:

IllegalArgumentException -
引数 interval の値が 0 以下の場合に発生します。

IllegalStateException -
電子コンパス機能が無効化されている場合に発生します。

DeviceException -
(ILLEGAL_STATE)
電子コンパス機能が既に周期計測中の場合に発生します。

DeviceException -
(BUSY_RESOURCE)
歩行方位取得機能が歩行検知計測中の場合に発生します。

stop

public void stop()

周期計測を停止します。

周期計測中以外に呼ばれた場合、何もしません。

導入されたバージョン:

Star-1.5

getIntervalResolution

public int getIntervalResolution()

周期計測の計測間隔の解像度を取得します。
このメソッドにより得られる値の自然数倍の計測間隔をサポートします。

戻り値:

実装がサポートする、周期計測間隔の解像度をミリ秒単位で返します。

導入されたバージョン:

Star-1.5

getMaxDataSize

public int getMaxDataSize()

周期計測において実装内部で蓄積可能な最大データ数を取得します。
周期計測は、最大データ数を超えると蓄積されたデータの 古いものから上書きします。

戻り値:

実装がサポートする、蓄積可能な最大データ数を返します。

導入されたバージョン:

Star-1.5

getDataSize

public int getDataSize()

周期計測用の蓄積データバッファに蓄積されているデータ数を取得します。

戻り値:

蓄積データ数を返します。

導入されたバージョン:

Star-1.5

getData

public double[] getData()

周期計測用の蓄積データバッファから計測結果を取得します。

このメソッドは、呼び出しの度に新しい配列を生成し、その配列の参照を返します。 戻り値の配列の全要素に有効な計測データが格納されています。

本メソッドの実行に成功すると、 周期計測用の蓄積バッファはクリアされます。

蓄積バッファに計測データが 1 つも蓄積されていない時に本メソッドを呼び出した場合、 null を返します。

周期計測中に計測結果を取得した場合でも引き続き周期的に計測されます。

戻り値:

周期計測の全計測データを配列で返します。計測データは DEGREE 単位で表した方位角です。

導入されたバージョン:

Star-1.5

peekLatestData

public double peekLatestData()

周期計測用の蓄積データバッファから最新の計測値を1つ取得します。

本メソッドの実行に成功しても、 周期計測用の蓄積バッファはクリアされません。

蓄積バッファに計測データが 1 つも蓄積されていない時に本メソッドを呼び出した場合、 BUFFER_EMPTY を返します。

戻り値:

周期計測の最新計測データを返します。

導入されたバージョン:

Star-1.5

disposeData

public void disposeData()

周期計測用の蓄積バッファをクリアします。

導入されたバージョン:

Star-1.5

setEnabled

public void setEnabled(boolean enabled)

電子コンパス機能を有効化・無効化します。 方位角の計測を行うには、電子コンパス機能を有効化する必要があります。

電子コンパス機能が有効化されている間は、通常より多くの電力を消費します。 電子コンパス機能を利用しないときは、このメソッドで無効化して下さい。

電子コンパス機能が既に有効化されている状態で有効化しようとしたり、 既に無効化されている状態で無効化しようとした場合には、何もしません。

電子コンパス機能が有効化されている状態で、このアプリケーションが終了した場合は、 電子コンパス機能は無効化されます。

パラメータ:

enabled - 電子コンパス機能を有効化するには true を、 無効化するには false を、それぞれ指定します。