Objectcom.nttdocomo.device.felica.Felica
FeliCa 機能を制御する基本クラスです。
このAPIでは、便宜上、FeliCa 機能の利用形態を
open()を呼び出した後に、それぞれ
getOnlineFelica()
getOfflineFelica(int, int)
getFreeArea()
getAdhocDataTransfer()
activate() や inactivate()
を利用します。
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 呼発着信以外によりサスペンドした場合、
システムが強制的に搬送波を停止します。
| メソッドの概要 | |
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 |
| メソッドの詳細 |
public static void open()
throws FelicaException
[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)。
public static void close()
throws FelicaException
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
FelicaException - FeliCaのクローズに失敗した場合に発生します
(ID_CLOSE_ERROR, TYPE_UNDEFINED_ERROR)。
public static OnlineFelica getOnlineFelica()
オンライン処理用に、OnlineFelicaオブジェクトを取得します。 このメソッドを複数回呼び出しても、常に同じインスタンスが返ります。
なお、パーミッションとしてFeliCaオンライン機能の利用が許可されていない場合には、 このメソッドを呼び出した時点でセキュリティ違反として強制終了されます。
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
DeviceException - FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
public static OfflineFelica getOfflineFelica(int card,
int systemCode)
throws FelicaException,
java.io.IOException
オフライン処理用に、OfflineFelicaオブジェクトを取得します。 このメソッドを呼び出すと、 下記の設定にて、 指定されたカードに対してポーリングを行います。 同じカードの異なるシステムへの ポーリングに成功すると、そのカード内で システム切り替えが発生しPINの解除情報がクリアされます。
| 内部カード | 外部カード | |
| タイムアウト値 | 500[ms] | 250[ms] |
| リトライ数 | 0 | 0 |
このメソッドは、引数の組合せに関係なくポーリングを行います。 ポーリングの成功結果によって取得したIDmが、 それまでに取得したことのないIDmである場合は、新規にインスタンスを生成し返します。 既に取得済みのIDmである場合は、その時と同じインスタンスを返します。
OfflineFelica.CARD_EXTERNAL)が指定された場合には、
例外 UnsupportedOperationException が発生します。
OfflineFelica.CARD_EXTERNAL)を指定可能です。
内部カード が指定された場合に、
引数 systemCode にフリーエリアのシステムコードが指定された場合
card - 処理対象カード
(OfflineFelica.CARD_INTERNAL、
またはOfflineFelica.CARD_EXTERNAL)。systemCode - システムコード。
0 以上 216 - 1 以下の値が指定できます。
内部カード が指定された場合には
OfflineFelica オブジェクトを、
外部カード が指定された場合には
ThruRWOfflineFelica オブジェクトを返します。
ただし、引数 systemCode にワイルドカードが指定された場合、
以下の条件を満たしたときには null を返します。
内部カード が指定された場合に、
ポーリングの成功結果によって取得したシステムコードがフリーエリアのシステムコードである場合
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 - 入出力エラーが発生した場合に発生します。public static FreeArea getFreeArea()
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
DeviceException - FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
SecurityException - ADFにFeliCaCPIDキーの指定がないアプリケーションが、
このメソッドを呼び出した場合に発生します。
SecurityException - ADFにFeliCaPINキーの指定がないアプリケーションが、
このメソッドを呼び出した場合に発生します。
public static AdhocDataTransfer getAdhocDataTransfer()
アドホック通信用に AdhocDataTransfer オブジェクトを取得します。 このメソッドを呼び出した時点では、外部カードに対しては何も行いません。
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
DeviceException - FeliCaがオープンされていない場合に発生します(ILLEGAL_STATE)。
public static void turnOffRFPower()
throws FelicaException,
java.io.IOException
i アプリが以下のメソッドを呼び出すと、 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 チップは、搬送波を出力している間は、 外部 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 - 入出力エラーが発生した場合に発生します。
public static void reset()
throws FelicaException,
java.io.IOException
なお、FeliCa IC チップは、 リセットによって以下のことが起こります。
このメソッドは、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 - 入出力エラーが発生した場合に発生します。
public static void activate()
throws FelicaException,
java.io.IOException
[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) まで]
入出力エラーが発生した場合に発生します。
public static void inactivate()
throws FelicaException,
java.io.IOException
[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) まで]
入出力エラーが発生した場合に発生します。
public static void setFelicaPushListener(FelicaPushListener listener)
登録できるリスナは 1 つだけです。 このメソッドを複数回呼び出した場合は最後に登録したリスナだけが有効です。 リスナオブジェクトとして null を指定するとリスナの登録を解除します。
listener - 登録するリスナオブジェクトを指定します。
UnsupportedOperationException - FeliCa機能をサポートしていない場合に発生します。
IllegalStateException - ダウンロード即起動アプリで呼び出された場合に発生します。