com.nttdocomo.device.felica
クラス Felica

Object
  com.nttdocomo.device.felica.Felica

public final class Felica

extends Object

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

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

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

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

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

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

getOnlineFelica()

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

getOfflineFelica(int, int)

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

getFreeArea()

を呼び出すことによって得られるオブジェクトを通じて、 目的とするアクセスを実現することができます。 外部 R/W からのアクセスについては専用のクラスは用意されていません。 このクラスに用意されている activate() や inactivate() を利用します。 詳細は、それぞれのクラス・メソッドの説明を参照してください。

FeliCa をオープンした状態で、音声・テレビ電話発着信によりサスペンドした場合、または、 サスペンド中に音声・テレビ電話着信があった場合、強制的に close() が呼ばれます。

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

なお、待ち受け実行時の非活性化状態では FeliCa にアクセスすることは出来ません。 活性化状態から非活性化状態に切り替えた場合には、 強制的に close() が呼ばれます。 また、ダウンロード即起動アプリからも FeliCa にアクセスすることは出来ません。

導入されたバージョン:

DoJa-3.0 (506iC)、DoJa-3.5 (900iC)

メソッドの概要

static void	activate() 外部 R/W からのアクセスを待つ状態にします。
static void	close() FeliCa をクローズします。
static FreeArea	getFreeArea() フリーエリアアクセス用に、FreeAreaオブジェクトを取得します。
static OfflineFelica	getOfflineFelica(int card, int systemCode) オフライン処理用に、OfflineFelicaオブジェクトを取得します。
static OnlineFelica	getOnlineFelica() オンライン処理用に、OnlineFelicaオブジェクトを取得します。
static void	inactivate() 外部 R/W からのアクセス待ち状態を解除します。
static void	open() FeliCaカードにアクセスするためのデバイスをオープンします。

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

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

メソッドの詳細

open

public static void open()
                 throws FelicaException

FeliCaカードにアクセスするためのデバイスをオープンします。 既にオープンした状態で呼び出した場合には何も行いません。

例外:

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

IllegalStateException - ダウンロード即起動アプリで呼び出された場合に発生します。

IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。

SecurityException - FeliCaオンライン機能の利用、 FeliCaオフライン機能の利用の、いずれの利用も許可されておらず、かつ、 ADF の FeliCaCPID キー、 ADF の FeliCaPIN キーの、いずれも指定されていない場合に発生します。

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

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

close

public static void close()
                  throws FelicaException

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

例外:

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

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

getOnlineFelica

public static OnlineFelica getOnlineFelica()

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

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

戻り値:

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

例外:

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

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

getOfflineFelica

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

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

タイムアウト値	500[ms]
リトライ数	0

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

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

[DoJa-3.0 (506iC) 以降 ただし、DoJa-3.5 (900i) を除く]
処理対象カードにおいて、外部カードは未サポートです。 引数 card に 外部カード(OfflineFelica.CARD_EXTERNAL)が指定された場合には、 例外 UnsupportedOperationException が発生します。

パラメータ:

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

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

戻り値:

OfflineFelica オブジェクトを返します。 引数 systemCode にワイルドカードが指定された場合、 ポーリングの成功結果によって取得したシステムコードが、 フリーエリアのシステムコードである場合は null を返します。

例外:

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

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

DeviceException - オンライン処理が既に開始されている場合や、 外部 R/W からのアクセス待ち状態下の場合に発生します(ILLEGAL_STATE)。

UnsupportedOperationException - [DoJa-3.0 (506iC) 以降 ただし、DoJa-3.5 (900i) を除く] 引数 card に外部カードが指定された場合に発生します。

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

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

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

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

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

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

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

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

getFreeArea

public static FreeArea getFreeArea()

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

戻り値:

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

例外:

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

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

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

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

activate

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

外部 R/W からのアクセスを待つ状態にします。 このメソッドは即座にリターンします。

アプリケーションは、このメソッドを呼び出してから、 inactivate()、あるいは close() が呼ばれるまでの間は 外部 R/W からのアクセス待ち状態 となります。 外部 R/W からのアクセス待ち状態下においては、 オンライン処理中に呼び出すと例外が発生するようなメソッドは、 一切呼び出すことはできません。 別の FeliCa 通信を行うには、 外部 R/W からのアクセス待ち状態を解除するか、 一旦 FeliCa をクローズして、再度オープンするようにして下さい。

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

例外:

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

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

DeviceException - オンライン処理が既に開始されている場合や、 外部 R/W からのアクセス待ち状態下の場合に発生します(ILLEGAL_STATE)。

FelicaException - レスポンスタイムアウトにより、外部 R/W からのアクセス待ち状態への遷移に失敗した場合に発生します (ID_ACTIVATE_ERROR, TYPE_TIMEOUT_ERROR)。

FelicaException - レスポンスデータのフォーマットが正しくないことにより、 外部 R/W からのアクセス待ち状態への遷移に失敗した場合に発生します (ID_ACTIVATE_ERROR, TYPE_FORMAT_ERROR)。

FelicaException - 外部R/Wからのアクセス待ち状態への遷移に失敗した場合に発生します (ID_ACTIVATE_ERROR, TYPE_UNDEFINED_ERROR)。

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

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

inactivate

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

外部 R/W からのアクセス待ち状態を解除します。 外部 R/W からのトランザクションが終了していない場合は、 IOException が発生します。 activate()を行っていない場合には何も行いません。

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

例外:

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

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

FelicaException - レスポンスタイムアウトにより、外部 R/W からのアクセス 待ち状態の解除に失敗した場合に発生します (ID_INACTIVATE_ERROR, TYPE_TIMEOUT_ERROR)。

FelicaException - レスポンスデータのフォーマットが正しくないことにより、 外部 R/W からのアクセス待ち状態の解除に失敗した場合に発生します (ID_INACTIVATE_ERROR, TYPE_FORMAT_ERROR)。

FelicaException - 外部 R/W からのアクセス待ち状態の解除に失敗した場合に発生します (ID_INACTIVATE_ERROR, TYPE_UNDEFINED_ERROR)。

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

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