com.nttdocomo.device.felica
クラス Felica

Object
  拡張com.nttdocomo.device.felica.Felica

public final class Felica
extends Object
 [iアプリオプションAPI]

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

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

に分類しており、open()を呼び出した後に、それぞれ
オンラインアクセスの場合:
getOnlineFelica()
オフラインアクセスの場合:
getOfflineFelica(int, int)
フリーエリアアクセスの場合:
getFreeArea()
アドホック通信の場合:
getAdhocDataTransfer()
を呼び出すことによって得られるオブジェクトを通じて、 目的とするアクセス・通信を実現することができます。 詳細は、それぞれのクラス・メソッドの説明を参照してください。
[DoJa-4.1 (902iS) まで] 外部 R/W からのアクセスについては専用のクラスは用意されていません。 このクラスに用意されている activate()inactivate() を利用します。
[DoJa-5.0 (903i) 以降] このクラスの activate()inactivate() を利用しなくても外部 R/W からのアクセスが可能です。 このためアプリケーション開発者は、 オンライン・オフライン・フリーエリアアクセスによるトランザクションと、 外部 R/W からのアクセスによるトランザクションを排他制御できないことに注意する必要があります。

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

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

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

[DoJa-5.0 (903i) 以降]
アプリケーションが FeliCa IC チップの搬送波出力を開始している状態で、 音声・テレビ電話・PTT 呼発着信以外によりサスペンドした場合、 システムが強制的に搬送波を停止します。

導入されたバージョン:
DoJa-3.0 (506iC)、DoJa-3.5 (900iC)

メソッドの概要
static void activate()
          推奨されていません。  DoJa-5.0 (903i) 以降では、 このメソッドを呼び出さなくても外部 R/W からのアクセスを受け付けることができるため、 このメソッドはサポートされません。
static void close()
          FeliCa をクローズします。
static AdhocDataTransfer getAdhocDataTransfer()
           アドホック通信用に AdhocDataTransfer オブジェクトを取得します。
static FreeArea getFreeArea()
          フリーエリアアクセス用に、FreeAreaオブジェクトを取得します。
static OfflineFelica getOfflineFelica(int card, int systemCode)
           オフライン処理用に、OfflineFelicaオブジェクトを取得します。
static OnlineFelica getOnlineFelica()
           オンライン処理用に、OnlineFelicaオブジェクトを取得します。
static void inactivate()
          推奨されていません。  DoJa-5.0 (903i) 以降では、 activate()メソッドを呼び出さなくても外部 R/W からのアクセスを受け付けることができるため、 このメソッドはサポートされません。
static void open()
          FeliCa をオープンします。
static void reset()
          FeliCa をリセットします。
static void setFelicaPushListener(FelicaPushListener listener)
          外部 R/W から Push 通知を受信した際のイベントを受け取るリスナを登録します。
static void turnOffRFPower()
          搬送波の出力を停止します。
 
クラス Object から継承したメソッド
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

メソッドの詳細

open

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

[DoJa-4.1 (902iS) まで]
パーミッションとしてFeliCaオンライン機能の利用、FeliCaオフライン機能の利用の、いずれも許可されておらず、かつ、 ADF の FeliCaCPID キー、ADF の FeliCaPIN キーの いずれも指定されていない場合には、 このメソッドを呼び出した時点で例外が発生します。
[DoJa-5.0 (903i) 以降]
パーミッションとして上記が許可されている必要や、ADF キーが指定されている必要はありません。

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

例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
IllegalStateException - ダウンロード即起動アプリで呼び出された場合に発生します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
IllegalStateException - [DoJa-5.0 (903i) 以降] Bluetooth 通信中(一度でも Bluetooth.getInstance() 呼び出しが成功した後の状態)に呼び出された場合に発生します。
IllegalStateException - [DoJa-5.0 (903i) 以降] UART 通信中 (Connector.open() によって UART 通信を行うコネクションをオブジェクトを取得し、 かつ、そのコネクションがクローズされていない状態) に呼び出された場合に発生します。
SecurityException - [DoJa-4.1 (902iS) まで] パーミッションとして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 IC チップ) の電源が切断されます。 既に 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] 250[ms]
リトライ数0 0

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

