com.docomostar.device.felica
クラス Felica

Object
  com.docomostar.device.felica.Felica

public final class Felica

extends Object

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

FeliCa 機能を制御する基本クラスです。

このAPIでは、便宜上、FeliCa 機能の利用形態を

• オンラインアクセス
• オフラインアクセス
• (オフライン)フリーエリアアクセス
• 外部 R/W からのアクセス
• アドホック通信

に分類しており、open()を呼び出した後に、それぞれ

オンラインアクセスの場合:

getOnlineFelica()

オフラインアクセスの場合:

getOfflineFelica(int, int)

フリーエリアアクセスの場合:

getFreeArea()

アドホック通信の場合：

getAdhocDataTransfer()

を呼び出すことによって得られるオブジェクトを通じて、 目的とするアクセス・通信を実現することができます。 詳細は、それぞれのクラス・メソッドの説明を参照してください。
なお、外部 R/W からのアクセスを受け付けるために、 事前に何らかのメソッドを呼び出しておく必要はありません。 外部 R/W からは常にアクセスが可能です。 このためアプリケーション開発者は、 オンライン・オフライン・フリーエリアアクセスによるトランザクションと、 外部 R/W からのアクセスによるトランザクションを排他制御できないことに注意する必要があります。

FeliCa をオープンした状態で、発着信によりサスペンドした場合、 または、サスペンド中に発着信があった場合、 強制的に close() が呼ばれます。
ミニアプリ実行時の Selected 状態においては、上記に加えて、 FeliCa をオープンした状態で Widget View が非表示状態に遷移した場合にも、 強制的に close() が呼ばれます。 ミニアプリ実行時の Focused または Unfocused 状態においては、 FeliCa をオープンした状態でサスペンドした場合、 サスペンド理由に関わらず、強制的に close() が呼ばれます。

また、ネイティブのセキュリティ設定により FeliCa 機能がロックされている状態では、 FeliCa 機能を利用することはできません。 FeliCa をオープンした状態で、FeliCa 機能がロックされた場合は、 強制的に close() が呼ばれます。

アプリケーションが FeliCa IC チップの搬送波出力を開始している状態で、 発着信以外によりサスペンドした場合、 システムが強制的に搬送波を停止します。

導入されたバージョン:

Star-1.0

メソッドの概要

static boolean	canRegisterNodes() このアプリケーションに関係するノード(システム・エリア・サービス)のうち、 未登録ノード分の登録可否を調べます。
static void	close() FeliCa をクローズします。
static AdhocDataTransfer	getAdhocDataTransfer() アドホック通信用に AdhocDataTransfer オブジェクトを取得します。
static FreeArea	getFreeArea() フリーエリアアクセス用に、FreeAreaオブジェクトを取得します。
static int[]	getLockedNodeList() このアプリケーションに関係するノード(エリア・サービス)のうち、 遠隔個別領域停止中のノードリストを取得します。
static OfflineFelica	getOfflineFelica(int card, int systemCode) オフライン処理用に、OfflineFelicaオブジェクトを取得します。
static OnlineFelica	getOnlineFelica() オンライン処理用に、OnlineFelicaオブジェクトを取得します。
static void	open() FeliCa をオープンします。
static void	reset() FeliCa をリセットします。
static void	turnOffRFPower() 搬送波の出力を停止します。

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

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

メソッドの詳細

open

public static void open()
                 throws FelicaException

FeliCa をオープンします。 このメソッドを呼び出すと、デバイス (FeliCa IC チップ) に電源が供給されます。 既にオープンした状態で呼び出した場合には何も行いません。

このメソッドを呼び出した時に、 FeliCa IC チップが既に搬送波検出によって起動されている場合、 例外 FelicaException(ID_OPEN_ERROR, TYPE_UNDEFINED_ERROR) が発生します。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

IllegalStateException -
Bluetooth 通信中(一度でも Bluetooth.getInstance() 呼び出しが成功した後の状態)に呼び出された場合に発生します。

IllegalStateException -
UART 通信中 (Connector.open() によって UART 通信を行うコネクションをオブジェクトを取得し、 かつ、そのコネクションがクローズされていない状態) に呼び出された場合に発生します。

SecurityException -
ネイティブのセキュリティ設定により FeliCa 機能がロックされている場合に発生します。

FelicaException -
(ID_OPEN_ERROR, TYPE_UNDEFINED_ERROR)
外部R/Wから使用中など、FeliCaのオープンに失敗した場合に発生します。以下の場合にも発生します。

