com.nttdocomo.device.felica
クラス OfflineFelica

Object
  com.nttdocomo.device.felica.OfflineFelica

public final class OfflineFelica

extends Object

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

フリーエリアアクセスを除くオフライン処理によって、 FeliCa にアクセスする手段を提供するクラスです。

このクラスのインスタンスの各メソッドは、 Felica.getOfflineFelica(int, int) の引数で指定されたアクセス先に対して、それぞれの操作を行います。 インスタンス生成後に、アクセス先を変更する手段は用意されていません。 複数のアクセス先に交互にアクセスする必要がある場合には、 アクセス先ごとに、Felica.getOfflineFelica(int, int) にて、 対応するインスタンスを取得してください。 ただし、同じカードの 異なるシステムにアクセスを行った時点で、 そのカード内のPINの解除情報がクリアされます。

このオブジェクトが生成された直後では、タイムアウト値としては 500[ms] が、 リトライ数としては 0 が、 それぞれ設定されています。 タイムアウト値は setTimeout(int) にて変更可能ですが、リトライ数を変更することはできません。

なお、オンライン処理中や 外部 R/W からのアクセス待ち状態下においては、オフライン処理を行うことはできません。 すなわち、OnlineFelica.start(String) を呼び出してから OnlineFelica.stop() を呼び出すまでの間や、 Felica.activate() を呼び出してから Felica.inactivate()、 Felica.close() を呼び出すまでの間には、 このクラスに用意されているメソッドを呼び出すことはできません。

セキュリティ上の制約について
iアプリが起動してから終了するまでの間に、下記の条件を満たした場合には、 その時点でアプリケーションは強制終了されます。 尚、下記に記されている失敗回数は、 このクラスの全インスタンスによる失敗回数の合計です。

• executePIN(PINParameters) において、 PIN指定誤りにより、 PINの照合、変更、有効/無効化に4回失敗した場合

導入されたバージョン:

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

関連項目:

Felica.getOfflineFelica(int, int)

フィールドの概要

static int	CARD_EXTERNAL 外部カードを表します(=1)。
static int	CARD_INTERNAL 内部カードを表します(=0)。

メソッドの概要

void	executePIN(PINParameters param) PINを変更、有効/無効化、或いは照合を行います。
int	getCard() このオブジェクトの処理対象カードを取得します。
byte[]	getCardVersion() このオブジェクトがアクセス先として保持しているカードのバージョンを返します。
byte[]	getIDm() このオブジェクトがアクセス先として保持しているIDmを返します。
byte[]	getKeyVersion(int serviceCode) キーバージョンを取得します。
int	getSystemCode() このオブジェクトがアクセス先として保持している システムコードを取得します。
int	getTimeout() タイムアウト値を取得します。
FelicaData[]	read(ReadParameters param) ブロックを読み込みます。
void	setTimeout(int timeout) このオブジェクトの カード処理におけるタイムアウト値を設定します。
void	write(WriteParameters param) ブロックを書き込みます。

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

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

フィールドの詳細

CARD_INTERNAL

public static final int CARD_INTERNAL

内部カードを表します(=0)。

関連項目:

定数フィールド値

CARD_EXTERNAL

public static final int CARD_EXTERNAL

外部カードを表します(=1)。

関連項目:

定数フィールド値

メソッドの詳細

executePIN

public void executePIN(PINParameters param)
                throws FelicaException,
                       java.io.IOException

PINを変更、有効/無効化、或いは照合を行います。 PINの変更、有効/無効化、照合は内部カードに対してのみ行うことが出来ます。

引数 param に複数のパラメータが登録されおり、かつ、 それらのパラメータのうち1つでもPIN処理に失敗した場合は、 param の実行時の型により以下のよう振る舞います。

InputPINParameters の場合:

最初のパラメータから順にPIN処理が行われ、 途中のパラメータのPIN処理に失敗した場合でも、 それ以前のパラメータで成功しているPIN処理は有効となります。

ChangePINParametersや、EnablePINParameters の場合:

登録されているパラメータのうち1つでもPIN処理に失敗した場合は、 全てのパラメータのPIN処理は行われません。

なお、 PINParametersに登録されているパラメータ数が 対象カードの同時 書き込み 上限数を超えていた場合においては、 引数 param の実行時の型にかかわらず、 全てのパラメータのPIN処理は行われません。

パラメータ:

