SINETStreamHelper ユーザガイド（端末位置情報の追跡部）
目次
1. モジュール構成 2. API概要 3. インタフェース LocationTrackerListener 3.1 メソッド概要 3.2 メソッド詳細 3.2.1 onLocationSettingsChecked 3.2.2 onLocationEngaged 3.2.3 onLocationDisengaged 3.2.4 onLocationDataReceived 3.2.5 onError 4. クラスLocationTracker 4.1 コンストラクタ概要 4.2 メソッド概要 4.3 コンストラクタ詳細 4.4 メソッド詳細 4.4.1 start 4.4.2 stop 4.4.3 bindLocationService 4.4.4 unbindLocationService 付録 A.1 ライフサイクル
1. モジュール構成
SINETStreamHelperライブラリにおける「Android端末位置の追跡取得」機能のモジュール構成を以下に示す。
#-------------------------------------------------------+
| User Application |
+-------------------------------------------------------+
| A
=====================|=============================|== API functions
| |
+------------------|-----------------------------|------+
| V | [Location]
| +----------------------------------+ +----------+ |
| | LocationTracker |---> | Location | |
| | +----------+ +----------+ | | Tracker | |
| | |Permission| |Settings | | | Listener | |
| | |Handler | |Handler | | +----------+ |
| | +----------+ +----------+ | |
| +----------------------------------+ |
| | A | A |
| V | [Location] V | [Location] |
| +----------------+ +----------------+ |
| | GpsService | | FlpService | |
| +----------------+ +----------------+ |
| | A | A |
| | | | | SINETStreamHelper |
| | | | | (Location Handler)|
+------|--|-------------------|--|----------------------+
| | | |
=========|==|===================|==|================= Android System
| | V |
| | ..............................
V | [Location] : Google Play Service :
+------------+ : +------------------------+ :
| Location | +--->| Fused | :
| Manager | | : | LocationProviderClient | :
+------------+ | : +------------------------+ :
| A | : A A A :
| | | :.....|.......|.......|......:
=========|==|=============|========|=======|=======|======== Devices
| | | | | |
V | [Raw Data] | | | | [Raw Data]
+----------+ | +-----+ +----+ +-------+
| GPS |---------+ | NET | | BT | | ... |
+----------+ +-----+ +----+ +-------+
〈凡例〉
- LocationTracker
- Android端末位置情報の追跡取得機能のフロントエンドとして、制御用のAPI関数一式を提供する。
- Permission Handler
- Androidシステムで端末の位置情報取得のためには、ユーザアプリケーション実行時に所用のアクセス権限を取得する必要がある。
SINETStreamHelperライブラリがユーザアプリケーションの代理として権限取得処理を操作する。
- Settings Handler
- システム設定情報の現在の値（特に位置情報取得に関する箇所）を参照する。
- GpsService
- Android端末位置情報の追跡取得機能のバックエンドとして、常駐型サービスとして動作する。本書では対となるFlpServiceと合わせ
位置情報サービスと呼称する。 - Android端末の具備するGPSデバイスを利用して測位するための制御を担当する。
- 測位精度を確保するためにフォアグラウンドで動作し、動作中であることを示す通知アイコンを表示する。
- FlpServiceとは排他動作となる。
- Android端末位置情報の追跡取得機能のバックエンドとして、常駐型サービスとして動作する。本書では対となるFlpServiceと合わせ
- FlpService
- Android端末位置情報の追跡取得機能のバックエンドとして、常駐型サービスとして動作する。本書では対となるGpsServiceと合わせ
位置情報サービスと呼称する。 - Google Play開発者サービスと連携して測位するための制御を担当する。
- 測位精度を確保するためにフォアグラウンドで動作し、動作中であることを示す通知アイコンを表示する。
- GpsServiceとは排他動作となる。
- Android端末位置情報の追跡取得機能のバックエンドとして、常駐型サービスとして動作する。本書では対となるGpsServiceと合わせ
- LocationTrackerListener
SINETStreamHelperライブラリからの端末位置情報自動更新に関するコールバックインタフェースを定義する。- これらの実体は利用者側アプリケーションで実装すること。
2. API概要
- パッケージ
- jp.ad.sinet.stream.android.helper
- 公開インタフェース
- LocationTrackerListener
- 公開クラス
- LocationTracker
3. インタフェース LocationTrackerListener
3.1 メソッド概要
- onError
- エラー検出時に呼ばれる。
- onLocationSettingsChecked
- 位置情報の利用可能性検査が完了した場合に呼ばれる。
- onLocationDisengaged
- メソッド
LocationTracker.unbindLocationService()により、 本ライブラリ内部の位置情報サービスと切断した場合に呼ばれる。
- メソッド
- onLocationEngaged
- メソッド
LocationTracker.bindLocationService()により、 本ライブラリ内部の位置情報サービスと結合した場合に呼ばれる。
- メソッド
- onLocationDataReceived
- 新しい位置情報が得られた場合に呼ばれる。
3.2 メソッド詳細
3.2.1 onLocationSettingsChecked
void onLocationSettingsChecked(boolean isReady)
- 説明：
- 位置情報の利用可能性検査が完了した場合に呼ばれる。
- 引数:
- isReady - 真であれば、次のメソッド
LocationTracker.bindLocationService()を発行可能。さもなくば、同メソッドがエラーで失敗する。
- isReady - 真であれば、次のメソッド
3.2.2 onLocationEngaged
void onLocationEngaged(@NonNull
java.lang.String info)
- 説明：
- メソッド
LocationTracker.bindLocationService()により、 本ライブラリ内部の位置情報サービスと結合した場合に呼ばれる。 - この時点から、クライアントは端末の位置情報の通知を受けられる。
- メソッド
- 引数:
- info - システムからの通知メッセージ（なければ空文字）
3.2.3 onLocationDisengaged
void onLocationDisengaged(@NonNull
java.lang.String info)
- 説明：
- メソッド
LocationTracker.unbindLocationService()により、 本ライブラリ内部の位置情報サービスと切断した場合に呼ばれる。 - クライアントの終了前にこの通知を待つこと。
- メソッド
- 引数:
- info - システムからの通知メッセージ（なければ空文字）
3.2.4 onLocationDataReceived
void onLocationDataReceived(@NonNull
android.location.Location location)
- 説明：
- 新しい位置情報を得た場合に呼ばれる。
- 引数:
- location - Androidシステムから通知された位置情報
Android開発者文書にて定義された Location オブジェクト
- location - Androidシステムから通知された位置情報
3.2.5 onError
void onError(@NonNull
java.lang.String errmsg)
- 説明：
- 何らかのエラー条件を満たしたときに呼ばれる。
- 引数:
- errmsg - エラー内容メッセージ
4. クラスLocationTracker
- 本クラスは、SINETStreamHelperライブラリのフロントエンドとして端末位置情報の自動更新を受けるためのAPI関数一式を提供する。
- LocationTrackerは本ライブラリ内部の
サービス
要素
GpsServiceまたはFlpServiceと結合し、同サービスと協調動作する。 - 位置情報サービスとはAndroidのメッセージング機構で通信するため、以下の
メソッドは非同期要求として扱うこと。
- start
- stop
- bindLocationService
- unbindLocationService
- 本クラスの利用者は、呼び出し側の
Activity
において
LocationTrackerListenerを実装し、処理結果やエラーの非同期通知を受けられるようにしなければならない。
4.1 コンストラクタ概要
- LocationTracker
- LocationTrackerのインスタンスを生成する。
4.2 メソッド概要
- start
- システム設定状況に問題なければ、
位置情報サービスを起動する。
- システム設定状況に問題なければ、
- stop
位置情報サービスが実行中であれば、これを終了する。
- bindLocationService
位置情報サービスと結合し、センサー処理を開始する。
- unbindLocationService
位置情報サービスと切断し、センサー処理を終了する。
4.3 コンストラクタ詳細
public LocationTracker(@NonNull
androidx.appcompat.app.AppCompatActivity activity,
@NonNull
final String locationProviderName,
int clientId)
- 説明：
- LocationTrackerのインスタンスを生成する。
- 引数:
- activity -
LocationTrackerListenerを実装した 基本アクティビティ - locationProviderName - 端末位置を追跡する情報源となる位置情報プロバイダ種別（
gpsまたはfused） - clientId -
位置情報サービスに結合したクライアント同士を峻別する識別子
- activity -
- 注意：
- 本コンストラクタは、端末位置の取得に関するシステム設定状況や実行時権限の確認のために ActivityResultLauncherにより別アクティビティを本ライブラリから呼び出している[1]。
- 上記
ActivityResultLauncherの利用上の制限のため、本コンストラクタは利用者側ActivityのonCreate()内で呼び出す必要がある。さもないと実行時にIllegalStateExceptionが発生する[2]。
- 例外:
- java.lang.RuntimeException - 付与のコンテクストが所用のリスナーを実装していない
- java.lang.IllegalStateException - 呼び出し側Activityの内部状態が
onCreateでない
- 参考:
4.4 メソッド詳細
4.4.1 start
public void start()
- 説明：
位置情報サービスを利用するにあたり、現状のシステム設定内容の妥当性に関して一連の検査を実施する。- 処理に成功した場合は、コンストラクタで指定された位置情報プロバイダに対応する「本ライブラリ内部サービス（
GpsServiceまたはFlpService）」が自動的に起動される。 - Androidシステムから位置情報の自動更新が受けられるか否か
LocationTrackerListener.onLocationSettingsCheckedにて通知される。 - 処理途中で何らかのエラーを検出した場合は
LocationTrackerListener.onErrorで通知される。
- 参考：
4.4.2 stop
public void stop()
- 説明：
位置情報サービスが実行中であれば、これを停止する。- 処理途中で何らかのエラーを検出した場合は
LocationTrackerListener.onErrorで通知される。
- 参考：
4.4.3 bindLocationService
public void bindLocationService()
- 説明：
位置情報サービスに結合し、センサー制御を開始する。- 本メソッドは非同期要求であるため、利用者は操作完了を待つ必要がある。
- 処理に成功した場合は
LocationTrackerListener.onLocationEngagedで通知される。 さもなくばLocationTrackerListener.onErrorで通知される。
- 参考：
4.4.4 unbindLocationService
public void unbindLocationService()
- 説明：
位置情報サービスと切断し、センサー制御を終了する。- 本メソッドは非同期要求であるため、利用者は操作完了を待つ必要がある。
- 処理に成功した場合は
LocationTrackerListener.onLocationEngagedで通知される。 さもなくばLocationTrackerListener.onErrorで通知される。
- 参考：
付録
A.1 ライフサイクル
( constructor )
|
+-----------> |
| |
| V
| start()
| |
| |-----> onLocationSettingsChecked(true)
| +------> |
| | V
| | bindLocationService()
| | |
| | |-----> onLocationEngaged()
| | |
| | |-----> onLocationDataReceived()
// // // :
| | |-----> onLocationDataReceived()
| | V
| | unbindLocationService()
| | |
| | |-----> onLocationDisengaged()
| +-------<>
| |
| V
| stop()
| |
+------------<>
|
V