com.docomostar.system
クラス AutoPositioning

Object
  com.docomostar.system.AutoPositioning

public final class AutoPositioning
extends Object

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

自動測位機能にアクセスする手段を提供するクラスです。 自動測位機能は、登録した制御情報に従って自動的に測位を実施する機能です。 このクラスでは、制御情報の登録、削除および登録された制御情報の取得を行うことができます。

自動測位機能は Star アプリを実行していない状態であっても、 ユーザの移動状況に応じて測位を実施します。 測位結果は Star アプリからあらかじめ登録された URL へ通知されます。 コンテンツプロバイダは、通知された測位結果をもとに、 招集メッセージなどを用いて、Star アプリの起動を促すことができます。 なお、LocationRecord クラスから自動測位機能による測位履歴を参照することができます。

Star アプリから自動測位機能にアクセスするには、getAutoPositioning() メソッドを呼び出し、 インスタンスを取得する必要があります。 インスタンス取得後、setParameter(AutoPositioningParam) メソッドにより制御情報を登録します。 制御情報が新規に登録されると、その制御情報に基づく自動測位を開始します。 ただし、制御情報が登録されている状態であっても、 自動測位が停止していることがあります。

制御情報を登録することができる Star アプリの数には上限があります。 上限に達しているために、新規に登録することができない場合には、 deleteBySelection() メソッドを呼び出して、 他の Star アプリによって登録されている 制御情報を削除してください。 上限に達しているかどうかを確認するには、isOccupied() メソッドを呼び出してください。

登録されている制御情報は、getParameter() メソッドで取得することができます。 制御情報が登録されている状態で、setParameter(AutoPositioningParam) メソッドを呼び出すと、 新しい制御情報に基づいて自動測位を継続します。

この Star アプリから登録した制御情報を削除するには、delete() メソッドを呼び出します。 削除されると、その制御情報に基づく自動測位を終了します。

制御情報を登録した後に Star アプリを終了しても、自動測位に影響を与えません。

導入されたバージョン:

Star-1.2

関連項目:

AutoPositioningParam, LocationRecord

メソッドの概要

void	delete() この Star アプリから登録されている制御情報を削除します。
void	deleteBySelection() ユーザ操作により、Star アプリから登録されている制御情報を削除します。
static AutoPositioning	getAutoPositioning() AutoPositioning のインスタンスを返します。
AutoPositioningParam	getParameter() この Star アプリから登録されている制御情報を取得します。
boolean	isOccupied() 制御情報を登録している Star アプリの数が上限に達しているためにこの Star アプリから制御情報の登録ができないかどうかを返します。
void	setParameter(AutoPositioningParam param) 制御情報を登録します。

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

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

メソッドの詳細

getAutoPositioning

public static AutoPositioning getAutoPositioning()

AutoPositioning のインスタンスを返します。

複数回呼び出された場合は、常に同じインスタンスを返します。

パーミッションとしてオートGPS機能の利用が許可されているトラステッド Star アプリのみ、このメソッドを呼び出すことができます。 パーミッションとしてオートGPS機能の利用が許可されていない場合、Star アプリは強制終了します。

端末によっては、自動測位機能をサポートしていない場合があります。 その場合には、例外 UnsupportedOperationException が発生します。

戻り値:

AutoPositioning のインスタンスを返します。

例外:

UnsupportedOperationException -
端末が自動測位機能をサポートしていない場合に発生します。

SecurityException -
UIM が装着されていない場合に発生します。

IllegalStateException -
i モードサービス用デフォルト APN 以外の APN に設定変更されている場合に発生します。

isOccupied

public boolean isOccupied()

制御情報を登録している Star アプリの数が上限に達しているためにこの Star アプリから制御情報の登録ができないかどうかを返します。

制御情報を登録する前にこのメソッドを呼び出して true が返ってきた場合、 この Star アプリから制御情報を登録する前に deleteBySelection() メソッドを呼び出して、 ユーザ操作により他の Star アプリから登録された 制御情報を削除する必要があります。

既にこの Star アプリから制御情報が登録されている場合、 deleteBySelection() メソッドを呼び出す必要はありません。 そのため、既にこの Star アプリから制御情報を登録している場合は必ず false を返します。

戻り値:

制御情報を登録している Star アプリの数が上限に達しているためにこの Star アプリから制御情報の登録ができない場合は true、 それ以外の場合は false を返します。 ただし、この Star アプリから既に制御情報を登録している場合は false を返します。

