NFC Felica Library Manual (Version 1.01)

CASIO Computer Co., Ltd. Copyright ©2012. All rights reserved. February 2012

Table of the Contents Chapter 1. Chapter 2. Chapter 3. 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 3.12 3.13 3.14 3.15 3.16 3.17 3.18 3.19 3.20 3.21 3.22 3.23 Chapter 4. 4.1 4.1.1 4.1.2 4.2 4.3

Editorial Record Overview Operation Environment Functions List NFCFelicaOpen NFCFelicaClose NFCFelicaPolling NFCFelicaStopPolling NFCFelicaGetCardResponse NFCFelicaRadioOff NFCFelicaRead NFCFelicaWrite NFCFelicaSetEventNotification NFCFelicaGetEventNotification NFCFelicaSetAutoRadioOff NFCFelicaGetAutoRadioOff NFCFelicaSetPollingMode NFCFelicaGetPollingMode NFCFelicaGetCardResponseEx NFCFelicaSamOpen NFCFelicaSamClose NFCFelicaSamPowerUp NFCFelicaSamPowerDown NFCFelicaSamAuthentication NFCFelicaAuthentication NFCFelicaReadWithEncryption NFCFelicaWriteWithEncryption Notes to Programming Notification for Radio Wave Stop Using Window Message Notification Using Event Notification Communicating with FeliCa Cards About search method

3 4 5 6 10 11 12 14 15 17 18 20 22 23 24 25 26 28 29 31 32 33 34 35 37 40 42 44 44 44 48 52 53

No part of this document may be produced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of CASIO Computer Co., Ltd. in Tokyo Japan. Information in this document is subject to change without advance notice. CASIO Computer Co., Ltd. makes no representations or warranties with respect to the contents or use of this manual and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. © 2012 CASIO Computer Co., Ltd. All rights reserved. 2

Editorial Record Manual Version no. 1.00

Date edited

Page

Content

May 2010

Original DT-X8 & IT-9000 added to compatible models Functions added In Chapter 1,Overview explanation is corrected. In Chapter 3,Functions List explanation is added. In Chapter 4.3,About search method is added.

Jan2012 1.01 February2012

3

1. Overview The Near Field Communication (NFC) Felica Library provides functions for communicating with FeliCa cards. (See note) When accessing FeliCa card using NFC Library, your application needs to create FeliCa command by itself, and needs to transmit it to FeliCa card. NFC Felica Library creates FeliCa command instead of your application, and supports access to FeliCa card. When the smart cards in question belong exclusively to the FeliCa card system, applications can be developed more efficiently using the NFC Felica Library rather than the NFC Library. Using the NFC Felica Library enables enhanced application source code compatibility without the need to be mindful of the terminal model. Regardless of the model of handheld terminal being used, the NFC Felica Library provides all of the functions as well as the behavior of a 'virtual machine' from the perspective of the application. Each of the NFC Felica Library functions returns an unsupported function error (FUNCTION_UNSUPPORT) when the subject device function cannot be controlled in response to a request from the application. In addition, configuring a parameter which is not available due to a difference in the functions of the equipped device will result in a parameter error being returned. The NFC Felica Library is designed to enhance the compatibility of application source codes and is not intended to ensure compatibility of the equipped device functions. Please therefore be sure to correctly judge unsupported function and parameter errors and notify the operator that the function is not supported or, alternatively, invalidate the process altogether. Note: FeliCa is the contactless IC card technology developed by Sony Corporation. FeliCa is a trademark of Sony Corporation.

4

2. Operation Environment Applicable Handheld Terminals • IT-800 series • DT-X8 series • IT-9000 series

OS • Microsoft® WindowsCE 6.0 • Microsoft® Windows Mobile® 6.5

IDE and Programming Languages Table 2.1 Integrated Development Environment (IDE)

Visual C++

Microsoft Visual Studio 2005 + SP1 Microsoft Visual Studio 2008 + SP1

Y Y

Visual Basic, Visual C# Y Y

Provided Files Table 2.2 File

Visual C++

NFCFelicaLib.h NFCFelicaLib.lib NFCFelicaLib.dll NFCFelicaLibNet.dll

Y Y Y -

Visual Basic, Visual C# Y Y

How to Use the Library When using Visual C++ • Include NFCFelicaLib.h and FNCLib.h within the program source and designate NFCFelicaLib.lib as the linker dependent file. • NFCFelicaLib.dll is stored within the handheld terminal.

When using Visual Basic or Visual C# • Add reference NFCFelicaLibNet.dll into project. • NFCFelicaLib.dll is stored within the handheld terminal. • Copy NFCFelicaLibNet.dll into same folder with execute module.

5

3. Functions List The following functions are provided by the NFC FeliCa Library.

NFCFelicaOpen NFCFelicaClose

NFCFelicaPolling

NFCFelicaStopPolling NFCFelicaGetCardResponse NFCFelicaRadioOff NFCFelicaRead NFCFelicaWrite NFCFelicaSetEventNotification NFCFelicaGetEventNotification NFCFelicaSetAutoRadioOff NFCFelicaGetAutoRadioOff NFCFelicaSetPollingMode NFCFelicaGetPollingMode NFCFelicaGetCardResponseEx NFCFelicaSamOpen NFCFelicaSamClose NFCFelicaSamPowerUp NFCFelicaSamPowerDown NFCFelicaSamAuthentication NFCFelicaAuthentication NFCFelicaReadWithEncryption NFCFelicaWriteWithEncryption

Description

