com.nttdocomo.device.felica
インタフェース FelicaAdhocListener

すべてのスーパーインタフェース:

EventListener

public interface FelicaAdhocListener

extends EventListener

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

アドホック通信による連続データ転送に関するイベントのリスナを定義します。 アドホック通信による連続データ転送において、サーバとして振る舞うためには、 このリスナを実装する必要があります。

クライアント側からの AdhocDataTransfer.setup(String adfURL, String command, Hashtable params) 呼び出しにより、 この端末のこのアプリケーションが通信相手として指定された場合、 その時点でこのアプリケーションが実行中か否かにかかわらず、 このリスナが呼び出されます。

このアプリケーションが実行中である場合には即座にこのリスナが呼び出されます。 このアプリケーションが実行中でない場合には、 自動的にこのアプリケーションが起動し、 ADF の AppClass で指定された IApplication のサブクラスがインスタンス化され、コンストラクタの処理が完了した後に、 このリスナが呼び出されます。

なお、システムによってこのリスナが呼び出される際には、 以下のような処理が行われます。 ここで、main は IApplication.getCurrentApp() の戻り値を、 params は、クライアント側から渡された Hashtable 型の引数を、それぞれ表します。

1. main がこのインタフェースを実装しているかを検査する。
   • main がこのインタフェースを実装していない場合、 即座にクライアント側にデータ転送要求を拒否する旨通知し、 リスナの呼び出し処理を終了する。
   • main がこのインタフェースを実装している場合、 ((FelicaAdhocListener)main).requestReceived(params) が呼び出される。
2. ((FelicaAdhocListener)main).requestReceived(params) を呼び出した時の戻り値が true である場合はデータ転送要求承諾の旨を、 false である場合や戻り値が無かった (例外が発生した) 場合にはデータ転送要求を拒否する旨を、それぞれクライアント側に通知する。

上記処理からも分かるように、このインタフェースは ADF の AppClass キーによって指定されている IApplication クラスのサブクラスにて実装しなければなりません。 IApplication クラスのサブクラスがこのインタフェースを実装している場合のみ、 システムはこのインタフェースに定義されているメソッドを呼び出すことができます。 IApplication クラスのサブクラス以外がこのインタフェースを実装しても、 システムはこのインタフェースに定義されているメソッドを呼び出すことができないことに注意してください。

加えて、データ転送要求を受け取った時点で、 以下の条件のいずれかを満たす場合は、アドホック通信を実施できないため、 このリスナは呼び出されずに、 クライアント側にはデータ転送要求を拒否する旨が通知されます。

• 既に FeliCa がオープン中の場合
• このアプリケーションが、ダウンロード即起動アプリケーションである場合
• 赤外線 OBEX 通信中の場合
• 赤外線 OBEX 通信が開始できないような状況下の場合 (アドホック通信による OBEX 通信は、 赤外線による OBEX 通信と同等の扱いとなっています)
  • 端末がセルフモードの場合
  • 動画再生中の場合
  • 音声・テレビ電話通話中の場合
  • 赤外線リモコンが通信中の場合
  • バックグラウンドで動作しているネイティブ機能がパケット通信中の場合
  • PTT 呼通信中、PTT 設定中の場合

導入されたバージョン:

DoJa-5.0 (903i)

メソッドの概要

boolean

requestReceived(java.util.Hashtable receivedParams) アドホック通信による連続データ転送において、 クライアント側より、 データ転送先のアプリケーションとして呼び出された場合にコールされます。

メソッドの詳細

requestReceived

public boolean requestReceived(java.util.Hashtable receivedParams)

アドホック通信による連続データ転送において、 クライアント側より、 データ転送先のアプリケーションとして呼び出された場合にコールされます。

クライアント側が、 このアプリケーションがインストールされている端末に対して AdhocDataTransfer.setup(String adfURL, String command, Hashtable params) を呼び出すことで、このメソッドがコールされますが、 このメソッドの引数 receivedParams には、 上記メソッドの引数 params で指定された値がそのまま設定されています。 呼び出され方の詳細については、このインタフェースの説明も参照して下さい。

このアプリケーションが、データ転送要求を受けて起動した場合には、 このメソッドから参照可能な変数は、 起動時にインスタンス化される IApplication のサブクラスのコンストラクタ呼び出しが完了した時点でアクセス可能なものに限られます。

このメソッドの実装者は、 クライアント側からのデータ転送要求を受け入れたい場合は、 このリスナが呼び出されたら、即座に true をリターンし、 速やかに FelicaServerObexConnection.accept() を呼び出さなければなりません。 特に、true をリターンしてはじめて、クライアント側が FelicaClientObexConnection.connect() を呼び出すため、 以下のようなコードを書くとデッドロックすることに注意して下さい。

 public boolean requestReceived(Hashtable receivedParams) {
     FelicaServerObexConnection con = 
         (FelicaServerObexConnection)Connector.open("obex:/felicaserver");
     con.accept(); // connect() されるまでブロックする
     return true; // true をリターンしないと対向側は connect() してこない
 }

なお、OBEX クライアント側の connect() は、 accept() が呼び出されるまでブロックするため、 connect() と accept() の順番は、 どちらが先になっても構いません。 従って、典型的には、このリスナの実装は以下のようになります。

 public boolean requestReceived(Hashtable receivedParams) {
     // 非同期に通信コード(accept() を含む)を呼び出す
     (new Thread() {
             public void run() {
                 doCommunicate();
             } 
        }).start();
     // true を返して、相手側からの connect() を待つ
     return true;
 }

 private void doCommunicate() {
     FelicaServerObexConnection con = 
         (FelicaServerObexConnection)Connector.open("obex:/felicaserver");
     con.accept();
     // 以下、クライアントとの通信コード
 }

一方、クライアント側からのデータ転送要求を拒否したい場合には、 単純に false をリターンして下さい。

このメソッド実行中にキャッチされない例外が発生した場合には、 要求を拒否したものとして扱われます。

パラメータ:

receivedParams - クライアント側からの、 データ転送リクエストに付随したパラメータが設定されています。 クライアント側からパラメータが設定されなかった(setup() 呼び出し時にサイズ 0 の Hashtable、または null が指定されていた)場合には null が設定されています。

戻り値:

このデータ転送リクエストを承諾する場合には true を、 拒否する場合には false を、それぞれ返します。