com.nttdocomo.device.location.LocationProvider
Object
現在地を測位する機能にアクセスする手段を提供します。
測位する機能にアクセスするには、getLocationProvider() を呼び出し、
測位機能を表すインスタンスを取得する必要があります。
取得した測位機能インスタンスは、
このクラスのいずれかのサブクラスのインスタンスです。
インスタンス取得後、
そのインスタンスに対して setMeasurementMode(int)
を用いて測位モードを設定することができます。
実際に設定することが可能な測位モードについては、
getAvailableMeasurementMode() により調べることができます。
インスタンスに設定されている測位モードは、
getMeasurementMode() によって取得することができます。
ここで指定した測位モードが測位精度や反応速度に与える影響は機種依存です。
詳しくはそれぞれのフィールドの説明を参照してください。
取得したインスタンスの getLocation() メソッドを呼び出すと、
指定した測位モードで現在地の測位を行います。
その際、iアプリはサスペンドしません。
測位により得られた位置情報は、
測位結果オブジェクトとして返されます。
| フィールドの概要 | |
static int |
CAPABILITY_TRACKING_MODE
測位方式の能力を表す定数値で、 トラッキングモード(定期的な測位)が利用可能なことを表します(=0)。 |
static int |
DATUM_TOKYO
東京測地系を表す定数値です(=1)。 |
static int |
DATUM_WGS84
WGS84 測地系を表す定数値です(=0)。 |
static int |
METHOD_GPS
測位方式を表す定数値で、 GPS による測位を表します(=0)。 |
static int |
MODE_QUALITY_PRIORITY
測位モードを表す定数値で、 品質重視モードで測位を行うことを表します(=1)。 |
static int |
MODE_STANDARD
測位モードを表す定数値で、 標準モードで測位を行うことを表します(=0)。 |
static int |
UNIT_DEGREE
DEGREE 単位を表す定数値です(=1)。 |
static int |
UNIT_DMS
DMS 単位(精度 1/100 秒)を表す定数値です(=0)。 |
static int |
UNIT_DMS_2
DMS 単位 (精度 1/1000 秒) を表す定数値です(=2)。 |
| メソッドの概要 | |
static int[] |
getAvailableLocationMethod()
サポートされている測位方式を取得します。 |
static int[] |
getAvailableLocationMethod(int capability)
指定された能力を持つ測位方式で、 サポートされているもののリストを取得します。 |
abstract int[] |
getAvailableMeasurementMode()
設定可能な測位モードを取得します。 |
Location |
getLocation()
測位を行います。 |
abstract Location |
getLocation(int timeout)
測位を行います。 |
static LocationProvider |
getLocationProvider()
デフォルトの測位方式で測位を行う、 測位機能のインスタンスを生成して返します。 |
static LocationProvider |
getLocationProvider(int method)
指定された測位方式で測位を行う、 測位機能のインスタンスを生成して返します。 |
int |
getMeasurementMode()
このインスタンスが測位時に使用する測位モードを取得します。 |
abstract int |
getMinimalInterval()
定期的な測位を実施するときに指定可能な、測位間隔の最小値を取得します。 |
abstract void |
interrupt()
測位を中断させます。 |
void |
setMeasurementMode(int mode)
測位モードを指定します。 |
void |
setTrackingListener(TrackingListener listener,
int interval,
int timeout)
定期的な測位を開始、または停止します。 |
| クラス Object から継承したメソッド |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| フィールドの詳細 |
public static final int DATUM_TOKYO
Location.getDatum(),
Location.transform(int),
定数フィールド値public static final int DATUM_WGS84
Location.getDatum(),
Location.transform(int),
定数フィールド値public static final int UNIT_DMS
Location.getLatitudeString(int, int),
Location.getLongitudeString(int, int),
定数フィールド値public static final int UNIT_DEGREE
Location.getLatitudeString(int, int),
Location.getLongitudeString(int, int),
定数フィールド値public static final int UNIT_DMS_2
Location.getLatitudeString(int, int),
Location.getLongitudeString(int, int),
定数フィールド値public static final int MODE_QUALITY_PRIORITY
測位モードを表す定数値で、 品質重視モードで測位を行うことを表します(=1)。
getLocation() を呼び出した際に、
できるだけ精度の高い測位結果を取得しようとします。
ただし、標準モードにて測位した場合に比べ、
測位にかかる時間が長くなる場合があります。
setMeasurementMode(int),
定数フィールド値public static final int MODE_STANDARD
測位モードを表す定数値で、 標準モードで測位を行うことを表します(=0)。
測位モードのデフォルト値です。
getLocation() を呼び出した際に、
できるだけ早く測位結果を取得しようとします。
ただし、品質重視モードにて測位した場合に比べ、
測位結果の精度が低くなる場合があります。
setMeasurementMode(int),
定数フィールド値public static final int METHOD_GPS
測位方式を表す定数値で、 GPS による測位を表します(=0)。
getLocationProvider(int),
getAvailableLocationMethod(),
定数フィールド値public static final int CAPABILITY_TRACKING_MODE
測位方式の能力を表す定数値で、 トラッキングモード(定期的な測位)が利用可能なことを表します(=0)。
getAvailableLocationMethod(int),
定数フィールド値| メソッドの詳細 |
public static int[] getAvailableLocationMethod()
サポートされている測位方式を取得します。 サポートされている測位方式のリストが返されます。
戻り値の配列に含まれている値であれば、
getLocationProvider(int) の引数に指定しても
UnsupportedOperationException が発生しないことが保証されています。
また、戻り値の第0要素は、無引数の getLocationProvider()
が呼び出された時に得られるインスタンスの測位方式です。
位置情報取得機能そのものをサポートしていない場合は null が返されます。
METHOD_から始まる定数)
が全て格納された一次元配列を返します。
返される配列は、このクラスが内部で保持している配列のコピーです。
位置情報取得機能そのものをサポートしていない場合
(サポートされている測位方式が1つも無い場合)
は null を返します。METHOD_GPS,
getLocationProvider(),
getLocationProvider(int)public static int[] getAvailableLocationMethod(int capability)
指定された能力を持つ測位方式で、 サポートされているもののリストを取得します。
このメソッド呼び出しで得られる測位方式の集合は、
常に getAvailableLocationMethod()
メソッド呼び出しで得られる測位方式の集合のサブセットとなっています。
capability - 取得したい測位方式が持つべき能力を表す定数
(このクラスに定義されている CAPABILITY_
から始まる定数) を指定します。
METHOD_ から始まる定数)
が全て格納された一次元配列を返します。
返される配列は、このクラスが内部で保持している配列のコピーです。
サポートされている測位方式の中に該当するものが無い場合には
null を返します。
IllegalArgumentException - 引数 capability に不正な値が指定された場合に発生します。
public static LocationProvider getLocationProvider(int method)
指定された測位方式で測位を行う、 測位機能のインスタンスを生成して返します。
引数には、本クラスに定義されている METHOD_
から始まる定数を指定できますが、どの方式をサポートしているかは、
位置情報取得機能そのものをサポートしているかどうかも含めて機種依存です。
それらのサポート状況を調べるためには
getAvailableLocationMethod() を呼び出してください。
そのメソッドの返り値に含まれていない測位方式が指定された場合には、
UnsupportedOperationException が発生します。
複数回呼び出された場合は毎回異なるインスタンスを生成して返しますが、
測位方式が異なるもの同士であっても、getLocation(int)
メソッドを同時に(並行に)呼び出すことはできません。
同時に呼び出した場合、後に呼び出したスレッドには例外が発生します。
パーミッションとして位置情報APIの利用が許可されているトラステッドiアプリのみ、 このメソッドを呼び出すことができます。 キーがない場合、iアプリは強制終了します。
method - インスタンスを取得したい測位方式を指定します。
現実装では METHOD_GPS のみが指定できます。
METHOD_GPS が指定された場合には
GPSLocationProvider
クラスのインスタンスが返されます。
UnsupportedOperationException - 測位機能がサポートされていないか、
サポートされていない測位方式が指定された場合に発生します。
SecurityException - パーミッションとして位置情報APIの利用が許可されているが、
iアプリ個別のユーザ設定により許可されない場合に発生します。
GPSLocationProviderpublic static LocationProvider getLocationProvider()
デフォルトの測位方式で測位を行う、
測位機能のインスタンスを生成して返します。
デフォルトの測位方式は、
getAvailableLocationMethod()
の戻り値の先頭の要素ですが、その具体的な値は機種依存です。
測位機能そのものがサポートされていない場合には
UnsupportedOperationException が発生します。
測位機能がサポートされている場合は、
getLocationProvider(int)
の引数に getAvailableLocationMethod()[0]
を指定して呼び出した場合と同じ振る舞いをします。
UnsupportedOperationException - 位置情報取得機能をサポートしていない場合に発生します。
SecurityException - パーミッションとして位置情報APIの利用が許可されているが、
iアプリ個別のユーザ設定により許可されない場合に発生します。
public Location getLocation()
throws LocationException
測位を行います。
このメソッドは getLocation(int)
の引数に
デフォルトのタイムアウト値を指定したものと等価です。
デフォルトのタイムアウト値については、機種依存です。
DeviceException - 現在実行中の Java アプリケーションや、ネイティブ機能において、
既に測位実施中の場合に発生します(BUSY_RESOURCE)。
DeviceException - 現在実行中の Java アプリケーションで、setTrackingListener(TrackingListener, int, int)
の引数 listener に、 null 以外が設定されている場合に発生します(BUSY_RESOURCE)。
LocationException - 端末がセルフモードの場合に発生します(SELF_MODE)。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
測位が禁止されている場合に発生します。
LocationException - このメソッドを呼び出してから、
デフォルトのタイムアウト値だけ経過しても、
測位結果が得られない場合に発生します(TIMEOUT)。
LocationException - サスペンド状態に遷移した場合や、
interrupt()
メソッド等により中断要求が発生した場合に発生します(INTERRUPTED)。
LocationException - ユーザ操作により中断要求が発生した場合に発生します(USER_ABORT)。
LocationException - 通信エラー等により、
測位に失敗した場合に発生します(UNDEFINED)。
public abstract Location getLocation(int timeout)
throws LocationException
測位を行います。 このメソッドを呼び出したスレッドは、測位が終了するまでブロックされます。
測位が正常終了すると、測位結果が設定された位置情報オブジェクト (Location オブジェクト)を返します。
測位開始から引数で指定した時間が経過すると、タイムアウトします。 サポートされているタイムアウト値の範囲を超えた値を指定した場合、 その上限または下限のタイムアウト値が指定されます。
timeout - タイムアウト値を秒単位で指定します。
0を指定した場合、
サポートされているタイムアウト値の上限が指定されます。
上限がない場合、タイムアウトしません。
IllegalArgumentException - 引数 timeout に負の値が指定された場合に発生します。
DeviceException - 現在実行中の Java アプリケーションや、ネイティブ機能において、
既に測位実施中の場合に発生します(BUSY_RESOURCE)。
DeviceException - 現在実行中の Java アプリケーションで、setTrackingListener(TrackingListener, int, int)
の引数 listener に、 null 以外が設定されている場合に発生します(BUSY_RESOURCE)。
LocationException - 端末がセルフモードの場合に発生します(SELF_MODE)。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
測位が禁止されている場合に発生します。
LocationException - このメソッドを呼び出してから、
引数に指定したタイムアウト値だけ経過しても、
測位結果が得られない場合に発生します(TIMEOUT)。
LocationException - サスペンド状態に遷移した場合や、
interrupt()
メソッド等により中断要求が発生した場合に発生します(INTERRUPTED)。
LocationException - ユーザ操作により中断要求が発生した場合に発生します(USER_ABORT)。
LocationException - 通信エラー等により、測位に失敗した場合に発生します(UNDEFINED)。
public abstract void interrupt()
測位を中断させます。
このインスタンスの getLocation() メソッド
にて測位を行っている場合にこのメソッドを呼び出すと、測位が中断されます。
中断されたスレッドは
LocationException(INTERRUPTED) が発生します。
測位が行われていないときに呼び出された場合は、
このメソッドはなにもしません。
また、別のインスタンスに対する getLocation() メソッド呼び出しは、
影響を受けません。
public void setMeasurementMode(int mode)
測位モードを指定します。
それぞれの測位モードを指定した場合の測位時の振る舞いについては､ フィールドの詳細を参照してください。
測位モードには、
getAvailableMeasurementMode()
によって返される配列の各要素の値を指定することができます。
それ以外の値を指定した場合は、
不正な値が指定されたとして例外が発生します。
mode - 測位モードを表す定数値を指定します。
IllegalArgumentException - 引数 mode に不正な値が指定された場合に発生します。
public int getMeasurementMode()
このインスタンスが測位時に使用する測位モードを取得します。
public abstract int[] getAvailableMeasurementMode()
設定可能な測位モードを取得します。
このメソッドによって取得した配列の各要素の値は、
setMeasurementMode(int) の引数に設定することにより、
その値が表す測位モードで i
アプリからの測位を行えることが保証されています。
public void setTrackingListener(TrackingListener listener,
int interval,
int timeout)
定期的な測位を開始、または停止します。
定期的な測位を開始するには、 定期的に測位結果を受けとるためのリスナをセットします。 リスナとして null でない値を指定した場合、 即座に定期的な測位を開始し、 測位結果は指定したリスナに定期的に通知されます。
定期的な測位を停止するには、 リスナとして null を指定してこのメソッドを呼び出して下さい。 その場合、第2引数以降にどのような値を指定しても無視されます。 また、定期的な測位を開始していないにもかかわらず、null を指定して このメソッドを呼び出した場合には何も起こりません。
引数 interval には、測位間隔を指定します。 サスペンド状態や休眠状態でない限り、 必ず指定された測位間隔でリスナが呼び出されます。 測位間隔には、実装がサポートする最小測位間隔以上の値を指定してください。 それ以下の値を指定した場合には、 最小測位間隔が指定されたものとして振る舞います。
引数 timeout には、
最新の測位結果が取得できない状態が何 msec 経ったら
「測位不能」とみなすかを指定します。
具体的には、前回に測位が成功した瞬間から
(interval + timeout) [msec] 経っても最新の測位結果が取得できない場合に
「測位不能」とみなします。
「測位不能」時の具体的な振る舞いについては
TrackingListener クラスの説明を参照して下さい。
なお、 既に(null でない)リスナが設定されている状態で、 (nullでない)リスナを指定してこのメソッドを呼び出した場合には、 今まで行われていた定期的な測位を停止してから(リスナとして null を指定してこのメソッドを呼び出した場合と同様に振る舞ってから)、 新しく定期的な測位を開始します。
このメソッドは、 トラッキングモードが有効な測位方式でのみサポートされています。 サポートされていない測位方式では、 このメソッドを呼び出しても何も起きず、 引数にどのような値を指定しても例外は発生しません。
listener - 定期的な測位結果を受けとるリスナを指定します。
定期的な測位を停止したい場合には null を指定します。interval - 測位間隔 [msec] を指定します。timeout - タイムアウト [msec] を指定します。
0 を指定することも可能です。
また、-1 を指定するとタイムアウトしません
(測位不能とみなされることはありません)。
IllegalArgumentException - 引数 interval に 0 以下の値が指定された場合に発生します。
IllegalArgumentException - 引数 timeout に -1 未満の値が指定された場合に発生します。
DeviceException - 現在実行中の Java アプリケーションや、ネイティブ機能において、
既に測位実施中の場合に発生します(BUSY_RESOURCE)。
public abstract int getMinimalInterval()
定期的な測位を実施するときに指定可能な、測位間隔の最小値を取得します。
トラッキングモードをサポートしていない測位方式のインスタンスでは -1 が返されます。
setTrackingListener(TrackingListener, int, int)