• 遠隔個別領域停止処理／解除処理実施中により、FeliCa のオープンに失敗した場合
• ミニアプリ実行時における以下の場合
• 他のミニアプリが既に FeliCa IC チップをオープン中の場合
• ADF に FeliCaCPID キー指定のある他のミニアプリがアプリ起動時の CPID チェック中である場合

close

public static void close()
                  throws FelicaException

FeliCa をクローズします。 このメソッドを呼び出すと、デバイス (FeliCa IC チップ) の電源が切断されます。 既に FeliCa がクローズされている場合や、 FeliCa がオープンされていない場合には何も行いません。 オンライン通信中である場合は、 サーバーに通知することなくデバイスの電源が切断されます。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

FelicaException -
(ID_CLOSE_ERROR, TYPE_UNDEFINED_ERROR)
FeliCaのクローズに失敗した場合に発生します。

getOnlineFelica

public static OnlineFelica getOnlineFelica()

オンライン処理用に、OnlineFelicaオブジェクトを取得します。 このメソッドを複数回呼び出しても、常に同じインスタンスが返ります。

なお、パーミッションとしてFeliCaオンライン機能の利用が許可されていない場合には、 このメソッドを呼び出した時点でセキュリティ違反として強制終了されます。

戻り値:

OnlineFelica オブジェクトを返します。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

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

getOfflineFelica

public static OfflineFelica getOfflineFelica(int card,
                                             int systemCode)
                                      throws FelicaException,
                                             java.io.IOException

オフライン処理用に、OfflineFelicaオブジェクトを取得します。 このメソッドを呼び出すと、 下記の設定にて、 指定されたカードに対してポーリングを行います。 同じカードの異なるシステムへの ポーリングに成功すると、そのカード内で システム切り替えが発生しPINの解除情報がクリアされます。

	内部カード	外部カード
タイムアウト値	500[ms]	250[ms]
リトライ数	0	0

このメソッドは、引数の組合せに関係なくポーリングを行います。 ポーリングの成功結果によって取得したIDmが、 それまでに取得したことのないIDmである場合は、新規にインスタンスを生成し返します。 既に取得済みのIDmである場合は、その時と同じインスタンスを返します。

処理対象カードについて:

処理対象カードにおいて、外部カードをサポートします。 引数 card に 外部カード(OfflineFelica.CARD_EXTERNAL)を指定可能です。

システムコードについて:

管理システムのシステムコードは指定できません。 処理対象カードが内部カードである場合には、 フリーエリアのシステムコードも指定できません。 従って、以下の場合には例外 IllegalArgumentException が発生します。 なお、処理対象カードが外部カードである場合には、 フリーエリアのシステムコードを指定することができます。

• 引数 systemCode に管理システムのシステムコードが指定された場合
• 引数 card に 内部カード が指定された場合に、 引数 systemCode にフリーエリアのシステムコードが指定された場合

パーミッションについて:

以下の場合には、このメソッドを呼び出した時点でセキュリティ違反として強制終了されます。

• パーミッションとしてFeliCaオフライン機能の利用、FeliCaリーダ／ライタ機能の利用のいずれも許可されていない場合
• 引数 card に 内部カード が指定された場合に、 パーミッションとしてFeliCaオフライン機能の利用が許可されていない場合
• 引数 card に 外部カード が指定された場合に、 パーミッションとしてFeliCaリーダ／ライタ機能の利用が許可されていない場合

パラメータ:

card - 処理対象カード (OfflineFelica.CARD_INTERNAL、 またはOfflineFelica.CARD_EXTERNAL)。

systemCode - システムコード。 0 以上 2¹⁶ - 1 以下の値が指定できます。

戻り値:

引数 card に 内部カード が指定された場合には OfflineFelica オブジェクトを、 外部カード が指定された場合には ThruRWOfflineFelica オブジェクトを返します。 ただし、引数 systemCode にワイルドカードが指定された場合、 以下の条件を満たしたときには null を返します。

• ポーリングの成功結果によって取得したシステムコードが管理システムのシステムコードである場合
• 引数 card に 内部カード が指定された場合に、 ポーリングの成功結果によって取得したシステムコードがフリーエリアのシステムコードである場合

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

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

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

IllegalArgumentException -
引数 card に不正な値 (上述の処理対象カード以外)が指定された場合に発生します。

IllegalArgumentException -
引数 systemCode に負の値、 または 2¹⁶ 以上の値が指定された場合に発生します。

IllegalArgumentException -
引数 systemCode に管理システムのシステムコードが指定された場合に発生します。

IllegalArgumentException -
引数 card に内部カードが指定された場合、かつ、 引数 systemCode にフリーエリアのシステムコードが指定された場合に発生します。