処理対象カードについて:
[DoJa-4.1 (902iS) まで]
処理対象カードにおいて、外部カードは未サポートです。 引数 card に 外部カード(OfflineFelica.CARD_EXTERNAL)が指定された場合には、 例外 UnsupportedOperationException が発生します。
[DoJa-5.0 (903i) 以降]
処理対象カードにおいて、外部カードをサポートします。 引数 card に 外部カード(OfflineFelica.CARD_EXTERNAL)を指定可能です。
システムコードについて:
[DoJa-4.1 (902iS) まで]
フリーエリアのシステムコードは指定できません。 引数 systemCode にフリーエリアのシステムコードが指定された場合には、 例外 IllegalArgumentException が発生します。
[DoJa-5.0 (903i) 以降]
管理システムのシステムコードは指定できません。 処理対象カードが内部カードである場合には、 フリーエリアのシステムコードも指定できません。 従って、以下の場合には例外 IllegalArgumentException が発生します。 なお、処理対象カードが外部カードである場合には、 フリーエリアのシステムコードを指定することができます。
  • 引数 systemCode に管理システムのシステムコードが指定された場合
  • 引数 card に 内部カード が指定された場合に、 引数 systemCode にフリーエリアのシステムコードが指定された場合
パーミッションについて:
[DoJa-4.1 (902iS) まで]
パーミッションとしてFeliCaオフライン機能の利用が許可されていない場合には、 このメソッドを呼び出した時点でセキュリティ違反として強制終了されます。
[DoJa-5.0 (903i) 以降]
以下の場合には、このメソッドを呼び出した時点でセキュリティ違反として強制終了されます。
  • パーミッションとしてFeliCaオフライン機能の利用、FeliCaリーダ/ライタ機能の利用の、いずれも許可されていない場合
  • 引数 card に 内部カード が指定された場合に、 パーミッションとしてFeliCaオフライン機能の利用が許可されていない場合
  • 引数 card に 外部カード が指定された場合に、 パーミッションとしてFeliCaリーダ/ライタ機能の利用が許可されていない場合

パラメータ:
card - 処理対象カード (OfflineFelica.CARD_INTERNAL、 またはOfflineFelica.CARD_EXTERNAL)。
systemCode - システムコード。 0 以上 216 - 1 以下の値が指定できます。
戻り値:
[DoJa-4.1 (902iS) まで]
OfflineFelica オブジェクトを返します。 引数 systemCode にワイルドカードが指定された場合、 ポーリングの成功結果によって取得したシステムコードが、 フリーエリアのシステムコードである場合は null を返します。
[DoJa-5.0 (903i) 以降]
引数 card に 内部カード が指定された場合には OfflineFelica オブジェクトを、 外部カード が指定された場合には ThruRWOfflineFelica オブジェクトを返します。 ただし、引数 systemCode にワイルドカードが指定された場合、 以下の条件を満たしたときには null を返します。
  • ポーリングの成功結果によって取得したシステムコードが管理システムのシステムコードである場合
  • 引数 card に 内部カード が指定された場合に、 ポーリングの成功結果によって取得したシステムコードがフリーエリアのシステムコードである場合
