com.docomostar.device.felica
クラス AdhocDataTransfer

Object
  com.docomostar.device.felica.AdhocDataTransfer

public final class AdhocDataTransfer
extends Object

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

アドホック通信による連続データ転送機能を制御するクラスです。

アドホック通信による連続データ転送において、サーバとして振る舞うためには、 FelicaAdhocEvent.getAdhocDataTransfer() 呼び出しによってこのオブジェクトを取得し、 reply(int) によって、クライアント側に、 データ転送要求を受け入れるかどうかを通知しなければなりません。 この場合、reply(int) 以外のメソッドを呼び出すと例外が発生します。

アドホック通信による連続データ転送において、 クライアントとして振る舞うためには、 最初に setup(String, String, Hashtable) を呼び出す必要があります。 setup() が正常にリターンした時点で、 サーバとのアドホック通信のリンクが確立されています。

リンク確立後は Connector.open("obex:/felicaclient") 呼び出しにより FelicaClientObexConnection オブジェクトを取得し、 OBEX によりデータの送受信を行ってください。 なお、アドホック通信におけるクライアント側が Connector.open("obex:/felicaserver") を呼び出すと例外が発生します。

クライアント側が通信を終了する場合には、 以下の手順を踏んで下さい。

1. FelicaClientObexConnection.close() 呼び出しにより OBEX 通信を終了させる
2. terminateAdhoc() 呼び出しにより、アドホック通信を終了させる
3. Felica.turnOffRFPower() により、搬送波の出力を停止する

導入されたバージョン:

Star-1.0

フィールドの概要

static int	REPLY_ACCEPT クライアント側からのデータ転送要求を受け入れることを表します(=0)。
static int	REPLY_REJECT クライアント側からのデータ転送要求を拒否することを表します(=1)。

メソッドの概要

int	getAdhocState() アドホック通信機能の現在の状態(アドホックモード)を取得します。
byte[]	getIDm() このオブジェクトがアクセス先として保持している IDm を返します。
void	reply(int value) クライアント側からの、 アドホック通信によるデータ転送要求について、 受け入れるか否かを通知します。
void	setup(String adfURL, String command, java.util.Hashtable params) アドホック通信による連続データ転送先とのリンクを確立します。
void	terminateAdhoc() アドホック通信による連続データ転送を終了し、 リンクを切断します。

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

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

フィールドの詳細

REPLY_ACCEPT

public static final int REPLY_ACCEPT

クライアント側からのデータ転送要求を受け入れることを表します(=0)。

関連項目:

reply(int), 定数フィールド値

REPLY_REJECT

public static final int REPLY_REJECT

クライアント側からのデータ転送要求を拒否することを表します(=1)。

関連項目:

reply(int), 定数フィールド値

メソッドの詳細

setup

public void setup(String adfURL,
                  String command,
                  java.util.Hashtable params)
           throws java.io.IOException

アドホック通信による連続データ転送先とのリンクを確立します。

このメソッドを呼び出すと、 ユーザに連続データ転送を開始して良いかを確認するダイアログを表示します。 ユーザがデータ転送の開始を承諾すると、 この端末を転送先のデバイスに近付けるよう促すダイアログを表示します。 ユーザが端末を近付けると、リンクが確立され、 引数 adfURL で指定された転送先アプリケーションに対して、 データ転送の受け入れ可否を問い合わせます。 転送先アプリケーションがデータ転送の受け入れを承諾すると、 このメソッドは正常にリターンします。

リンクが確立されると、 リンク先のカードのIDmが取得できるようになります。 なお、ここでユーザがデータ転送の開始を承諾してから、 データ転送が終了するまでは、 端末を転送先のデバイスに近付け続けている必要があります。 途中でデバイスを遠ざけると、リンクが切断されますので注意して下さい。

ユーザがデータ転送の開始を拒否した場合や、 転送先アプリケーションがデータ転送の受け入れを拒否した場合も含めて、 結果としてリンクが確立できなかった場合には例外が発生します。

このメソッド呼び出しの過程で、 通信先の外部カードとの間で、無線通信速度のネゴシエーションを行います。 その結果、ThruRWOfflineFelica.negotiateBaudRate(int) で設定した通信速度が変更されている可能性がありますので注意してください。 このメソッド呼び出しで例外が発生した場合でも同様です。

引数 params を用いて、 転送先アプリケーション側に起動パラメータを渡すことができます。 転送先アプリケーションは、 params で指定した値が、 FelicaAdhocEvent.getReceivedParameter() の戻り値として取得できます。

引数 params には、キーと値 (どちらも String 型) の組を複数個格納したハッシュテーブルを指定できますが、 下記の制限があります。

• 格納するキーと値は、全て「空白を除く ASCII 図形文字」 (\u0021〜\u007E) で構成されていなければなりません。
• 格納するキーと値は、合計で255バイト以下でなければなりません。

パラメータ:

adfURL - 転送先アプリケーションの ADF の URL を指定します。 これによって転送先のアプリケーションを特定します。

command - 転送先アプリケーションへ通知する起動コマンドを指定します。

params - 転送先アプリケーションへ通知する、起動パラメータ を格納したハッシュテーブルを指定します。 起動パラメータそのものが不要な場合には null を指定します。

例外:

IllegalStateException -
このオブジェクトが、 システムによって生成された FelicaAdhocEvent インスタンスに対する FelicaAdhocEvent.getAdhocDataTransfer() 呼び出しによって得られたものである場合に発生します。

DeviceException -
(ILLEGAL_STATE)
FeliCa がオープンされていない場合に発生します。

DeviceException -
(ILLEGAL_STATE)
オンライン処理が既に開始されている場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
既に setup() 実行中の別スレッドが存在する場合に発生します。

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