Sets up NFC driver in communication permit state and turns on NFC driver power. Sets up NFC driver in communication prohibit state and turns off NFC device power. Searches FeliCa cards located in communication range and retrieves their UID. Terminates search for FeliCa cards in communication range. Retrieves detailed information about activated FeliCa cards. Terminates radio wave transmission. Reads specified address data (16 bytes). Writes data to a specified address (16 bytes). Sets up timing notification method for radio wave automatic stop. Retrieves the timing notification method for radio wave automatic stop. Sets up the time period until when radio wave automatic stop. Retrieves the time period until when radio wave automatic stop. Configures the smart card search method Fetches the smart card search method Fetches detailed information of activated smart cards Turns on the SAM card controller Turns off the SAM card controller Turns on the SAM card of the assigned slot number Turns off the SAM card of the assigned slot number Mutual authentication of the Felica Library and SAM card* Mutual authentication of the FeliCa card and SAM card* Reads the FeliCa security domain data* Writes the FeliCa security domain data* 6

IT-9000

Function

DT-X8

Security functions IT-800

Table 3.1

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y Y Y

Y Y Y

Y Y Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

Y

-

Y Y

Y Y

-

Y

Y

-

-

Y Y

-

-

Y

-

-

Y

-

-

Y

-

-

Y

-

-

Y Y

Y: Function supported - : Function not supported * Requires a FeliCa SAM card (RC-S251)

Function call procedure Application startup 1. Turn on the NFC device using the NFCFelicaOpen function. (See note 1) 2. Turn on the SAM slot using the NFCFelicaSamOpen function. (See note 2) 3. Turn on the SAM card (RC-S251) inserted in SAM slot using the NFCFelicaSamPowerUp function. (See note 3) 4. Perform mutual authentication of the NFC Felica Library and SAM card using the NFCFelicaSamAuthentication function. The procedure of 2 to 4 is performed only when accessing the security domain of FeliCa card.

Communicating with FeliCa cards 1. Upon initiating communication processing, execute the NFCFelicaPolling function to start transmitting radio waves and search for FeliCa cards within the communicable range. 2. If a FeliCa card responds, use the NFCFelicaGetCardResponse function to fetch the response information. 3. Perform communication with the FeliCa card. 4. When communication with the smart card is complete, execute the NFCFelicaRadioOff function to terminate radio wave output. See the next page for details on communicating with FeliCa cards.

Applicaiton end 1. Turn off the SAM card inserted in SAM slot using the NFCFelicaSamPowerDown function 2. Turn off the SAM slot using the NFCFelicaSamClose function. 3. Turn off the NFC device using the NFCFelicaClose function. The procedure of 1 to 2 is performed only when accessing the security domain of FeliCa card.

7

NFCFelicaPolling

NFCFelicaOpen

No

Response received from card

Yes

NFCFelicaSamOpen

NFCFelicaGet CardResponse

NFCFelicaSam PowerDown

NFCFelicaSam PowerUp

Communicate with card

NFCFelicaSamClose

NFCFelicaSam Authentication

NFCFelicaRadioOff

NFCFelicaClose

Note: 1. Since NFC device goes to standby mode while not communicating with FeliCa card, electric power is hardly used. 2. Since SAM controller goes to standby mode when the power supply of SAM card (RC-S251) is off, electric power is hardly used. 3. When the power supply of SAM card (RC-S251) is on, about 15-mA electric power is consumed.When use of electric power needs to be suppressed, please usually turn off the power supply of SAM card, and only when you access SAM card, turn on a power supply.

8

Communicating with FeliCa cards (security domain) 1. Perform mutual authentication of the FeliCa card and SAM card (RC-S251) using the NFCFelicaAuthentication function. If mutual authentication is successful, you can access the FeliCa card's security domain. 2. Execute the NFCFelicaReadWithEncryption or NFCFelicaWriteWithEncryption functions and perform data access. 3. When accessing other blocks within the same area/service, return to Step 2 and repeat the procedure. 4. When accessing a different area or service, return to Step 1 and repeat the procedure.

NFCFelicaAuthentication

NFCFelicaReadWithEncryption NFCFelicaWriteWithEncryption

Terminate access to same area/service

No

Yes Access other area/service

Yes

No

Communicating with FeliCa cards (non-security domain) 1. Carry out NFCFelicaRead or NFCFelicaWrite function.

NFCFelicaRead NFCFelicaWrite

Process End?

No

Yes

9