FelicaException -
(ID_POLLING_ERROR, TYPE_SELF_MODE)
(外部カードのみ) 端末がセルフモードの場合に発生します。

FelicaException -
(ID_POLLING_ERROR, TYPE_TIMEOUT_ERROR)
レスポンスタイムアウトにより、 ポーリングに失敗した場合に発生します。

FelicaException -
(ID_POLLING_ERROR, TYPE_FORMAT_ERROR)
レスポンスデータのフォーマットが正しくないことにより、 ポーリングに失敗した場合に発生します。

FelicaException -
(ID_POLLING_ERROR, TYPE_DEVICE_ERROR)
(外部カードのみ) 搬送波受信中のために、 ポーリングに失敗した場合に発生します。

FelicaException -
(ID_POLLING_ERROR, TYPE_UNEXPECTED_ERROR)
(外部カードのみ) 外部カードからのレスポンスデータの長さが上限を超えていたことにより、 ポーリングに失敗した場合に発生します。

FelicaException -
(ID_POLLING_ERROR, TYPE_UNDEFINED_ERROR)
ポーリングに失敗した場合に発生します。

java.io.InterruptedIOException -
FeliCaカードアクセス中に、 Suspended 状態への遷移によりカードアクセス処理が失敗した場合に発生します。

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

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

getFreeArea

public static FreeArea getFreeArea()

フリーエリアアクセス用に、FreeAreaオブジェクトを取得します。 このメソッドを複数回呼び出しても、常に同じインスタンスが返ります。

戻り値:

FreeArea オブジェクトを返します。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

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

SecurityException -
ADF にFeliCaCPIDキーの指定がないアプリケーションが、 このメソッドを呼び出した場合に発生します。

SecurityException -
ADF にFeliCaPINキーの指定がないアプリケーションが、 このメソッドを呼び出した場合に発生します。

getAdhocDataTransfer

public static AdhocDataTransfer getAdhocDataTransfer()

アドホック通信用に AdhocDataTransfer オブジェクトを取得します。 このメソッドを呼び出した時点では、外部カードに対しては何も行いません。

戻り値:

AdhocDataTransfer オブジェクトを返します。 常に同じオブジェクトへの参照を返します。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

IllegalStateException -
ミニアプリ実行時に呼び出された場合に発生します。

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

turnOffRFPower

public static void turnOffRFPower()
                           throws FelicaException,
                                  java.io.IOException

搬送波の出力を停止します。 搬送波の出力を停止すると、 無線通信速度が初期値(= 212kbps)に戻ります。

Star アプリが以下のメソッドを呼び出すと、 FeliCa IC チップは搬送波の出力を開始します。 FeliCa IC チップは搬送波の出力を開始すると、 明示的に停止するまでは出力を継続します。 搬送波の出力は消費電力が大きいため、 (搬送波の出力を必要とする)一連の処理が終わり次第、 適宜このメソッドを呼び出して下さい。

• Felica.getOfflineFelica(CARD_EXTERNAL, int)
• ThruRWOfflineFelica.checkPIN(CheckPINParameters)
• ThruRWOfflineFelica.executePIN(PINParameters)
• ThruRWOfflineFelica.read(ReadParameters)
• ThruRWOfflineFelica.write(WriteParameters)
• ThruRWOfflineFelica.getKeyVersion(int)
• ThruRWOfflineFelica.getContainerIssueInfo()
• ThruRWOfflineFelica.setParameter(long)
• ThruRWOfflineFelica.negotiateBaudRate(int)
• AdhocDataTransfer.setup(String, String, Hashtable)

なお、搬送波の出力は、 以下の条件によっても停止します。

• 発着信以外によりアプリケーションがサスペンドする
• FeliCa IC チップをリセットする
• FeliCa IC チップの電源を再投入する

なお、FeliCa IC チップは、搬送波を出力している間は、 外部 R/W からのアクセスを受け付けられない可能性があることに注意してください。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

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

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

FelicaException -
(ID_TURNOFF_RFPOWER_ERROR, TYPE_TIMEOUT_ERROR)
レスポンスタイムアウトにより、 搬送波停止に失敗した場合に発生します。

FelicaException -
(ID_TURNOFF_RFPOWER_ERROR, TYPE_FORMAT_ERROR)
レスポンスデータのフォーマットが正しくないことにより、 搬送波停止に失敗した場合に発生します。

FelicaException -
(ID_TURNOFF_RFPOWER, TYPE_DEVICE_ERROR)
ハードウェア要因により、 搬送波停止に失敗した場合に発生します。