例外:

SecurityException -
Star アプリ個別のユーザ設定により許可されない場合に発生します。

setParameter

public void setParameter(AutoPositioningParam param)
                  throws StoreException,
                         InterruptedOperationException

制御情報を登録します。

このメソッドを呼び出して登録に成功すると、この Star アプリはサスペンドして、 登録完了の旨を表すネイティブのダイアログが表示されます。 ユーザ操作によりダイアログが閉じられると、 この Star アプリはレジュームします。

登録が完了すると、登録した制御情報に基づいて自動測位を開始し、 現在地の通知を行います。 既にこの Star アプリから制御情報を登録している場合、 新しい制御情報に基づいて自動測位を継続します。

この Star アプリから制御情報が登録されておらず、 かつ制御情報を登録している Star アプリの数が上限に達している状態でこのメソッドから登録を行った場合、 例外が発生します。

パラメータ:

param - 登録する制御情報を指定します。

例外:

NullPointerException -
引数 param に null が指定された場合に発生します。

SecurityException -
Star アプリ個別のユーザ設定により許可されない場合に発生します。

SecurityException -
ロック機能などのネイティブ独自のセキュリティ設定により、 制御情報が登録できない場合に発生します。

StoreException -
(STORE_FULL)
この Star アプリから制御情報が登録されておらず、 かつ制御情報を登録している Star アプリの数が上限に達している状態でこのメソッドを呼び出した場合に発生します。

StoreException -
(UNDEFINED)
Star アプリがサスペンドする前に、 上記以外の理由により登録ができない場合に発生します。

InterruptedOperationException -
競合条件などにより、ネイティブ機能が異常終了した場合に発生します。

getParameter

public AutoPositioningParam getParameter()

この Star アプリから登録されている制御情報を取得します。

このメソッドで返される AutoPositioningParam オブジェクトは、 この Star アプリから登録されている制御情報のコピーです。 取得したオブジェクトが保持しているパラメータを変更しても、 setParameter(AutoPositioningParam)で上書き登録を行わなければ、 登録されている制御情報に影響は与えません。

setParameter(AutoPositioningParam) メソッドで登録した制御情報のパラメータは、 何らかの理由により変更されることがあります。 この場合、パラメータが変更された最新の制御情報のオブジェクトを返します。

制御情報が登録されていない場合は、null を返します。

戻り値:

この Star アプリから登録されている制御情報を返します。

例外:

SecurityException -
Star アプリ個別のユーザ設定により許可されない場合に発生します。

delete

public void delete()
            throws StoreException,
                   InterruptedOperationException

この Star アプリから登録されている制御情報を削除します。

このメソッドが呼び出されると、この Star アプリはサスペンドし、ユーザ確認のダイアログが表示されます。 ユーザが削除を許可した場合、この Star アプリから登録されている 制御情報が削除され、この Star アプリはレジュームします。 ユーザが削除をキャンセルした場合、この Star アプリはレジュームして例外が発生します。

この Star アプリから制御情報が登録されていない状態でこのメソッドを呼び出した場合、 この Star アプリはサスペンドせず何もしません。例外も発生しません。

例外:

StoreException -
(USER_ABORT)
ユーザ操作により、削除がキャンセルされた場合に発生します。

InterruptedOperationException -
競合条件などにより、選択操作が異常終了した場合に発生します。

deleteBySelection

public void deleteBySelection()
                       throws StoreException,
                              InterruptedOperationException

ユーザ操作により、Star アプリから登録されている制御情報を削除します。

このメソッドが呼び出されると、この Star アプリはサスペンドし、 削除対象を選択するためのネイティブのユーザインタフェースを表示します。 選択後、対象の制御情報は削除され、この Star アプリはレジュームします。 ユーザが選択操作をキャンセルした場合、この Star アプリはレジュームして例外が発生します。

制御情報を登録している Star アプリが一つも存在しない場合、 この Star アプリはサスペンドし、 削除対象が存在しない旨を表すネイティブのダイアログが表示されます。 ユーザ操作によりダイアログを閉じられると、 この Star アプリはレジュームします。

例外:

SecurityException -
Star アプリ個別のユーザ設定により許可されない場合に発生します。

StoreException -
(USER_ABORT)
ユーザが操作をキャンセルした場合に発生します。

InterruptedOperationException -
競合条件などにより、選択操作が異常終了した場合に発生します。