param - PINパラメータ。PINParametesのいずれかのサブクラスです。

例外:

IllegalStateException - このオブジェクトが外部カードを指定して取得したものである場合に発生します。

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

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

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

IllegalArgumentException - 引数 param に登録パラメータ数 (OfflineParameters.getSize() が返す値) が 0 個の PIN パラメータが指定された場合に発生します。

FelicaException - レスポンスタイムアウトにより、 PIN照合、変更、有効/無効化に失敗した場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_TIMEOUT_ERROR)。

FelicaException - レスポンスデータのフォーマットが正しくないことにより、 PIN照合、変更、有効/無効化に失敗した場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_FORMAT_ERROR)。

FelicaException - 引数 param に含まれているパラメータの数が、 対象カードの同時書き込み上限数を超えていた場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_BLOCK_COUNT_OVER_ERROR)。

FelicaException - 指定されたサービスが存在しないことにより、 PIN照合、変更、有効/無効化に失敗した場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_SERVICE_CODE_ERROR)。

FelicaException - 親エリアのPIN未照合により、PIN照合、変更、有効/無効化に失敗した場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_PIN_REQUIRED_ERROR)。

FelicaException - PINの同時解除数が上限を超えたことにより、 PIN照合に失敗した場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_PIN_COUNT_OVER_ERROR)。

FelicaException - PINの照合試行回数が上限に達していることにより、PIN照合、変更、 有効/無効化に失敗した場合に発生します。 (ID_EXECUTEPIN_ERROR, TYPE_PIN_LOCK_OUT_ERROR)。

FelicaException - PINの照合失敗により、 PIN照合、変更、有効/無効化に失敗した場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_SETPIN_ERROR)。

FelicaException - PINの有効/無効の切り替え不可により、 有効/無効化に失敗した場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_SETATTRIBUTE_ERROR)。

FelicaException - PIN照合、変更、有効/無効化に失敗した場合に発生します (ID_EXECUTEPIN_ERROR, TYPE_UNDEFINED_ERROR)。

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

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

read

public FelicaData[] read(ReadParameters param)
                  throws FelicaException,
                         java.io.IOException

ブロックを読み込みます。

このメソッドによる読み込み処理は同時性が確保されます。 従って、ReadParametersに登録されているパラメータのうち１つでも読み込みに失敗した場合は、 全てのパラメータの読み込みは行われません。

ReadParametersに登録されているパラメータ数が 対象カードの同時読み込み上限数を超えていた場合、 全てのパラメータの読み込みは行われません。

パラメータ:

param - 読み込みパラメータ。

戻り値:

ブロックデータリスト。

例外:

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

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

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

IllegalArgumentException - 引数 param に登録パラメータ数 (OfflineParameters.getSize() が返す値) が0個の読み込みパラメータが指定された場合に発生します。

FelicaException - レスポンスタイムアウトにより、 読み出しに失敗した場合に発生します (ID_READ_ERROR, TYPE_TIMEOUT_ERROR)。

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

FelicaException - 引数 param に含まれているパラメータの数が、 対象カードの同時読み込み上限数を超えていた場合に発生します (ID_READ_ERROR, TYPE_BLOCK_COUNT_OVER_ERROR)。

FelicaException - 指定されたサービスが存在しないことにより、 読み出しに失敗した場合に発生します (ID_READ_ERROR, TYPE_SERVICE_CODE_ERROR)。

FelicaException - ブロックナンバーの指定不正により、読み出しに失敗した場合に発生します (ID_READ_ERROR, TYPE_BLOCK_NO_ERROR)。

FelicaException - PIN未照合により、読み出しに失敗した場合に発生します (ID_READ_ERROR, TYPE_PIN_REQUIRED_ERROR)。

FelicaException - 読み出しに失敗した場合に発生します (ID_READ_ERROR, TYPE_UNDEFINED_ERROR)。

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

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

write

public void write(WriteParameters param)
           throws FelicaException,
                  java.io.IOException

ブロックを書き込みます。

このメソッドによる書き込み処理は同時性が確保されます。 従って、WriteParametersに登録されているパラメータのうち１つでも書き込みに失敗した場合は、 全てのパラメータの書き込みは行われません。

WriteParametersに登録されているパラメータ数が 対象カードの同時書き込み上限数を超えていた場合、 全てのパラメータの書き込みは行われません。

パラメータ:

param - 書き込みパラメータ。

例外:

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

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

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