例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
DeviceException - FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
DeviceException - [DoJa-4.1 (902iS) まで] オンライン処理が既に開始されている場合や、 外部 R/W からのアクセス待ち状態下の場合に発生します(ILLEGAL_STATE)。
DeviceException - [DoJa-5.0 (903i) 以降] オンライン処理が既に開始されている場合に発生します(ILLEGAL_STATE)。
UnsupportedOperationException - [DoJa-4.1 (902iS) まで] 引数 card に外部カードが指定された場合に発生します。
IllegalArgumentException - 引数 card に不正な値(上述の処理対象カード以外)が指定された場合に発生します。
IllegalArgumentException - 引数 systemCode に負の値、 または 216 以上の値が指定された場合に発生します。
IllegalArgumentException - [DoJa-5.0 (903i) 以降] 引数 systemCode に管理システムのシステムコードが指定された場合に発生します。
IllegalArgumentException - 引数 card に内部カードが指定された場合、かつ、 引数 systemCode にフリーエリアのシステムコードが指定された場合に発生します。
FelicaException - レスポンスタイムアウトにより、 ポーリングに失敗した場合に発生します (ID_POLLING_ERROR, TYPE_TIMEOUT_ERROR)。
FelicaException - レスポンスデータのフォーマットが正しくないことにより、 ポーリングに失敗した場合に発生します (ID_POLLING_ERROR, TYPE_FORMAT_ERROR)。
FelicaException - (外部カードのみ) [DoJa-5.0 (903i) 以降] 搬送波受信中のために、 ポーリングに失敗した場合に発生します (ID_POLLING_ERROR, TYPE_DEVICE_ERROR)。
FelicaException - (外部カードのみ) [DoJa-5.0 (903i) 以降] 外部カードからのレスポンスデータの長さが上限を超えていたことにより、 ポーリングに失敗した場合に発生します (ID_POLLING_ERROR, TYPE_UNEXPECTED_ERROR)。
FelicaException - ポーリングに失敗した場合に発生します (ID_POLLING_ERROR, TYPE_UNDEFINED_ERROR)。
java.io.InterruptedIOException - FeliCaカードアクセス中に、 サスペンド状態への遷移によりカードアクセス処理が失敗した場合に発生します。
PortBusyException - [DoJa-5.0 (903i) 以降] ポートビジーエラーが発生した場合に発生します。
java.io.IOException - 入出力エラーが発生した場合に発生します。

getFreeArea

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

戻り値:
FreeArea オブジェクトを返します。
例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
DeviceException - FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
SecurityException - ADFにFeliCaCPIDキーの指定がないアプリケーションが、 このメソッドを呼び出した場合に発生します。
SecurityException - ADFにFeliCaPINキーの指定がないアプリケーションが、 このメソッドを呼び出した場合に発生します。

getAdhocDataTransfer

public static AdhocDataTransfer getAdhocDataTransfer()

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

戻り値:
AdhocDataTransfer オブジェクトを返します。 常に同じオブジェクトへの参照を返します。
例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
DeviceException - FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
導入されたバージョン:
DoJa-5.0 (903i)

turnOffRFPower

public static void turnOffRFPower()
                           throws FelicaException,
                                  java.io.IOException
搬送波の出力を停止します。 搬送波の出力を停止すると、 無線通信速度が初期値(= 212kbps)に戻ります。

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

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

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

例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
DeviceException - FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
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カードアクセス中に、 サスペンド状態への遷移によりカードアクセス処理が失敗した場合に発生します。
PortBusyException - ポートビジーエラーが発生した場合に発生します。
java.io.IOException - 入出力エラーが発生した場合に発生します。
導入されたバージョン:
DoJa-5.0 (903i)

reset

public static void reset()
                  throws FelicaException,
                         java.io.IOException
FeliCa をリセットします。 このメソッドは、デバイス(FeliCa IC チップ)に対してソフトウェアリセットを行います。

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

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

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

例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
DeviceException - FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
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カードアクセス中に、 サスペンド状態への遷移によりカードアクセス処理が失敗した場合に発生します。
PortBusyException - ポートビジーエラーが発生した場合に発生します。
java.io.IOException - 入出力エラーが発生した場合に発生します。
導入されたバージョン:
DoJa-5.0 (903i)

activate

public static void activate()
                     throws FelicaException,
                            java.io.IOException
推奨されていません。  DoJa-5.0 (903i) 以降では、 このメソッドを呼び出さなくても外部 R/W からのアクセスを受け付けることができるため、 このメソッドはサポートされません。

[DoJa-4.1 (902iS) まで]
外部 R/W からのアクセスを待つ状態にします。 このメソッドは即座にリターンします。

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

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

[DoJa-5.0 (903i) 以降]
このメソッドを呼び出した場合、常に例外 UnsupportedOperationException が発生します。

