定期的な測位において、測位結果を受け取るためのリスナを定義します。
トラッキングモードをサポートする測位方式のインスタンスに対して、
LocationProvider.setTrackingListener(TrackingListener listener,
int interval, int timeout)
にて、このリスナをセットすることで、
定期的に測位結果を受けとることができます。
上記メソッドにおいてリスナが設定されると、即座に定期的な測位が開始され、
引数 interval [msec] ごとに、設定されたリスナの
locationReceived(LocationProvider src,
Location result, Exception cause)
の引数 result に最新の測位結果がセットされた状態でコールバックされます。
なお、初回の測位結果が得られるまでは、コールバックは行われません。
初回の測位結果(その結果が成功か失敗かは問いません)
が得られた時点で初回のコールバックがなされ、
その後は interval [msec] ごとの定期的なコールバックとなります。
実装は、interval [msec] ごとに測位結果が更新されるように振る舞いますが、 様々な要因によって、測位が間に合わない場合も有り得ます。 その場合でも、あくまでもリスナは interval [msec] おきに呼び出され、 その時点における最新の測位結果が渡されることに注意してください。
前回に測位が成功した瞬間から (interval + timeout) [msec] 経っても最新の測位結果が取得できない場合は、 測位不能とみなされます。 測位不能とみなされた場合、実装は以下のように振る舞います。
locationReceived() メソッドはコールバックされます。
その時の Location 型の引数 result には null が、
Throwable 型の引数 cause には、
直前の測位失敗時に発生した例外オブジェクトが、
それぞれ設定されています。
設定されている例外オブジェクトは、
通常の測位に失敗した時に発生する例外と同じものです。locationReceived()
メソッドがコールバックされた時には、
Location 型の引数 result に最新の測位結果が設定されています。
サスペンド状態や休眠状態に遷移した場合でも、
それらの状態から復帰した時点から定期的な測位、
ならびにコールバックを再開します。
リスナが設定されているにもかかわらずコールバックが停止することはありません。
コールバックを明示的に停止したい場合には
setTrackingListener() メソッドの第1引数に
null を指定して呼び出して下さい。
なお、メソッドがコールバックされる間隔や、測位不能とみなされる時間には、 サスペンド/休眠中の時間も含まれます。 具体的には、 サスペンド/休眠状態から復帰した場合には以下のように振る舞います。
LocationProvider.setTrackingListener(TrackingListener, int, int)| メソッドの概要 | |
void |
locationReceived(LocationProvider src,
Location result,
Exception cause)
定期的な測位が開始されている場合に、 定期的にコールバックされます。 |
| メソッドの詳細 |
public void locationReceived(LocationProvider src,
Location result,
Exception cause)
src - このリスナが設定されている測位機能オブジェクトが設定されています。result - 最新の測位結果が設定されています。
測位不能な場合には null が設定されています。cause - 測位不能な場合に、
測位に失敗した原因となった例外オブジェクトが設定されています。
引数 result が非 null である場合には null が設定されています。