3.1 NFCFelicaOpen This function sets up the NFC driver in communication permit state (open state) and turns on the NFC device power. While the state is being kept effect, communication starts as soon as NFCFelicaPolling function is carried out. This state remains until when NFCFelicaClose function is carried out. Calling Sequence [C++] int NFCFelicaOpen( HWND hWnd ) [Visual Basic] Public Shared Function NFCFelicaOpen( ByVal hWnd As IntPtr_ ) As Int32 [C#] Public static Int32 NFCFelicaOpen( IntPtr hWnd )

Parameters hWnd Designates the application window handle. A message is sent to the designated window handle when the radio wave automatic stop is set effect and the event notification method is set to 'message'. If 'NULL' is set in this parameter the message is sent to 'BROADCAST'. Return Values The following values are returned. NFC_OK : Normal termination NFC_PON : The NFC driver is being opened. See note. NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_ERROR_MODULE : No response from the module. In the Device Emulator, the value is not returned. Note: If NFCFelicaOpen function is carried out twice or more in the same process, the function returns NFC_OK.

10

3.2 NFCFelicaClose This function sets the NFC driver in communication prohibit state (close state) and turns off the NFC device power. Calling Sequence [C++] int NFCFelicaClose() [Visual Basic] Public Shared Function NFCFelicaClose() As Int32 [C#] Public static Int32 NFCFelicaClose()

Parameters None Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned.

11

3.3 NFCFelicaPolling This function searches FeliCa cards that are located in the communication range. When the function detects a FeliCa card, it activates the card for data communication. The function continues to search FeliCa cards that are located in the communication range until either it detects a FeliCa card, the specified timeout elapses, or the specified callback function returns 'FALSE'. In the Device Emulator, the function checks parameters only. Calling Sequence [C++] int NFCFelicaPolling( DWORD dwTimeout, BOOL (*fpCallBack)(void), DWORD dwSystemCode, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaPolling( ByVal dwTimeout As Int32, _ ByVal fpCallBack As IntPtr, _ ByVal dwSystemCode As Int32, _ ByVal dwReserved As Int32, _ ) As Int32 [C#] Public static Int32 NFCFelicaPolling( Int32 dwTimeout, IntPtr fpCallBack, Int32 dwSystemCode, Int32 dwReserved )

Parameters dwTimeout Specifies a period of time in the range of 100 to 60,000 (milliseconds) for timeout starting from when a FeliCa card is found and until when the card is initiated. If '0' is set in this parameter, the function searches FeliCa cards without spending time period of the timeout. fpCallBack Specifies the callback function that determines whether searching FeliCa cards should be continued or not. When the callback function returns 'TRUE' the search process is continued, or the process is terminated when it returns 'FALSE'. Specifying "NULL" in this parameter continues the search process irrespective of the return value. 12

dwSystemCode Specifies the system code of FeliCa card that is activated. To activate FeliCa cards for all system codes, specify '0xFFFF'. dwReserved This parameter is not supported in the current version. Specify '0'.

Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error NFC_ERROR_TIMEOUT : Timeout error. In the Device Emulator, the value is not returned. NFC_ERROR_CALLBACK : Callback function error. In the Device Emulator, the value is not returned. NFC_ERROR_MODULE : No response from the module. In the Device Emulator, the value is not returned. NFC_ERROR_STOP : Suspend error caused by the stop function. In the Device Emulator, the value is not returned.

13

3.4 NFCFelicaStopPolling This function stops searching FeliCa cards that are located in the communication range. Carrying out NFCFelicaStopPolling function can stop searching FeliCa cards if NFCFelicaPolling function is carried out without specifying the callback function. Calling Sequence [C++] int NFCFelicaStopPolling() [Visual Basic] Public Shared Function NFCFelicaStopPolling() As Int32 [C#] Public static Int32 NFCFelicaStopPolling()

Parameters None Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error

14

3.5 NFCFelicaGetCardResponse This function retrieves response information about activated FeliCa cards. The function can retrieve response information after NFCFelicaPolling function has been carried out. The response information is stored once in the driver upon successful activation of FeliCa card. The function then retrieves the information from the driver. In the Device Emulator, the function checks parameters only. Calling Sequence [C++] int NFCFelicaGetCardResponse( BYTE *pIDm, BYTE *pPMm, DWORD *pSystemCode, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaGetCardResponse( ByVal pIDm As Byte(), _ ByVal pPMm As Byte(), _ ByRef pSystemCode As Int32, _ ByVal dwReserved As Int32, _ ) As Int32 [C#] Public static Byte[] Byte[] Ref Int32 Int32 )

Int32 NFCFelicaGetCardResponse( pIDm, pPMm, dwSystemCode, dwReserved

Parameters pIDm Retrieves the IDm of successfully activated FeliCa card. Specify a pointer with 2-byte area. pPMm Retrieves the PMm of successfully activated FeliCa card. Specify a pointer with 1-byte area. pSystemCode Retrieves the system code of successfully activated FeliCa card. Specify a pointer with 7-byte area. 15

dwReserved This parameter is not supported in the current version. Specify '0'. Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error

16

3.6 NFCFelicaRadioOff This function terminates radio wave transmission by the NFC module. Calling Sequence [C++] int NFCFelicaRadioOff() [Visual Basic] Public Shared Function NFCFelicaRadioOff() As Int32 [C#] Public static Int32 NFCFelicaRadioOff()

Parameters None Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_ERROR_MODULE : No response from the module. In the Device Emulator, the value is not returned.

17

3.7 NFCFelicaRead This function retrieves the specified service code and block number from activated FeliCa cards. Data can only be retrieved from areas accessible without authentication. In the Device Emulator, the function checks parameters only. Calling Sequence [C++] int NFCFelicaRead( DWORD dwServiceCode, DWORD dwBlockNumber, BYTE *pData, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaRead( ByVal dwServiceCode As Int32, _ ByVal dwBlockNumber As Int32, _ ByRef pData As Byte(), _ ByVal dwReserved As Int32 _ ) As Int32 [C#] Public static Int32 Int32 Byte[] Int32 )

Int32 NFCFelicaRead( dwServiceCode, dwBlockNumber, pData, dwReserved

Parameters dwServiceCode Specifies the service code in the range of 0x0000 to 0xFFFF for position to retrieve. dwBlockNumber Specifies the block number in the range of 0 or any number greater than 0 for position to retrieve. pData Retrieves the block data. Specify a pointer with 16-byte area. dwReserved This parameter is not supported in the current version. Specify '0'. 18

Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error NFC_ERROR_TIMEOUT : Timeout error NFC_NOT_ACTIVATION : Card not activated error. In the Device Emulator, the value is not returned. NFC_ERROR_MODULE : No response from the module. In the Device Emulator, the value is not returned. NFC_ERROR_SUSPEND : Terminal OFF error. In the Device Emulator, the value is not returned. NFC_ERROR_AUTOOFF : Radio wave automatic stop error. In the Device Emulator, the value is not returned.

19

3.8 NFCFelicaWrite This function writes the specified service code and block number into activated FeliCa cards. Data can be only written into areas accessible without authentication. In the Device Emulator, the function checks parameters only. Calling Sequence [C++] int NFCFelicaWrite( DWORD dwServiceCode, DWORD dwBlockNumber, BYTE *pData, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaWrite( ByVal dwServiceCode As Int32, _ ByVal dwBlockNumber As Int32, _ ByRef pData As Byte(), _ ByVal dwReserved As Int32 _ ) As Int32 [C#] Public static Int32 Int32 Byte[] Int32 )

Int32 NFCFelicaWrite( dwServiceCode, dwBlockNumber, pData, dwReserved

Parameters dwServiceCode Specifies the service code in the range of 0x0000 to 0xFFFF for position to write. dwBlockNumber Specifies the block number in the range of 0 or any number greater than 0 for position to write. pData Specifies the block data to write. Specify a pointer with 16-byte area. dwReserved This parameter is not supported in the current version. Specify '0'. 20

Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error NFC_ERROR_TIMEOUT : Timeout error NFC_NOT_ACTIVATION : Card not activated error. In the Device Emulator, the value is not returned. NFC_ERROR_MODULE : No response from the module. In the Device Emulator, the value is not returned. NFC_ERROR_SUSPEND : Terminal OFF error. In the Device Emulator, the value is not returned. NFC_ERROR_AUTOOFF : Radio wave automatic stop error. In the Device Emulator, the value is not returned.

21

3.9 NFCFelicaSetEventNotification This function sets up notification method, with window message or event, of timing for the radio wave automatic stop. • Window message notification The message is sent to the window handle that specifies the window message of 'WM_NFC_AUTORADIOOFF( WM_USER + 0x580 )'. • Event notification The event issued when the radio wave is automatically stopped is 'NFCEventAutoRadioOff'. In Windows CE operating system, specify TEXT('NFCEventAutoRadioOff') in program because names are formed in Unicode. Calling Sequence [C++] int NFCFelicaSetEventNotification( DWORD dwMode ) [Visual Basic] Public Shared Function NFCFelicaSetEventNotification( ByVal dwMode As Int32 _ ) As Int32 [C#] Public static Int32 NFCFelicaSetEventNotification( Int32 dwMode )

Parameters dwMode Specifies the timing notification method for radio wave automatic stop. NFC_DISABLE : Notification disabled (default) NFC_MESSAGE : Window message notification NFC_EVENT : Event notification Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error

22

3.10 NFCFelicaGetEventNotification This function retrieves the timing notification method for the radio wave automatic stop. Calling Sequence [C++] int NFCFelicaGetEventNotification( DWORD *pMode ) [Visual Basic] Public Shared Function NFCFelicaGetEventNotification( ByRef pMode As Int32 _ ) As Int32 [C#] Public static Int32 NFCFelicaGetEventNotification( ref Int32 pMode )

Parameters pMode Retrieves the timing notification method for radio wave automatic stop. Refer to NFCFelicaSetEventNotification function for the values to retrieve. Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error

23

3.11 NFCFelicaSetAutoRadioOff This function sets up a period of time until when transmission of radio wave is automatically stopped. Calling Sequence [C++] int NFCFelicaSetAutoRadioOff( DWORD dwTimeout ) [Visual Basic] Public Shared Function NFCFelicaSetAutoRadioOff( ByVal dwTimeout As Int32 _ ) As Int32 [C#] Public static Int32 NFCFelicaSetAutoRadioOff( Int32 dwTimeout )

Parameters Timeout Specifies a period of time in the range of 100 to 60,000 (milliseconds) until when transmission of radio wave is automatically stopped. The default is 1,000. Specifying "0" in this parameter disables the radio wave automatic stop. Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error

24

3.12 NFCFelicaGetAutoRadioOff This function retrieves the time period until when transmission of radio wave is stopped automatically. Calling Sequence [C++] int NFCFelicaGetAutoRadioOff( DWORD *pTimeout ) [Visual Basic] Public Shared Function NFCFelicaGetAutoRadioOff( ByRef pTimeout As Int32 _ ) As Int32 [C#] Public static Int32 NFCFelicaGetAutoRadioOff( ref Int32 pTimeout )

Parameters Timeout Retrieves the time period for radio wave automatic stop. Refer to NFCFelicaSetAutoRadioOff function for the values to retrieve. Return Values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error

25

3.13 NFCFelicaSetPollingMode This function sets up IC card search method. [C++] int NFCFelicaSetPollingMode( DWORD dwMode, DWORD dwNum, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaSetPollingMode( ByRef dwMode As Int32, _ ByRef dwNum As Int32, _ ByRef dwReserved As Int32 _ ) As Int32 [C#] public static Int32 NFCFelicaSetPollingMode( Int32 dwMode, Int32 dwNum, Int32 dwReserved )

Parameters dwMode Set up IC card search method. NFC_PLMODE_NORMAL NFC_PLMODE_MULTISTEP NFC_PLMODE_MULTISTEP2 NFC_PLMODE_PACKAGE

Normal (Default） Multistep Multistep 2 Package

dwNum Set up number of multistep scanning. Setting range is different by search method. Case of NFC_PLMODE_NORMAL Specify 0 Case of NFC_PLMODE_MULTISTEP 2 to 100 Case of NFC_PLMODE_MULTISTEP2 2 to 100 Case of NFC_PLMODE_PACKAGE Specify 2 dwReserved This parameter is not supported in the current version. Specify '0'. Return values The following values are returned. NFC_OK : Normal termination 26

NFC_NOT_DEVICE NFC_POF NFC_PRM

: NFC driver error. In the Device Emulator, the value is not returned. : Unopened error : Parameter error

Notes IC card search method Normal One IC card will be started by one search operation. Different IC cards will be started continuously until specified Multistep / number.(see note) Multistep 2 (Only one IC card will be started by one search operation.） Same type several pieces IC card will be started by one search Package operation. Search operation will be continued until specified number. Note: Started card's Uid will be recorded in driver history at each IC card started. Double starting will be prevent by compared this history and started IC card. This history record will be clear by started specified IC card, passed timeout period, call back function return FALSE, execute NFCFelicaStopPolling function.

27

3.14 NFCFelicaGetPollingMode This function retrieves IC card search method [C++] int NFCFelicaGetPollingMode( DWORD *pdwMode, DWORD *pdwNum, DWORD *pdwReserved ) [Visual Basic] Public Shared Function NFCFelicaGetPollingMode( ByRef pdwMode As Int32, _ ByRef pdwNum As Int32, _ ByRef pdwReserved As Int32 _ ) As Int32 [C#] public ref ref ref )

static Int32 NFCFelicaGetPollingMode( Int32 pdwMode, Int32 pdwNum, Int32 pdwReserved

Parameters pMode Retrieves IC card search method. About retrieved detail value, refer NFCFelicaSetPollingMode function. pMode Retrieves number of multistep operation. About retrieved detail value, refer NFCFelicaSetPollingMode function. pMode This parameter is not supported in the current version. Specify NULL. Return values The following values are returned. NFC_OK : Normal termination NFC_NOT_DEVICE : NFC driver error. In the Device Emulator, the value is not returned. NFC_POF : Unopened error NFC_PRM : Parameter error

28

3.15 NFCFelicaGetCardResponseEx This function retrieves response information of activated smart cards When you execute this function after succeed NFCFelicaPolling function by set up package mode by NFCFelicaSetPollingMode, retrieved response information of started several pieces IC cards. Response information will be recorded in driver at IC card start sccess timing, and retrieve response information in driver by this function. In the Device Emulator, the function checks parameters only. [C++] int NFCFelicaGetCardResponseEx( BYTE *pbyIDm, BYTE *pbyPMm, DWORD *pdwSystemCode, DWORD *pdwDiscoveredNum, DWORD *pdwReserved ) [Visual Basic] Public Shared Function NFCFelicaGetCardResponseEx( ByVal pbyIDm As Byte(), _ ByVal pbyPMm As Byte(), _ ByRef pdwSystemCode As Int32, _ ByRef pdwDiscoveredNum As Int32, _ ByRef pdwReserved As Int32 _ ) As Int32 [C#] public static Int32 NFCFelicaGetCardResponseEx( Byte[] pbyIDm, Byte[] pbyPMm, ref Int32 pdwDiscoveredNum, ref Int32 pdwDiscoveredNum, ref Int32 pdwReserved )

Parameters pIDm Retrieves IDm from smart card. Secure (8 x dwNum in NFCFelicaSetPollingMode) bytes of the buffer size or more to retrieve. Data format 8 bytes First card IDm

8 bytes Second card IDm

29

pPMm Retrieves PMm from smart card. Secure (8 x dwNum in NFCFelicaSetPollingMode) bytes of the buffer size or more to retrieve. Data format 8 bytes First card PMm

8 bytes Second card PMm

pSystemCode Retrieves System Code from smart card. Secure (4 x dwNum in NFCFelicaSetPollingMode) bytes of the buffer size or more to retrieve. Data format 4 bytes

4 bytes Second card First card System Code System Code

pDiscoveredNum Retrieves number of IC card which was scceed to start by NFCFelicaPolling function. Maximum value which is available to set in dwTargetNo of NFCFelicaRead function and NFCFelicaWrite function, etc is value which is retrieved in this parameter. Ex) Case of retrieve 2 by this parameter Specified available value in dwTargetNo of NFCFelicaRead function is 0 to 1. pReserved This parameter is not supported in the current version. Specify NULL. Return values The following values are returned. NFC_OK

: Normal termination : NFC driver error. In the Device Emulator, the value is NFC_NOT_DEVICE not returned. NFC_POF : Unopened error NFC_PRM : Parameter error : Card inactivation error NFC_NOT_ACTIVATION Does not occur in the Device Emulator NFC_ERROR_INVALID_ACCESS : Run error during card polling

30

3.16 NFCFelicaSamOpen This function turns on the SAM card controller and authorizes (opens) SAM driver communication. [C++] int NFCFelicaSamOpen() [Visual Basic] Public Shared Function NFCFelicaSamOpen() As Int32 [C#] public static Int32 NFCFelicaSamOpen()

Parameters None Return values The following values are returned. NFC_OK : Normal termination NFC_PON : Opened (see note) : SAM driver error NFC_NOT_DEVICE Does not occur in the Device Emulator : Module not responding error NFC_ERROR_MODULE Does not occur in the Device Emulator Note: When this function is called up twice or more in the same process, it returns a normal termination

31

3.17 NFCFelicaSamClose This function turns off the SAM card controller and prohibits (closes) SAM driver communication. [C++] int NFCFelicaSamClose() [Visual Basic] Public Shared Function NFCFelicaSamClose() As Int32 [C#] public static Int32 NFCFelicaSamClose()

Parameters None Return values The following values are returned. NFC_OK : Normal termination : SAM driver error NFC_NOT_DEVICE Does not occur in the Device Emulator

32

3.18 NFCFelicaSamPowerUp This function turns on the SAM card of the assigned slot number. [C++] int NFCFelicaSamPowerUp( DWORD dwSlotNumber, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaSamPowerUp( _ ByVal dwSlotNumber As Int32, _ ByVal dwReserved As Int32 _ ) As Int32 [C#] public static Int32 NFCFelicaSamPowerUp( Int32 dwSlotNumber, Int32 dwReserved )

Parameters dwSlotNumber Assigns the number of the card slot in which the SAM card subject to communication is inserted (1 - no. of card slots) dwReserved This parameter is not used in the current version so assign a value of '0'. Return values The following values are returned. NFC_OK

: Normal termination : NFC driver error Does not occur in the Device Emulator : Unopened error : Parameter error : SAM card not inserted error : Module not responding error : Anomalous card response error

NFC_NOT_DEVICE NFC_POF NFC_PRM NFC_ERROR_NOCARD NFC_ERROR_MODULE NFC_ERROR_RESPONSE

33

3.19 NFCFelicaSamPowerDown This function turns off the SAM card of the assigned slot number. [C++] int NFCFelicaSamPowerDown( DWORD dwSlotNumber, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaSamPowerDown( _ ByVal dwSlotNumber As Int32, _ ByVal dwReserved As Int32 _ ) As Int32 [C#] public static Int32 NFCFelicaSamPowerDown( Int32 dwSlotNumber, Int32 dwReserved )

Parameters dwSlotNumber Assigns the number of the card slot in which the SAM card subject to communication is inserted (1 - no. of card slots) dwReserved This parameter is not used in the current version so assign a value of '0'. Return values The following values are returned. NFC_OK

: Normal termination : NFC driver error Does not occur in the Device Emulator : Unopened error : Parameter error : SAM card not inserted error : Module not responding error : Anomalous card response error

NFC_NOT_DEVICE NFC_POF NFC_PRM NFC_ERROR_NOCARD NFC_ERROR_MODULE NFC_ERROR_RESPONSE

34

3.20 NFCFelicaSamAuthentication This function performs mutual authentication of the Felica Library and SAM card (RC-S251). If mutual authentication is successful, the NFCFelicaAuthentication, NFCFelicaReadWithEncryption, and NFCFelicaWriteWithEncryption functions become available. Subsequently executing this function once more resets the number of communications with the SAM card. [C++] int NFCFelicaSamAuthentication( DWORD dwSlotNumber, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaSamAuthentication( _ ByVal dwSlotNumber As Int32, _ ByVal dwReserved As Int32 _ ) As Int32 [C#] public static Int32 NFCFelicaSamAuthentication( Int32 dwSlotNumber, Int32 dwReserved )

Parameters dwSlotNumber Assigns the number of the card slot in which the SAM card subject to communication is inserted (1 ‒ no. of card slots) dwReserved This parameter is not used in the current version so assign a value of '0'. Return values The following values are returned. NFC_OK

: Normal termination : NFC driver error Does not occur in the Device Emulator : Unopened error : Parameter error : SAM card not inserted error : SAM card not activated error : Timeout error : Terminal power off error

NFC_NOT_DEVICE NFC_POF NFC_PRM NFC_ERROR_NOCARD NFC_ERROR_ACTIVATION NFC_ERROR_TIMEOUT NFC_ERROR_SUSPEND 35

: Anomalous card response error

NFC_ERROR_RESPONSE Caution

If the terminal is turned off after successful mutual authentication with this function, the authorized state is reset when terminal power is restored and the terminal returns to the pre-authorized state. Addendum • Encryption This function performs unencrypted mutual authentication of the Felica Library and SAM card (RC-S251). Please therefore set the encryption method in the SAM card communication settings to "Disable CBC off". Refer to the SAM card manual for details. • Number of communications When the number of communications with the SAM card (RC-S251) exceeds 65,535 times, communication with the SAM card is disabled and the NFCFelicaAuthentication, NFCFelicaReadWithEncryption, and NFCFelicaWriteWithEncryption functions return the valueNFC_ERROR_COUNT. When this occurs, execute this function to clear the number of communications.

36

3.21 NFCFelicaAuthentication This function performs mutual authentication of the FeliCa card and SAM card. If mutual authentication is successful, the FeliCa card security domain can be accessed. [C++] int NFCFelicaAuthentication( DWORD dwSlotNumber, DWORD dwSystemCode, WORD wSystemKeyVer, BYTE byAreaNum, BYTE *pbyAreaCode, BYTE byServiceNum, BYTE *pbyServiceCode, DWORD dwTargetNo, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaAuthentication( _ ByVal dwSlotNumber As Int32, _ ByVal dwSystemCode As Int32, _ ByVal wSystemKeyVer As UInt16, _ ByVal byAreaNum As Byte, _ ByVal pbyAreaCode As Byte(), _ ByVal byServiceNum As Byte, _ ByVal pbyServiceCode As Byte(), _ ByVal dwTargetNo As Int32, _ ByVal dwReserved As Int32 _ ) As Int32 [C#] public static Int32 NFCFelicaAuthentication( Int32 dwSlotNumber, Int32 dwSystemCode, UInt16 wSystemKeyVer, byte byAreaNum, Byte[] pbyAreaCode, byte byServiceNum, Byte[] pbyServiceCode, Int32 dwTargetNo, Int32 dwReserved )

Parameters

37

dwSlotNumber Assigns the number of the card slot in which the SAM card subject to communication is inserted (1 ‒ no. of card slots) dwSystemCode Assigns the system code fetched by the NFCFelicaGetCardResponse or NFCFelicaGetCardResponseEx functions. wSystemKeyVer Assigns the system key version (little endian). byAreaNum Assigns the area number (1 - 8). pbyAreaCode Assigns the area code/area key version list (little endian). byServiceNum Assigns the service number (1 - 8). pbyServiceCode Assigns the service code/service key version list (little endian). dwTargetNo Assign the card number of the smart card you want to communicate with. In most cases you should set a value of '0'. Alternatively, if multiple smart cards have been successfully activated using the NFCFelicaPolling function, assign a value of 1 or more to communicate with the second or subsequent card. dwReserved This parameter is not used in the current version so assign a value of '0'. Return values The following values are returned. NFC_OK

: Normal termination : NFC driver error Does not occur in the Device Emulator : Unopened error : Parameter error : SAM card not inserted error : SAM card not activated error : Timeout error : Terminal power off error : Anomalous card response error : Maximum number of SAM card communications exceeded

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 38

Usage examples SAM slot number: 1 System code/system key version: 0018h/0001h Area code/area key version: 0000h/0001h Service code/service key version: 1020h/0001h dwSlotNumber dwSystemCode wSystemVer byAreaNum pbyAreaCode

= = = = =

0x00000001; 0x00001800; 0x0100; 0x01; {0x00, 0x00, 0x01, 0x00};

byServiceNum = 0x01; pbyServiceCode = {0x20, 0x10, 0x01, 0x00}; dwTargetNo dwReserved

= 0x00000000; = 0x00000000;

39

// Area code 2 bytes // Key version 2 bytes // Service code 2 bytes // Key version 2 bytes

3.22 NFCFelicaReadWithEncryption This function reads the FeliCa security domain data. [C++] int NFCFelicaReadWithEncryption( DWORD dwSlotNumber, BYTE byBlockNum, BYTE *pbyBlockList, BYTE *pbyData, BYTE *pbyActualNum, DWORD dwTargetNo, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaReadWithEncryption( _ ByVal dwSlotNumber As Int32, _ ByVal byBlockNum As Byte, _ ByVal pbyBlockList As Byte(), _ ByVal pbyData As Byte(), _ ByRef pbyServiceCode As Byte, _ ByVal dwTargetNo As Int32, _ ByVal dwReserved As Int32 _ ) As Int32 [C#] public static Int32 NFCFelicaReadWithEncryption( Int32 dwSlotNumber, Byte byBlockNum, Byte[] pbyBlockList, Byte[] pbyData, ref Byte pbyActualNum, DWORD dwTargetNo, DWORD dwReserved )

Parameters dwSlotNumber Assigns the number of the card slot in which the SAM card subject to communication is inserted (1 ‒ no. of card slots) byBlockNum Assigns the number of blocks to be read (1 - 12).

40

pbyBlockList Assigns the list of the block to be read. Up to 36 bytes can be assigned. pbyData Retrieves the read block data (16 bytes × number of blocks) pbyActualNum Retrieves the read block data. dwTargetNo Assign the card number of the smart card you want to communicate with. In most cases you should set a value of '0'. Alternatively, if multiple smart cards have been successfully activated using the NFCFelicaPolling function, assign a value of 1 or more to communicate with the second or subsequent card. dwReserved This parameter is not used in the current version so assign a value of '0'. Return values The following values are returned. NFC_OK

: Normal termination : NFC driver error Does not occur in the Device Emulator : Unopened error : Parameter error : SAM card not inserted error : SAM card not activated error : Timeout error : Terminal power off error : Anomalous card response error : Maximum number of SAM card communications exceeded

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 Usage examples

When reading a single block of data (16 bytes) for block number 0: /* Input */ dwSlotNumber byBlockNum pbyBlockList dwTargetNo dwReserved

= = = = =

0x00000001; 0x01; {0x80, 0x00} 0x00000000; 0x00000000;

// When block no. is 0

/* Output pbyData

*/ = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F}; pbyActualNum = 0x01;

41

3.23 NFCFelicaWriteWithEncryption This function writes the FeliCa security domain data. [C++] int NFCFelicaWriteWithEncryption( DWORD dwSlotNumber, BYTE byBlockNum, BYTE *pbyBlockList, BYTE *pbyData, DWORD dwTargetNo, DWORD dwReserved ) [Visual Basic] Public Shared Function NFCFelicaWriteWithEncryption( _ ByVal dwSlotNumber As Int32, _ ByVal byBlockNum As Byte, _ ByVal pbyBlockList As Byte(), _ ByVal pbyData As Byte(), _ ByVal dwTargetNo As Int32, _ ByVal dwReserved As Int32 _ ) As Int32 [C#] public static Int32 NFCFelicaWriteWithEncryption( Int32 dwSlotNumber, Byte byBlockNum, Byte[] pbyBlockList, Byte[] pbyData, DWORD dwTargetNo, DWORD dwReserved )

Parameters dwSlotNumber Assigns the number of the card slot in which the SAM card subject to communication is inserted (1 ‒ no. of card slots) byBlockNum Assigns the number of blocks to be written (1 - 8). pbyBlockList Assigns the list of blocks to be written. Up to 24 bytes can be assigned.

42

pbyData Assigns the block data to be retrieved (16 bytes × number of blocks) dwTargetNo Assign the card number of the smart card you want to communicate with. In most cases you should set a value of '0'. Alternatively, if multiple smart cards have been successfully activated using the NFCFelicaPolling function, assign a value of 1 or more to communicate with the second or subsequent card. dwReserved This parameter is not used in the current version so assign a value of '0'. Return values The following values are returned. NFC_OK

: Normal termination : NFC driver error Does not occur in the Device Emulator : Unopened error : Parameter error : SAM card not inserted error : SAM card not activated error : Timeout error : Terminal power off error : Anomalous card response error : Maximum number of SAM card communications exceeded

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 Usage examples

When writing a single block of data (16 bytes) for block number 0: dwSlotNumber byBlockNum pbyBlockList pbyData dwTargetNo dwReserved

= = = =

0x00000001; 0x01; {0x80, 0x00} // When block no. is 0 {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F}; = 0x00000000; = 0x00000000;

43

4. Notes to Programming 4.1 Notification for Radio Wave Stop 4.1.1 Using Window Message Notification Terminating Radio Wave Transmission Manually 1. If you receive WM_CREATE message, carry out NFCFelicaOpen function to set the mode in "wait to read" state. 2. If you receive WM_COMMAND or WM_KEYDOWN message etc., carry out NFCFelicaPolling function to search FeliCa card and activate it that is located in the communication range. 3. When you have successfully activated the FeliCa card and if you need to retrieve its detailed information, carry out NFCFelicaGetCardResponse function to retrieve the card response information (at your will). 4. Initiate communication with the FeliCa card. See note. 5. When communication with the FeliCa card is complete, carry out NFCFelicaRadioOff function to terminate radio wave output. 6. If you receive WM_CLOSE message, carry out NFCFelicaClose function to set the mode in "read prohibit" state. Note: Refer to Chapter 4.2 "Communicating with FeliCa Cards" for detail on communicating with FeliCa cards.

44

Figure 4.1

45

Stopping Radio Wave Automatically and Issuing Notification of Stop Timing 1. If you receive WM_CREATE message, carry out NFCFelicaOpen function to set the mode in "wait to read" state. 2. Carry out NFCFelicaSetEventNotification function to set the window message notification effect. 3. Carry out NFCFelicaSetAutoRadioOff function to set the radio wave automatic stop effect. 4. If you receive WM_COMMAND or WM_KEYDOWN message etc., carry out NFCFelicaPolling function to search FeliCa card and activate it that is located in the communication range. 5. When you have successfully activated the FeliCa card and if you need to retrieve its detailed information, carry out NFCFelicaGetCardResponse function to retrieve the card response information (at your will). 6. Initiate communication with the FeliCa card. See note. 7. When communication with the FeliCa card is complete, carry out NFCFelicaRadiOff function to terminate radio wave output (even if radio wave output does not stop, it will stop automatically once communication has not been performed for a certain time period). 8. You can receive WM_NFC_AUTORADIOOFF(WM_USER + 0x580) that automatic termination of radio wave output occurs. In this case, it is possible to notify the user that radio wave output has stopped automatically. 9. If you receive WM_CLOSE message, carry out NFCFelicaClose function to set the mode in "read prohibit" state. Note: Refer to Chapter 4.2 "Communicating with FeliCa Cards" for detail on communicating with FeliCa cards.

46

Figure 4.2

47

4.1.2 Using Event Notification Terminating Radio Wave Transmission Manually 1. When initiating communication process, carry out NFCFelicaPolling function to search FeliCa card and activate it that is located in the communication range. 2. When you have successfully activated the FeliCa card and if you need to retrieve its detailed information, carry out NFCFelicaGetCardResponse function to retrieve the card response information (at your will). 3. Initiate communication with the FeliCa card. See note. 4. When communication with the FeliCa card is complete, carry out NFCFelicaRadioOff function to terminate radio wave output. 5. When closing the application, carry out NFCFelicaClose function to set the mode in "read prohibit" state. Note: Refer to Chapter 4.2 "Communicating with FeliCa Cards" for detail on communicating with FeliCa cards.

When initiating application

When closing application

When communicating with FeliCa card

Figure 4.3

48

Stopping Radio Wave Automatically and Issuing Notification of Stop Timing Main Thread 1. When initiating the application, carry out CreateEvent function to create event handle of notification of radio wave automatic stop timing. 2. Carry out CreateThread function to create a thread to monitor the radio wave automatic stop. 3. Carry out NFCFelicaOpen function to set the mode in "wait to read" state. 4. Carry out NFCFelicaSetEventNotification function to set the event notification effect. 5. Carry out NFCFelicaSetAutoRadioOff function to set the radio wave automatic stop effect. 6. When initiating communication process, carry out NFCFelicaPolling function to search FeliCa card and activate it that is located in the communication range. 7. When you have successfully activated the FeliCa card and if you need to retrieve its detailed information, carry out NFCFelicaGetCardResponse function to retrieve the card response information (at your will). 8. Initiate communication with the FeliCa card. See note. 9. When communication with the FeliCa card is complete, carry out NFCFelicaRadioOff function to terminate radio wave output (even if radio wave output does not stop, it will stop automatically if communication has not been performed for a certain period of time). 10. When closing the application, carry out SetEvent function to issue a notification to the thread that monitors the radio wave automatic stop. 11. Close the event handle and thread handle. 12. Carry out NFCFelicaClose function to set the mode in "read prohibit" state. Note: Refer to Chapter 4.2 "Communicating with FeliCa Cards" for detail on communicating with FeliCa cards.

49

When initiating application

When closing application

Figure 4.4

50

When communicating with FeliCa card

NFC Felica thread 1. Carry out WaitForSingleObject function to wait for event handle of the radio wave automatic stop notification timing. 2. When you receive a notification event upon closing the application, close monitoring on the radio wave automatic stop. 3. When you receive a notification event on other occasions, it is possible to issue a notification that the radio wave output has stopped automatically.

Figure 4.5

51

4.2 Communicating with FeliCa Cards Below is the communication procedure for card described for "Communication with FeliCa Cards". 1. Carry out NFCFelicaRead or NFCFelicaWrite function.

Figure 4.6

52

4.3 About search method Use of Multi Step mode Communicate with FeliCa card 1. By using NFCFelicaSetPollingMode function, you should specify Multi Step mode(NFC_PLMODE_MULTISTEP) as search method and you should specify continuous scanning card number (CARD_NUM) as number of card. 2. Set iCount=0 3. If iCount