アプリケーションは、 このメソッドを呼び出しても 外部 R/W からのアクセス待ち状態 にはなりません。従って、 オンライン処理中に呼び出すと例外が発生するようなメソッドにおいて、 「外部 R/W からのアクセス待ち状態下の場合」という理由で例外が発生することはありません。

例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
UnsupportedOperationException - [DoJa-5.0 (903i) 以降] このメソッドをサポートしていない場合に発生します。
DeviceException - [DoJa-4.1 (902iS) まで] FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
DeviceException - [DoJa-4.1 (902iS) まで] オンライン処理が既に開始されている場合や、 外部 R/W からのアクセス待ち状態下の場合に発生します(ILLEGAL_STATE)。
FelicaException - [DoJa-4.1 (902iS) まで] レスポンスタイムアウトにより、外部 R/W からのアクセス待ち状態への遷移に失敗した場合に発生します (ID_ACTIVATE_ERROR, TYPE_TIMEOUT_ERROR)。
FelicaException - [DoJa-4.1 (902iS) まで] レスポンスデータのフォーマットが正しくないことにより、 外部 R/W からのアクセス待ち状態への遷移に失敗した場合に発生します (ID_ACTIVATE_ERROR, TYPE_FORMAT_ERROR)。
FelicaException - [DoJa-4.1 (902iS) まで] 外部R/Wからのアクセス待ち状態への遷移に失敗した場合に発生します (ID_ACTIVATE_ERROR, TYPE_UNDEFINED_ERROR)。
java.io.InterruptedIOException - [DoJa-4.1 (902iS) まで] FeliCaカードアクセス中に、 サスペンド状態への遷移によりカードアクセス処理が失敗した場合に発生します。
java.io.IOException - [DoJa-4.1 (902iS) まで] 入出力エラーが発生した場合に発生します。

inactivate

public static void inactivate()
                       throws FelicaException,
                              java.io.IOException
推奨されていません。  DoJa-5.0 (903i) 以降では、 activate()メソッドを呼び出さなくても外部 R/W からのアクセスを受け付けることができるため、 このメソッドはサポートされません。

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

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

[DoJa-5.0 (903i) 以降]
このメソッドを呼び出した場合、常に例外 UnsupportedOperationException が発生します。

例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
UnsupportedOperationException - [DoJa-5.0 (903i) 以降] このメソッドをサポートしていない場合に発生します。
DeviceException - [DoJa-4.1 (902iS) まで] FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
FelicaException - [DoJa-4.1 (902iS) まで] レスポンスタイムアウトにより、外部 R/W からのアクセス 待ち状態の解除に失敗した場合に発生します (ID_INACTIVATE_ERROR, TYPE_TIMEOUT_ERROR)。
FelicaException - [DoJa-4.1 (902iS) まで] レスポンスデータのフォーマットが正しくないことにより、 外部 R/W からのアクセス待ち状態の解除に失敗した場合に発生します (ID_INACTIVATE_ERROR, TYPE_FORMAT_ERROR)。
FelicaException - [DoJa-4.1 (902iS) まで] 外部 R/W からのアクセス待ち状態の解除に失敗した場合に発生します (ID_INACTIVATE_ERROR, TYPE_UNDEFINED_ERROR)。
java.io.InterruptedIOException - [DoJa-4.1 (902iS) まで] FeliCaカードアクセス中に、 サスペンド状態への遷移によりカードアクセス処理が失敗した場合に発生します。
java.io.IOException - [DoJa-4.1 (902iS) まで] 入出力エラーが発生した場合に発生します。

setFelicaPushListener

public static void setFelicaPushListener(FelicaPushListener listener)
外部 R/W から Push 通知を受信した際のイベントを受け取るリスナを登録します。 FeliCa をオープンしているか否かに関わらず常にリスナを登録可能です。

登録できるリスナは 1 つだけです。 このメソッドを複数回呼び出した場合は最後に登録したリスナだけが有効です。 リスナオブジェクトとして null を指定するとリスナの登録を解除します。

パラメータ:
listener - 登録するリスナオブジェクトを指定します。
例外:
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
IllegalStateException - ダウンロード即起動アプリで呼び出された場合に発生します。
導入されたバージョン:
DoJa-5.0 (903i)