abc NFCFelica ライブラリマニュアル このマニュアルは、NFCFelica ライブラリの 仕様について記載します。 Ver. 1.
ご注意 ● このソフトウェアおよびマニュアルの、一部または全部を無断で使用、複製することはできません。 ● このソフトウェアおよびマニュアルは、本製品の使用許諾契約書のもとでのみ使用することができます。 ● このソフトウェアおよびマニュアルを運用した結果の影響については、一切の責任を負いかねますのでご了 承ください。 ● このソフトウェアの仕様、およびマニュアルに記載されている事柄は、将来予告なしに変更することがありま す。 ● このマニュアルの著作権はカシオ計算機株式会社に帰属します。 ● 本書中に含まれている画面表示は、実際の画面とは若干異なる場合があります。予めご了承ください。 © 2012 カシオ計算機株式会社 Microsoft, MS, ActiveSync, Active Desktop, Outlook, Windows, Windows NT, および Windows ロゴは、米国 Microsoft Corporation の米国およびその他の国における登録商標または商標です。Microsoft 社の製品は、OEM 各社に、Microsoft Corporation の 100%出資子会
変更履歴 バージョン 0.90 1.00 1.01 変更日付 2009.07 2010.05 2012.01 2012.
目次 1. 概要···················································································································································································1 2. 動作環境 ·········································································································································································2 3.
1.
2. 動作環境 NFCFelica ライブラリの動作環境を以下に示します。 対象機種 • DT-5300 • DT-X8 • IT-9000 対象 OS • Microsoft WindowsCE 6.0 • Microsoft WindowsMobile 6.5 開発環境とプログラミング言語 Visual C++ 開発環境 Microsoft Visual Studio 2005 + SP1 Microsoft Visual Studio 2008 + SP1 ○ ○ Visual Basic, Visual C# ○ ○ 提供ファイル ファイル NFCFelicaLib.h NFCFelicaLib.lib NFCFelicaLib.dll NFCFelicaLibNet.dll Visual C++ ○ ○ ○ - Visual Basic, Visual C# ○ ○ 使用方法 Visual C++の場合 • プログラムソース内に NFCFelicaLib.h と NFCLib.h をインクルードし、リンカの依存ファイルとして NFCFelicaLib.
名前空間とクラス クラスライブラリ NFCFelicaLibNet.dll では、関数および定数の参照用として、下記のクラスが用意されてい ます。 名前空間 CaLib クラス名 NFCFelicaLibNet.Api NFCFelicaLibNet.Def 内容 関数参照用クラス 定数参照用クラス クラス定義の詳細については、Microsoft Visual Studio で NFCFelicaLibNet.
3.
■関数呼び出し手順 アプリケーション起動時 １． NFCFelicaOpen 関数により、NFC デバイスの電源を ON にします。※1 ２． NFCFelicaSamOpen 関数により、SAM スロットの電源を ON にします。※2 ３． NFCFelicaSamPowerUp 関数により、SAM スロットに挿入した SAM カード（RC-S251）の電源を ON に します。※3 ４． NFCFelicaSamAuthentication 関数により、NFCFelica ライブラリと SAM カードとの相互認証を行ない ます。 ※ 2 から 4 の手順は FeliCa カードのセキュリティ領域にアクセスする場合にのみ行ないます。 FeliCa カードとの通信時 1. 通信処理開始時に、NFCFelicaPolling 関数により電波送信を開始し、通信可能範囲内にある FeliCa カードを検索します。 2. FeliCa カードから応答がある場合、NFCFelicaGetCardResponse 関数により、応答情報を取得しま す。 3. FeliCa カードとの通信を行います。(次ページを参照) 4.
FeliCa カードとの通信(セキュリティ領域にアクセスする場合) １． NFCFelicaAuthentication 関数により、FeliCa カードと SAM カード （RC-S251）の相互認証を行ないます。相互認証に成功すると、セキュリテ ィ領域にアクセスできるようになります。 ２． NFCFelicaReadWithEncryption 関数または NFCFelicaWriteWithEncryption 関数を実行し、データアクセスを実行しま す。 ３． 同一エリア・サービス内の他のブロックにアクセスする場合は、2.に戻って 処理を繰り返します。 ４． 他のエリアまたはサービスにアクセスする場合は 1.に戻って処理を繰り返 します。 NFCFelicaAuthentication NFCFelicaReadWithEncryption NFCFelicaWriteWithEncryption 同一エリアサービス アクセス終了 No Yes 他のエリアサービス アクセス Yes No FeliCa カードとの通信(非セキュリティ領域にアクセスする場合) 1.
3.
3.
3.
dwReserved 現在のバージョンではこの引数を使用しません。0 を指定してください。 戻り値 以下の値を返します。 NFC_OK NFC_NOT_DEVICE NFC_POF NFC_PRM NFC_ERROR_TIMEOUT NFC_ERROR_CALLBACK NFC_ERROR_MODULE NFC_ERROR_STOP : 正常終了 : NFC ドライバエラー DeviceEmulator では発生しません : 未オープンエラー : パラメータエラー : タイムアウトエラー DeviceEmulator では発生しません : コールバック関数エラー DeviceEmulator では発生しません : モジュール未応答エラー DeviceEmulator では発生しません : 停止関数による中断エラー DeviceEmulator では発生しません 10
3.
3.
dwReserved 現在のバージョンではこの引数を使用しません。0 を指定してください。 戻り値 以下の値を返します。 NFC_OK NFC_NOT_DEVICE NFC_POF NFC_PRM : 正常終了 : NFC ドライバエラー DeviceEmulator では発生しません : 未オープンエラー : パラメータエラー 13
3.
3.
以下の値を返します。 NFC_OK NFC_NOT_DEVICE NFC_POF NFC_PRM NFC_ERROR_TIMEOUT NFC_NOT_ACTIVATION NFC_ERROR_MODULE NFC_ERROR_SUSPEND NFC_ERROR_AUTOOFF : 正常終了 : NFC ドライバエラー DeviceEmulator では発生しません : 未オープンエラー : パラメータエラー : タイムアウトエラー DeviceEmulator では発生しません : カード未起動エラー DeviceEmulator では発生しません : モジュール未応答エラー DeviceEmulator では発生しません : 本体 OFF 発生エラー DeviceEmulator では発生しません : 電波自動停止エラー DeviceEmulator では発生しません 16
3.
以下の値を返します。 NFC_OK NFC_NOT_DEVICE NFC_POF NFC_PRM NFC_ERROR_TIMEOUT NFC_NOT_ACTIVATION NFC_ERROR_MODULE NFC_ERROR_SUSPEND NFC_ERROR_AUTOOFF : 正常終了 : NFC ドライバエラー DeviceEmulator では発生しません : 未オープンエラー : パラメータエラー : タイムアウトエラー DeviceEmulator では発生しません : カード未起動エラー DeviceEmulator では発生しません : モジュール未応答エラー DeviceEmulator では発生しません : 本体 OFF 発生エラー DeviceEmulator では発生しません : 電波自動停止エラー DeviceEmulator では発生しません 18
3.
3.
3.
3.
3.
NFC_OK NFC_NOT_DEVICE NFC_POF NFC_PRM : 正常終了 : NFC ドライバエラー DeviceEmulator では発生しません : 未オープンエラー : パラメータエラー 補足 IC カードの検索方式 通常起動 : 多段起動/ : 多段起動 2 一括起動 : 1 回の検索で 1 枚の IC カードを起動します 段数に指定した回数まで異なる IC カードを連続して起動します （1 回の検索で 1 枚しか起動することができません）※ 1 回の検索で同一タイプの複数枚の IC カードを起動します 段数に指定した回数まで検索を行います ※ 注意 IC カードを 1 つ起動するたびに、起動した IC カードの Uid をドライバに記録し、その記 録した IC カードと重複する IC カードの二重起動を防止します。この記録は、指定した 枚数の IC カードを起動したとき、タイムアウト時間を経過したとき、コールバック関数が FALSE を返したとき、およびNFCFelicaStopPolling関数を実行したときにクリアします。 24
3.
3.
pbyPMm 起動に成功した IC カードの PMm を取得します。 バッファサイズは（8×NFCFelicaSetPollingMode関数の dwNum）以上確保してください。 8バイト 1枚目のPMm 8バイト ... 2枚目のPMm ... 8バイト n枚目のPMm pdwSystemCode 起動に成功した IC カードのシステムコードを取得します。 サイズは（4×NFCFelicaSetPollingMode関数の dwNum）以上確保してください。 4バイト 1枚目の システムコード 4バイト 2枚目の システムコード ... ...
3.
3.
3.
3.
3.
注意 本関数で相互認証の成功後、端末を電源 OFF すると、電源 ON 時に状態がリセットされ、相互認証前 の状態に戻ります。 補足 暗号化 本関数は、NFCFelica ライブラリと SAM カード（RC-S251）と暗号化なしの相互認証を行います。そのた め、SAM カードのコミュニケーション設定において、暗号化方式を Disable CBC off に設定してくださ い。詳細は SAM カードのマニュアルを参照してください。 通信回数 SAM カード（RC-S251）との通信回数が 65535 回を超えると、SAM カードとの通信ができなくなります。 そのため、NFCFelicaAuthentication関数、NFCFelicaReadWithEncryption関数、および NFCFelicaWriteWithEncryption関数が NFC_ERROR_COUNT を返します。その場合、本関数を実行 して通信回数をクリアしてください。 33
3.
dwSlotNumber 通信対象の SAM カードを挿入したカードスロット番号を指定します。（1∼カードスロット数） dwSystemCode NFCFelicaGetCardResponse関数またはNFCFelicaGetCardResponseEx関数で取得したシステムコー ドを指定します。 wSystemKeyVer システム鍵バージョンを指定します。（リトルエンディアン） byAreaNum エリア数を指定します。（1∼8） pbyAreaCode エリアコード/エリア鍵バージョンリスト（リトルエンディアン）を指定します。 byServiceNum サービス数を指定します。（1∼8） pbyServiceCode サービスコード/サービス鍵バージョンリスト（リトルエンディアン）を指定します。 dwTargetNo 通信したい IC カードに対応したカード番号を指定します。 通常は 0 を指定してください。NFCFelicaPolling関数で複数の IC カードの起動に成功した状態で 2 枚 目以降の IC カードと通信する場合は 1 以上の値を指定してください。 dwReserv
dwSystemCode wSystemVer byAreaNum pbyAreaCode = = = = 0x00001800; 0x0100; 0x01; {0x00, 0x00, 0x01, 0x00}; byServiceNum = 0x01; pbyServiceCode = {0x20, 0x10, 0x01, 0x00}; dwTargetNo dwReserved = 0x00000000; = 0x00000000; 36 // エリアコード 2 バイト // 鍵バージョン 2 バイト // サービスコード 2 バイト // 鍵バージョン 2 バイト
3.
pbyData 読み出したブロックデータを取得します。（16 バイト×ブロック数） pbyActualNum 読み出したブロック数を取得します。 dwTargetNo 通信したい IC カードに対応したカード番号を指定します。 通常は 0 を指定してください。NFCFelicaPolling関数で複数の IC カードの起動に成功した状態で 2 枚 目以降の IC カードと通信する場合は 1 以上の値を指定してください。 dwReserved 現在のバージョンではこの引数を使用しません。0 を指定してください。 戻り値 以下の値を返します。 NFC_OK NFC_NOT_DEVICE NFC_POF NFC_PRM NFC_ERROR_NOCARD NFC_ERROR_ACTIVATION NFC_ERROR_TIMEOUT NFC_ERROR_SUSPEND NFC_ERROR_RESPONSE NFC_ERROR_COUNT : 正常終了 : NFC ドライバエラー DeviceEmulator では発生しません : 未オープンエラー : パラメータエラー : SAM カード未挿入エラー : SAM
3.
dwTargetNo 通信したい IC カードに対応したカード番号を指定します。 通常は 0 を指定してください。NFCFelicaPolling関数で複数の IC カードの起動に成功した状態で 2 枚 目以降の IC カードと通信する場合は 1 以上の値を指定してください。 dwReserved 現在のバージョンではこの引数を使用しません。0 を指定してください。 戻り値 以下の値を返します。 NFC_OK NFC_NOT_DEVICE NFC_POF NFC_PRM NFC_ERROR_NOCARD NFC_ERROR_ACTIVATION NFC_ERROR_TIMEOUT NFC_ERROR_SUSPEND NFC_ERROR_RESPONSE NFC_ERROR_COUNT : 正常終了 : NFC ドライバエラー DeviceEmulator では発生しません : 未オープンエラー : パラメータエラー : SAM カード未挿入エラー : SAM カード未起動エラー : タイムアウトエラー : 本体電源 OFF エラー : カード異常応答発生エラー : SAM 通信回数オーバー 使用例 0
4. プログラミング上の注意点 4.1 電波停止の通知について ウィンドウメッセージ通知を使用する場合 電波を手動で停止する場合 1. WM_CREATE メッセージを受け取った場合は、NFCFelicaOpen関数を実行し、読み取り待機状態に します。 2. WM_COMMAND、WM_KEYDOWN 等のメッセージを受け取った場合は、NFCFelicaPolling関数によ り、通信可能範囲内にある FeliCa カードを検索/起動します。 3. FeliCa カードの起動に成功、かつ、そのカードの詳細な情報が必要な場合は、 NFCFelicaGetCardResponse関数により、応答情報を取得します。（任意） 4. FeliCa カードとの通信を行います※。 5. IC カードとの通信が終了した場合は、NFCFelicaRadioOff関数により、電波出力を停止します。 6.
電波を自動で停止し、停止タイミングを通知する場合 1. WM_CREATE メッセージを受け取った場合は、NFCFelicaOpen関数を実行し、読み取り待機状態に します。 2. NFCFelicaSetEventNotification関数により、ウィンドウメッセージ通知を有効に設定します。 3. NFCFelicaSetAutoRadioOff関数により、電波自動停止を有効に設定します。 4. WM_COMMAND、WM_KEYDOWN 等のメッセージを受け取った場合は、NFCFelicaPolling関数によ り、通信可能範囲内にある IC カードを検索/起動します。 5. FeliCa カードの起動に成功、かつ、そのカードの詳細な情報が必要な場合は、 NFCFelicaGetCardResponse関数により、応答情報を取得します。（任意） 6. FeliCa カードとの通信を行います※。 7. FeliCa カードとの通信が終了した場合は、NFCFelicaRadioOff関数により、電波出力を停止します。 （停止しない場合でも、通信を一定時間行わないと自動的に電波出力を停止します） 8.
イベント通知を使用する場合 電波を手動で停止する場合 1. アプリケーション開始時に、NFCFelicaOpen関数により、読み取り待機状態にします。 2. 通信処理開始時に、NFCFelicaPolling関数により、通信可能範囲内にある FeliCa カードを検索/起動 します。 3. FeliCa カードの起動に成功、かつ、そのカードの詳細な情報が必要な場合は、 NFCFelicaGetCardResponse関数により、応答情報を取得します。（任意） 4. FeliCa カードとの通信を行います※。 5. FeliCa カードとの通信が終了した場合は、NFCFelicaRadioOff関数により、電波出力を停止します。 6.
電波を自動で停止し、停止タイミングを通知する場合 ■ メインスレッド 1. アプリケーション開始時に、CreateEvent 関数により、電波自動停止タイミング通知イベントハンドルを 作成します。 2. CreateThread 関数により、電波自動停止を監視するスレッドを作成します。 3. NFCFelicaOpen関数により、読み取り待機状態にします。 4. NFCFelicaSetEventNotification関数により、イベント通知を有効に設定します。 5. NFCFelicaSetAutoRadioOff関数により、電波自動停止を有効に設定します。 6. 通信処理開始時に、NFCFelicaPolling関数により、通信可能範囲内にある FeliCa カードを検索/起動 します。 7. FeliCa カードの起動に成功、かつ、そのカードの詳細な情報が必要な場合は、 NFCFelicaGetCardResponse関数により、応答情報を取得します。（任意） 8. FeliCa カードとの通信を行います※。 9.
■ NFCFelica スレッド 13. WaitForSingleObject 関数により、電波自動停止タイミング通知イベントハンドルに対して待機しま す。 14. アプリケーション終了時に通知イベントを受け取った場合、電波自動停止の監視を終了します。 15.
4.2 FeliCa カードとの通信について 以下は「電波停止の通知について」におけるカードとの通信部分の手順です。 1.
4.3 検索方式について 多段起動を使用する場合 FeliCa カードと通信する場合 1. NFCFelicaSetPollingMode関数により、検索方式に多段起動 （NFC_PLMODE_MULTISTEP）を、段数に連続起動するカード 枚数 CARD_NUM を指定します。 2. iCount=0 をセットします。 3. iCount
多段起動 2 を使用する場合 FeliCa カードと通信する場合 1. NFCFelicaSetPollingMode関数により、検 索方式に多段起動 （NFC_PLMODE_MULTISTEP2）を、段数 に連続起動するカード枚数 CARD_NUM を指定します。 2. iCount=0 をセットします。 3. iCount
一括起動を使用する場合 FeliCa カードと通信する場合 1. NFCFelicaSetPollingMode関数により、検索方式に一括起 動（NFC_PLMODE_PACKAGE）を、段数に一括起動する枚 数を指定します。 2. NFCFelicaPolling関数により通信範囲内のカードを検索しま す。 3. IC カードが起動したら次の処理に進みます。 4. k に起動した枚数を、dwTargetNo に 0 をセットします。 （NFCFelicaRead関数やNFCFelicaWrite関数の引数） 5. dwTargetNo が k よりも小さい場合、次の処理に進みます。 6. NFCFelicaRead関数またはNFCFelicaWrite関数により、デ ータアクセスを実行します。 7. 他のブロックにアクセスする場合は、6.に戻って処理を繰り 返します。 8. 次のカードと通信する場合、dwTargetNo に 1 加算し、5.に 戻って同様の処理を繰り返します。 9. 5.において、dwTargetNo が k よりも大きい場合、ループ処 理を終了します。 10.
カシオ計算機お問い合わせ窓口 製品に関する最新情報 ●製品サポートサイト（カシオペア・ハンディターミナル） http://casio.