FelicaException -
(ID_TURNOFF_RFPOWER_ERROR, TYPE_UNDEFINED_ERROR)
搬送波停止に失敗した場合に発生します。

java.io.InterruptedIOException -
FeliCaカードアクセス中に、 Suspended 状態への遷移によりカードアクセス処理が失敗した場合に発生します。

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

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

reset

public static void reset()
                  throws FelicaException,
                         java.io.IOException

FeliCa をリセットします。 このメソッドは、デバイス(FeliCa IC チップ)に対してソフトウェアリセットを行います。

なお、FeliCa IC チップは、 リセットによって以下のことが起こります。

• PINの解除情報がクリアされる
• 搬送波の出力が停止する(無線通信速度が初期値に戻る)
• コマンドパケットで使用する属性の設定値が初期値に戻る

このメソッドは、FeliCa IC チップからのリセット処理完了通知を待ってからリターンします。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

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

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

FelicaException -
(ID_RESET_ERROR, TYPE_TIMEOUT_ERROR)
レスポンスタイムアウトにより、 リセットに失敗した場合に発生します。

FelicaException -
(ID_RESET_ERROR, TYPE_FORMAT_ERROR)
レスポンスデータのフォーマットが正しくないことにより、 リセットに失敗した場合に発生します。

FelicaException -
(ID_RESET_ERROR, TYPE_UNDEFINED_ERROR)
リセットに失敗した場合に発生します。

java.io.InterruptedIOException -
FeliCaカードアクセス中に、 Suspended 状態への遷移によりカードアクセス処理が失敗した場合に発生します。

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

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

getLockedNodeList

public static int[] getLockedNodeList()
                               throws FelicaException

このアプリケーションに関係するノード(エリア・サービス)のうち、 遠隔個別領域停止中のノードリストを取得します。

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

なお、パーミッションとして 遠隔個別領域停止状態の取得が許可されていない場合には、 このメソッドを呼び出した時点でセキュリティ違反として強制終了されます。

戻り値:

遠隔個別領域停止中のノードのリストを、 システムコードとノードコードのペアの配列として返します。 遠隔個別領域停止中のノードが N 個 [N:1,2,3,…] 存在する場合、 返される配列の長さは (N * 2) になります。 この場合 n 個目 [n:1,2,…,N] のノードについて、 そのシステムコードは配列の (n * 2 - 2) 番目の要素に、 そのノードコードは配列の (n * 2 - 1) 番目の要素に、 それぞれ格納されています。 遠隔個別領域停止中のノードが存在しない場合には、 長さ 0 の配列を返します。 返される配列は、 このクラスが内部で保持している配列のコピーです。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

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

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

FelicaException -
(ID_LOCKED_NODELIST_ERROR, TYPE_UNDEFINED_ERROR)
遠隔個別領域停止中のノードリストの取得に失敗した場合に発生します。

canRegisterNodes

public static boolean canRegisterNodes()
                                throws FelicaException

このアプリケーションに関係するノード(システム・エリア・サービス)のうち、 未登録ノード分の登録可否を調べます。 このメソッドは、 このアプリケーションに関係する未登録ノード分について、 登録に必要な空きブロックが FeliCa IC チップ内に存在するか否かを調べます。

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

なお、 エリア・サービスを発券するICアプリとしてiモードサーバーに登録されていないiアプリが このメソッドを呼び出した時点でセキュリティ違反として強制終了されます。

戻り値:

登録できる(空きブロックが存在する)場合には true を、 登録できない(空きブロックが存在しない)場合には false を返します。 なお、このアプリケーションに関連するノードが全て登録済みである場合には false を返します。

例外:

UnsupportedOperationException -
FeliCa機能をサポートしていない場合に発生します。

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

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

FelicaException -
(ID_CANREGISTER_NODES_ERROR, TYPE_NONEXISTENT_SYSTEM_ERROR)
そのICアプリがエリア・サービスを発券する対象のシステムが、 内部カードに存在しない場合に発生します。 なお、フルアプリ実行時にはこの例外が発生することはありません。

FelicaException -
(ID_CANREGISTER_NODES_ERROR, TYPE_SYSTEM_SIZE_SHORTAGE_ERROR)
そのICアプリが分割するシステム、および、発券するエリアの合計サイズが 内部カード内のシステムサイズを超えている場合に発生します。 なお、フルアプリ実行時にはこの例外が発生することはありません。

FelicaException -
(ID_CANREGISTER_NODES_ERROR, TYPE_UNDEFINED_ERROR)
未登録ノード分の登録可否の調査に失敗した場合に発生します。