IllegalArgumentException -
引数 adfURL の長さが 255 バイトを超える場合に発生します。

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

IllegalArgumentException -
引数 command が空文字列か、 255文字を超える場合に発生します。

IllegalArgumentException -
引数 command に 「空白を含む ASCII 図形文字(\0020〜\007E)」 以外の文字が含まれている場合に発生します。

ClassCastException -
引数 params のキーや値に、 String 型以外のオブジェクトが含まれていた場合に発生します。

IllegalArgumentException -
引数 params のキーや値に 「空白を除く ASCII 図形文字(\0021〜\007E)」 以外の文字が含まれている場合に発生します。

IllegalArgumentException -
引数 params のキーや値の文字数の合計が、 255 文字を超えている場合に発生します。

IllegalArgumentException -
引数 params にシステムが提供している以外のオブジェクト (Hashtable クラスを継承した未知のクラスのオブジェクト) が渡された場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
既にリンクが確立されている場合に発生します。

ConnectionException -
(SELF_MODE)
端末がセルフモードの場合に発生します。

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

DeviceException -
(RACE_CONDITION)
赤外線を用いた OBEX 通信中や、 赤外線リモコン通信中である場合に発生します。

ConnectionException -
(BUSY_RESOURCE)
バックグラウンドで動作しているネイティブ機能が、 パケット通信中の場合に発生します。以下の場合も含まれます。

• ミュージックチャネルダウンローダが起動中の場合
• ソフトウェア更新のダウンロード通知機能が起動中の場合
• [Star-1.1 まで] PTT 設定中の場合

ConnectionException -
(BUSY_RESOURCE)
音声・テレビ電話通話中に呼び出された場合に発生します。

ConnectionException -
(TIMEOUT)
タイムアウトによりリンク確立が失敗した場合に発生します。 ユーザがデータ転送の開始を承諾してから一定時間内に転送先のデバイスに近付けなかった場合、 転送先のデバイスがアドホック通信による連続データ転送機能をサポートしていなかったために応答が無かった場合や、 転送先デバイスが FeliCa ロック中であるために応答が無かった場合も含まれます。

ConnectionException -
(USER_ABORT)
ユーザがデータ転送の開始を拒否した場合や、 一旦開始を許可した後に中断した場合に発生します。

java.io.InterruptedIOException -
別スレッドやシステムからの Felica.close()・terminateAdhoc() 呼び出しにより、 通信が中断された場合に発生します。

ConnectionRefusedException -
(APPLICATION_NOT_EXIST)
転送先として指定したアプリケーションが存在していないため、 リンク確立を拒否された場合に発生します。

ConnectionRefusedException -
(BUSY_RESOURCE)
転送先デバイスで他のアプリケーションが起動しているため、 転送先として指定したアプリケーションが起動できない場合に発生します。

ConnectionRefusedException -
(REFUSED_BY_USER_SETTING)
転送先として指定したアプリケーションの自動起動が許可されていない場合に発生します。

ConnectionRefusedException -
(REFUSED_BY_ADF_SETTING)
転送先として指定したアプリケーションの ADF において、 AllowPushBy キーが定義されていなかったり、 起動コマンドが不一致である場合に発生します。

ConnectionRefusedException -
(REFUSED_BY_APPLICATION)
転送先として指定したアプリケーションによって、 データ転送受け入れを拒否された場合 (reply(ACCEPT_REJECT) が呼び出された場合) に発生します。

ConnectionRefusedException -
(RACE_CONDITION)
転送先として指定したアプリケーションが競合状態にあるため、 接続要求を受け入れられない場合に発生します。

ConnectionRefusedException -
(UNDEFINED)
転送先として指定したアプリケーションが、 上記以外の理由によってデータ転送を受け入れられない場合に発生します。

java.io.IOException -
上記以外の I/O エラーが発生した場合に発生します。 アドホック通信リンクプロトコル以下のレイヤで、 上記以外のエラーが発生した場合も含みます。

terminateAdhoc

public void terminateAdhoc()
                    throws java.io.IOException

アドホック通信による連続データ転送を終了し、 リンクを切断します。 既にリンクが切断されている場合には何もしません。

このメソッドを呼び出すと、 このオブジェクトが保持している IDm を破棄(初期化)します。

例外:

IllegalStateException -
このオブジェクトが、 システムによって生成された FelicaAdhocEvent インスタンスに対する FelicaAdhocEvent.getAdhocDataTransfer() 呼び出しによって得られたものである場合に発生します。

PortBusyException -
ポートビジーエラーが発生した場合に発生します。

java.io.IOException -
入出力エラーが発生した場合に発生します。

getAdhocState

public int getAdhocState()
                  throws FelicaException,
                         java.io.IOException

アドホック通信機能の現在の状態(アドホックモード)を取得します。 アドホックモードの取得対象は内部カードです。

このメソッドの戻り値の意味は以下の通りです。

戻り値	意味
0x00	アドホックモード 0
0x01	アドホックモード 1

このメソッドを呼び出すと、 内部カードに対してアクセスする可能性があります。 このため、内部カード内でシステム切り替えが発生し PIN の解除情報がクリアされる可能性があります。

戻り値:

アドホックモードを返します。

例外:

IllegalStateException -
このオブジェクトが、 システムによって生成された FelicaAdhocEvent インスタンスに対する FelicaAdhocEvent.getAdhocDataTransfer() 呼び出しによって得られたものである場合に発生します。

DeviceException -
(ILLEGAL_STATE)
FeliCa がオープンされていない場合に発生します。

DeviceException -
(ILLEGAL_STATE)
オンライン処理が既に開始されている場合に発生します。

FelicaException

萓句､