IllegalArgumentException - 引数 param に登録パラメータ数 (OfflineParameters.getSize() が返す値) が 0 個の書き込みパラメータが指定された場合に発生します。

FelicaException - レスポンスタイムアウトにより、 書き込みに失敗した場合に発生します (ID_WRITE_ERROR, TYPE_TIMEOUT_ERROR)。

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

FelicaException - 引数 param に含まれているパラメータの数が、 対象カードの同時書き込み上限数を超えていた場合に発生します (ID_WRITE_ERROR, TYPE_BLOCK_COUNT_OVER_ERROR)。

FelicaException - 指定されたサービスが存在しないことにより、 書き込みに失敗した場合に発生します (ID_WRITE_ERROR, TYPE_SERVICE_CODE_ERROR)。

FelicaException - ブロックナンバーの指定不正により、書き込みに失敗した場合に発生します (ID_WRITE_ERROR, TYPE_BLOCK_NO_ERROR)。

FelicaException - PIN未照合により、書き込みに失敗した場合に発生します (ID_WRITE_ERROR, TYPE_PIN_REQUIRED_ERROR)。

FelicaException - デクリメントでのパースバリュー不足、 あるいはキャッシュバックでのパースバリューのオーバーフローにより、 書き込みに失敗した場合に発生します (ID_WRITE_ERROR, TYPE_PURSE_ERROR)。

FelicaException - キャッシュバック値が直前のデクリメント値より大きいことにより、 書き込みに失敗した場合に発生します (ID_WRITE_ERROR, TYPE_CASHBACK_ERROR)。

FelicaException - サイクリック連続書き込みブロック数過大により、 書き込みに失敗した場合に発生します (ID_WRITE_ERROR, TYPE_CYCLIC_ERROR)。

FelicaException - 書き込みに失敗した場合に発生します (ID_WRITE_ERROR, TYPE_UNDEFINED_ERROR)。

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

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

getKeyVersion

public byte[] getKeyVersion(int serviceCode)
                     throws FelicaException,
                            java.io.IOException

キーバージョンを取得します。

このメソッドの引数に 2¹⁶ - 1 (0xffff) を指定した場合、 このオブジェクトがアクセス先として保持しているシステムのキーバージョンが返ります。

パラメータ:

serviceCode - サービスコード。 0 以上 2¹⁶ - 1 以下の値が指定できます。 2¹⁶ -1 (0xffff) を除いて、 属性部分には、エリアを表す属性値またはサービスを表す属性値が指定できます。

戻り値:

キーバージョン(2バイト)を返します。

例外:

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

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

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

IllegalArgumentException - 引数 serviceCode の属性部分の値が、エリアを表す属性値、 サービスを表す属性値のいずれでもない場合に発生します。

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

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

FelicaException - 指定されたサービスが存在しないことにより、 取得に失敗した場合に発生します (ID_GETKEYVERSION_ERROR, TYPE_SERVICE_CODE_ERROR)。

FelicaException - 取得に失敗した場合に発生します (ID_GETKEYVERSION_ERROR, TYPE_UNDEFINED_ERROR)。

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

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

getIDm

public byte[] getIDm()

このオブジェクトがアクセス先として保持しているIDmを返します。

戻り値:

IDmを返します。(8byte)

例外:

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

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

getCardVersion

public byte[] getCardVersion()

このオブジェクトがアクセス先として保持しているカードのバージョンを返します。

戻り値:

カードバージョンを返します。(2byte)

例外:

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

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

getSystemCode

public int getSystemCode()

このオブジェクトがアクセス先として保持している システムコードを取得します。

戻り値:

システムコードを返します。

例外:

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

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

getCard

public int getCard()

このオブジェクトの処理対象カードを取得します。

戻り値:

処理対象カードを返します。

例外:

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

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

getTimeout

public int getTimeout()

タイムアウト値を取得します。

戻り値:

タイムアウト値[ms]を返します。

例外:

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

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

setTimeout

public void setTimeout(int timeout)

このオブジェクトの カード処理におけるタイムアウト値を設定します。 ここで設定されたタイムアウト値は、 このオブジェクトに対してだけ有効です。

パラメータ:

timeout - タイムアウト値[ms]。 0 以上 60000 以下の値が指定できます

例外:

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

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

IllegalArgumentException - 引数 timeout に負の値、 または 60000 より大きい値が指定された場合に発生します。