NXP NFC Reader Library  v4.040.05.011646
NFC Forum Type 4A Card Emulation

This component implements the card emulation of NFC Forum Type 4A Tag. More...

Collaboration diagram for NFC Forum Type 4A Card Emulation:

Modules

 Component : Software
 

Macros

#define PHCE_T4T_CC_FILE_ID   0xE103U
 CC (Capability Container) file ID as per NFC Forum Specification.
 

Typedefs

typedef phStatus_t(* phceT4T_AppCallback_t) (uint8_t bState, uint16_t wRxOption, uint8_t *pRxData, uint16_t wRxDataLen, uint16_t *pStatusWord, uint8_t **ppTxData, uint16_t *pTxDataLen)
 Application callback to handle proprietary commands and UPDATE BINARY. This should be implemented by the user if proprietary means are needed to write to NDEF file and/or proprietary file(s) which may be on EEPROM or to handle proprietary commands. More...
 

Functions

phStatus_t phceT4T_SetElementaryFile (void *pDataParams, uint8_t bFileType, uint8_t *pFile, uint16_t wFileId, uint32_t dwFileSize, uint32_t dwContentLen)
 Set a supported Elementary File (EF). More...
 
phStatus_t phceT4T_Activate (void *pDataParams)
 Activate T4T card emulation functionality. More...
 
phStatus_t phceT4T_ProcessCmd (void *pDataParams, uint16_t wOption, uint8_t *pRxData, uint16_t wRxDataLen, uint16_t *pStatusWord, uint8_t **ppTxData, uint16_t *pTxDataLen)
 Validate and process the received C-APDU (Command Application Protocol Data Unit). More...
 
phStatus_t phceT4T_AppProcessCmd (void *pDataParams, phceT4T_AppCallback_t pAppCallback)
 Application process command. More...
 
phStatus_t phceT4T_GetSelectedFileInfo (void *pDataParams, uint16_t *pFileId, uint8_t **ppFile, uint32_t *pFileSize, uint8_t *pWriteAccess, uint32_t *pFileOffset)
 Get information about currently selected file. More...
 
phStatus_t phceT4T_Reset (void *pDataParams)
 Reset the tag's state variables. More...
 
phStatus_t phceT4T_SetConfig (void *pDataParams, uint16_t wConfig, uint16_t wValue)
 Set value of the specified configurationidentifier". More...
 
phStatus_t phceT4T_GetConfig (void *pDataParams, uint16_t wConfig, uint16_t *pValue)
 Get value of the specified configurationidentifier". More...
 

Tag States

#define PHCE_T4T_STATE_NONE   0x00U
 Initial state. More...
 
#define PHCE_T4T_STATE_CC_FILE_CREATED   0x01U
 CC (Capability container) file created. More...
 
#define PHCE_T4T_STATE_NDEF_FILE_CREATED   0x02U
 NDEF file created. More...
 
#define PHCE_T4T_STATE_NDEF_APP_SELECTED   0x03U
 NDEF application selected. More...
 
#define PHCE_T4T_STATE_FILE_SELECTED   0x04U
 File selected. More...
 
#define PHCE_T4T_STATE_FILE_READ   0x05U
 File read. More...
 
#define PHCE_T4T_STATE_FILE_UPDATE   0x06U
 File update. More...
 
#define PHCE_T4T_STATE_PROPRIETARY   0x07U
 Proprietary command received. More...
 

Receive Options

These options are given as input to phceT4T_ProcessCmd and application callback (if used) to indicate if the received data (C-APDU) given to it for processing is partial or complete.

The data (C-APDU) to be processed is received using phpalI14443p4mC_Receive.

#define PHCE_T4T_RXDEFAULT   0x00U
 Default option. More...
 
#define PHCE_T4T_RXCHAINING_BUFFER_FIRST   0x01U
 First part of partial receive data. More...
 
#define PHCE_T4T_RXCHAINING_BUFFER_CONT   0x02U
 Subsequent part of partial receive data. More...
 
#define PHCE_T4T_RXCHAINING_BUFFER_LAST   0x03U
 Last chunk of receive data. More...
 

Return Status

Custom return status codes of T4T card emulation layer.

#define PH_CE_T4T_FAILURE   (PH_ERR_CUSTOM_BEGIN + 0x00U)
 Failure. More...
 
#define PH_CE_T4T_SELECT   (PH_ERR_CUSTOM_BEGIN + 0x01U)
 SELECT command received. More...
 
#define PH_CE_T4T_READ_BINARY   (PH_ERR_CUSTOM_BEGIN + 0x02U)
 READ BINARY command received. More...
 
#define PH_CE_T4T_UPDATE_BINARY   (PH_ERR_CUSTOM_BEGIN + 0x03U)
 UPDATE BINARY command received. More...
 
#define PH_CE_T4T_PROPRIETARY   (PH_ERR_CUSTOM_BEGIN + 0x04U)
 Proprietary command received. More...
 
#define PH_CE_T4T_INVALID_STATE   (PH_ERR_CUSTOM_BEGIN + 0x05U)
 Tag in invalid state to execute the requested operation. More...
 

File Types

File types to be specified in phceT4T_SetElementaryFile.

#define PHCE_T4T_FILE_CC   0x00U
 Capability Container (CC) File. More...
 
#define PHCE_T4T_FILE_NDEF   0x01U
 NFC Data Exchange Format (NDEF) File. More...
 
#define PHCE_T4T_FILE_PROPRIETARY   0x02U
 Proprietary File. More...
 

Configuration Types

These options shall be used along with phceT4T_SetConfig and phceT4T_GetConfig to configure Type 4A card emulation layer.

#define PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY   0x00U
 Enable/Disable handling of UPDATE BINARY inside card emulation layer. More...
 
#define PHCE_T4T_CONFIG_RECEIVE_PROPRIETARY   0x01U
 Enable/Disable support for proprietary command. More...
 
#define PHCE_T4T_CONFIG_NDEF_FILE_ID   0x02U
 Set/Get NDEF file ID. More...
 
#define PHCE_T4T_CONFIG_NDEF_FILE_READ_ACCESS   0x03U
 Set/Get NDEF file read access value. More...
 
#define PHCE_T4T_CONFIG_NDEF_FILE_WRITE_ACCESS   0x04U
 Set/Get NDEF file write access value. More...
 
#define PHCE_T4T_CONFIG_MLE   0x05U
 Set/Get value of MLe (Maximum data that can be read in one Read Binary command). More...
 
#define PHCE_T4T_CONFIG_MLC   0x06U
 Set/Get value of MLc (Maximum data that can be written in one Update Binary command). More...
 

Detailed Description

This component implements the card emulation of NFC Forum Type 4A Tag.

Implementation is based on NFC Forum Type 4 Tag Operation Specification version 2.0. SELECT, READ BINARY and UPDATE BINARY commands are supported as per NFC Type 4 Tag Operation Specification.

This layer follows a multi-threaded RTOS based design using one reader library thread and one application thread. Application thread along with application callback can be used for handling of UPDATE BINARY and proprietary commands.

A pictorial representation of reader library thread and application thread used for card emulation is shown below. Refer function documentation for more information.

hce_combined_threads.png

As UPDATE BINARY and proprietary commands are handled by the phceT4T_AppProcessCmd in application thread, application shall use some synchronization mechanism (like mutex or semaphore) as shown in the diagram to synchronize entry to and exit from phceT4T_Activate and phceT4T_AppProcessCmd.

Waiting Time eXtension (WTX) is handled internally by phceT4T_Activate in reader library thread. The reader library thread should be of high priority than the application thread for proper handling of WTX. In non RTOS single threaded environment this layer can be used with limited features, i.e. with no support for WTX.

Macro Definition Documentation

§ PHCE_T4T_STATE_NONE

#define PHCE_T4T_STATE_NONE   0x00U

Initial state.

State after Initialization of this layer.

§ PHCE_T4T_STATE_CC_FILE_CREATED

#define PHCE_T4T_STATE_CC_FILE_CREATED   0x01U

CC (Capability container) file created.

State after creation of CC (Capability Container) file PHCE_T4T_FILE_CC using phceT4T_SetElementaryFile.

§ PHCE_T4T_STATE_NDEF_FILE_CREATED

#define PHCE_T4T_STATE_NDEF_FILE_CREATED   0x02U

NDEF file created.

State after creation of NDEF file PHCE_T4T_FILE_NDEF using phceT4T_SetElementaryFile.

§ PHCE_T4T_STATE_NDEF_APP_SELECTED

#define PHCE_T4T_STATE_NDEF_APP_SELECTED   0x03U

NDEF application selected.

State after receiving a valid SELECT request to select NFC NDEF application.

§ PHCE_T4T_STATE_FILE_SELECTED

#define PHCE_T4T_STATE_FILE_SELECTED   0x04U

File selected.

State after receiving a valid SELECT request to select a file present inside the NDEF application.

§ PHCE_T4T_STATE_FILE_READ

#define PHCE_T4T_STATE_FILE_READ   0x05U

File read.

State after receiving a valid READ BINARY request.

§ PHCE_T4T_STATE_FILE_UPDATE

#define PHCE_T4T_STATE_FILE_UPDATE   0x06U

File update.

State after receiving a valid UPDATE BINARY request.

§ PHCE_T4T_STATE_PROPRIETARY

#define PHCE_T4T_STATE_PROPRIETARY   0x07U

Proprietary command received.

State after receiving a proprietary command (command with unsupported instruction byte).

§ PHCE_T4T_RXDEFAULT

#define PHCE_T4T_RXDEFAULT   0x00U

Default option.

Option specified in phceT4T_ProcessCmd or application callback when phpalI14443p4mC_Receive returns PH_ERR_SUCCESS and the whole received data (complete C-APDU) is given for processing.

§ PHCE_T4T_RXCHAINING_BUFFER_FIRST

#define PHCE_T4T_RXCHAINING_BUFFER_FIRST   0x01U

First part of partial receive data.

Option specified in phceT4T_ProcessCmd or application callback when phpalI14443p4mC_Receive returns with PH_ERR_SUCCESS_CHAINING for first time and this partial received data (first part of C-APDU) is given for processing. This option indicates that the received data is not complete and only first part of data is given for processing.

§ PHCE_T4T_RXCHAINING_BUFFER_CONT

#define PHCE_T4T_RXCHAINING_BUFFER_CONT   0x02U

Subsequent part of partial receive data.

Option specified in phceT4T_ProcessCmd or application callback when phpalI14443p4mC_Receive returns with PH_ERR_SUCCESS_CHAINING for second time or more and this partial received data (subsequent part of C-APDU) is given for processing. This option indicates that the received data is not complete and subsequent part of data is given for processing.

§ PHCE_T4T_RXCHAINING_BUFFER_LAST

#define PHCE_T4T_RXCHAINING_BUFFER_LAST   0x03U

Last chunk of receive data.

Option specified in phceT4T_ProcessCmd or application callback when phpalI14443p4mC_Receive returns with PH_ERR_SUCCESS after a PH_ERR_SUCCESS_CHAINING in previous receive and this partial received data is given for processing. This option indicates that it is last part of partial receive data.

§ PH_CE_T4T_FAILURE

#define PH_CE_T4T_FAILURE   (PH_ERR_CUSTOM_BEGIN + 0x00U)

Failure.

This status code is returned by phceT4T_ProcessCmd when an unsupported C-APDU (Command Application Protocol Data Unit) is given to it for processing. Supported C-APDUs are SELECT, READ BINARY, UPDATE BINARY and PROPRIETARY (commands with unsupported instruction byte).

§ PH_CE_T4T_SELECT

#define PH_CE_T4T_SELECT   (PH_ERR_CUSTOM_BEGIN + 0x01U)

SELECT command received.

This status code is returned by phceT4T_ProcessCmd when a valid SELECT command is given to it for processing and the file is successfully selected.

§ PH_CE_T4T_READ_BINARY

#define PH_CE_T4T_READ_BINARY   (PH_ERR_CUSTOM_BEGIN + 0x02U)

READ BINARY command received.

This status code is returned by phceT4T_ProcessCmd when a valid READ BINARY command is given to it for processing and the file is successfully read.

§ PH_CE_T4T_UPDATE_BINARY

#define PH_CE_T4T_UPDATE_BINARY   (PH_ERR_CUSTOM_BEGIN + 0x03U)

UPDATE BINARY command received.

This status code is returned by phceT4T_ProcessCmd when a valid UPDATE BINARY command is given to it for processing. The file will be updated by phceT4T_ProcessCmd if PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY is enabled else application shall update the file using phceT4T_AppProcessCmd or using application callback from application thread.

§ PH_CE_T4T_PROPRIETARY

#define PH_CE_T4T_PROPRIETARY   (PH_ERR_CUSTOM_BEGIN + 0x04U)

Proprietary command received.

This status code is returned by phceT4T_ProcessCmd when a proprietary command (command with unsupported instruction byte) is given to it for processing. If PHCE_T4T_CONFIG_RECEIVE_PROPRIETARY is enabled then proprietary command will be sent to application and application can handle it using callback, else unsupported instruction is returned as status to reader.

§ PH_CE_T4T_INVALID_STATE

#define PH_CE_T4T_INVALID_STATE   (PH_ERR_CUSTOM_BEGIN + 0x05U)

Tag in invalid state to execute the requested operation.

This status code is returned by phceT4T_GetSelectedFileInfo, phceT4T_SetConfig and phceT4T_GetConfig when card emulation layer is not in a valid state to execute these APIs.

§ PHCE_T4T_FILE_CC

#define PHCE_T4T_FILE_CC   0x00U

Capability Container (CC) File.

This is used in phceT4T_SetElementaryFile to set the CC file.

§ PHCE_T4T_FILE_NDEF

#define PHCE_T4T_FILE_NDEF   0x01U

NFC Data Exchange Format (NDEF) File.

This is used in phceT4T_SetElementaryFile to set the NDEF file.

§ PHCE_T4T_FILE_PROPRIETARY

#define PHCE_T4T_FILE_PROPRIETARY   0x02U

Proprietary File.

This is used in phceT4T_SetElementaryFile to set a proprietary file.

§ PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY

#define PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY   0x00U

Enable/Disable handling of UPDATE BINARY inside card emulation layer.

Default value is PH_OFF (disabled). Supported values are PH_ON and PH_OFF. If enabled, the UPDATE BINARY command is processed and file is updated by the phceT4T_ProcessCmd itself. If disabled, UPDATE BINARY command is only validated and data to be written to file is given to application thread (i.e. phceT4T_AppProcessCmd) to update the file.

§ PHCE_T4T_CONFIG_RECEIVE_PROPRIETARY

#define PHCE_T4T_CONFIG_RECEIVE_PROPRIETARY   0x01U

Enable/Disable support for proprietary command.

Default value is PH_OFF (disabled). Supported values are PH_ON and PH_OFF. If disabled, unsupported instruction status word is sent back to reader. If enabled, application can handle proprietary commands in application callback phceT4T_AppCallback_t of phceT4T_AppProcessCmd.

§ PHCE_T4T_CONFIG_NDEF_FILE_ID

#define PHCE_T4T_CONFIG_NDEF_FILE_ID   0x02U

Set/Get NDEF file ID.

Valid range is between 0001h to E101h, E104h to 3EFFh, 3F01h to 3FFEh and 4000h to FFFEh. NDEF file ID can be updated only after phceT4T_SetElementaryFile is executed for NDEF file PHCE_T4T_FILE_NDEF.

§ PHCE_T4T_CONFIG_NDEF_FILE_READ_ACCESS

#define PHCE_T4T_CONFIG_NDEF_FILE_READ_ACCESS   0x03U

Set/Get NDEF file read access value.

Default is 0x00 (unrestricted read access). Only 0x00 is the supported value as per NFC Forum Type 4 Tag specification. Other values are RFU.

This can be configured only after executing phceT4T_SetElementaryFile for CC file PHCE_T4T_FILE_NDEF.

§ PHCE_T4T_CONFIG_NDEF_FILE_WRITE_ACCESS

#define PHCE_T4T_CONFIG_NDEF_FILE_WRITE_ACCESS   0x04U

Set/Get NDEF file write access value.

Default is 0x00 (unrestricted write access). Supported values are 0x00 (write access) and 0xFF (no write access, read only). Other values are RFU as per NFC Forum Type 4 Tag Specification.

This can be configured only after executing phceT4T_SetElementaryFile for CC file PHCE_T4T_FILE_NDEF.

§ PHCE_T4T_CONFIG_MLE

#define PHCE_T4T_CONFIG_MLE   0x05U

Set/Get value of MLe (Maximum data that can be read in one Read Binary command).

Default is 0xFFFF. Supported values are from 0x000F - 0xFFFF. Maximum read data length of 0xFFFF is supported only with extended APDUs (Application protocol data units). For short APDUs a maximum read length of 0xFF is supported. This can be configured only after executing phceT4T_SetElementaryFile for CC file PHCE_T4T_FILE_CC.

For more info on short and extended APDUs refer ISO 7816-4 2005, Section 5.

§ PHCE_T4T_CONFIG_MLC

#define PHCE_T4T_CONFIG_MLC   0x06U

Set/Get value of MLc (Maximum data that can be written in one Update Binary command).

Default is 0xFFFF. Supported values are from 0x0001 - 0xFFFF. Maximum write data length of 0xFFFF is supported only with extended APDUs (Application protocol data units). For short APDUs a maximum write data length of 0xFF is supported. This can be configured only after executing phceT4T_SetElementaryFile for CC file PHCE_T4T_FILE_CC.

For more info on short and extended APDUs refer ISO 7816-4 2005, Section 5.

Typedef Documentation

§ phceT4T_AppCallback_t

typedef phStatus_t(* phceT4T_AppCallback_t) (uint8_t bState, uint16_t wRxOption, uint8_t *pRxData, uint16_t wRxDataLen, uint16_t *pStatusWord, uint8_t **ppTxData, uint16_t *pTxDataLen)

Application callback to handle proprietary commands and UPDATE BINARY. This should be implemented by the user if proprietary means are needed to write to NDEF file and/or proprietary file(s) which may be on EEPROM or to handle proprietary commands.

Application callback, if implemented shall be specified when calling phceT4T_AppProcessCmd from application thread. Otherwise a default implementation as provided in phceT4T_AppProcessCmd will execute.

For UPDATE BINARY command, data to be written to file and length of data to be written to file is given to callback in pRxData and wRxDataLen respectively. For proprietary commands whole C-APDU (Command application Protocol Data Unit) received from reader is given to callback.

R-APDU (Response Application Protocol Data Unit) to be send back to reader should be updated in ppTxData (data field of R-APDU) and pStatusWord (SW1 and SW2 of R-APDU).

Application callback can get the details of currently selected file using phceT4T_GetSelectedFileInfo.

Parameters
[in]bStateTag State indicating received command type (PHCE_T4T_STATE_FILE_UPDATE or PHCE_T4T_STATE_PROPRIETARY).
[in]wRxOptionReceive option indicating if received data (pRxData) is partial or complete.
[in]pRxDataData received from reader library thread.
[in]wRxDataLenLength of received data (length of pRxData).
[out]pStatusWordStatus Word to be sent (as part of R-APDU). For example set pStatusWord as 0x9000 when requested command is successfully completed.
[out]ppTxDataData to be transmitted (as part of R-APDU). If only status word (pStatusWord) needs to be send as response to reader, set this to NULL. For UPDATE BINARY command this should be set to NULL.
[out]pTxDataLenLength of data to be transmitted. Set this to 0 if data to be transmitted (ppTxData) is set to NULL.
Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INTERNAL_ERRORfor all failures.

Usage:

Application Callback (Sample Code):

phStatus_t AppCallback(
uint8_t bState,
uint16_t wRxOption,
uint8_t *pRxData,
uint16_t wRxDataLen,
uint16_t *pStatusWord,
uint8_t **ppTxData,
uint16_t *pTxDataLen
)
{
phStatus_t status;
uint16_t wSelectedFileId;
uint8_t *pSelectedFile;
uint32_t dwSelectedFileSize;
uint8_t bWriteAccess;
uint32_t dwFileOffset;
// UPDATE BINARY command handling
{
// Get Selected file info.
&sceT4T,
&wSelectedFileId,
&pSelectedFile,
&dwSelectedFileSize,
&bWriteAccess,
&dwFileOffset);
if((status & PH_ERR_MASK) == PH_ERR_SUCCESS)
{
// Update file. If specific methods are needed for writing file,
// use it here.
(void)memcpy(&pSelectedFile[dwFileOffset], pRxData, wRxDataLen);
// File update success, update out parameters.
*pStatusWord = 0x9000;
*ppTxData = NULL;
*pTxDataLen = 0;
}
else // This condition shall never come.
{
// Could not update file.
printf("Application Thread: Getting file Info failed...\n");
*pStatusWord = 0x6A82;
*ppTxData = NULL;
*pTxDataLen = 0;
// Return same error back.
return (status & PH_ERR_MASK);
}
}
// Proprietary command handling.
else
{
// DEFAULT: No proprietary support.
*pStatusWord = 0x6D00; // Instruction code not supported.
*ppTxData = NULL;
*pTxDataLen = 0;
}
}

Function Documentation

§ phceT4T_SetElementaryFile()

phStatus_t phceT4T_SetElementaryFile ( void *  pDataParams,
uint8_t  bFileType,
uint8_t pFile,
uint16_t  wFileId,
uint32_t  dwFileSize,
uint32_t  dwContentLen 
)

Set a supported Elementary File (EF).

Supported EF types are:

NDEF file (PHCE_T4T_FILE_NDEF) and proprietary file (PHCE_T4T_FILE_PROPRIETARY) can be on EEPROM. If writing to EEPROM needs special methods, then application should handle it using callback phceT4T_AppCallback_t in phceT4T_AppProcessCmd.

Refer NFC Forum Type 4 Tag Operation Specification version 2.0, Section 5 for details of file size and file content for each file types.

For CC file, if content length is set to 0, then CC file will be initialized with default values. If not set to 0, then content length should be a valid value including NDEF file TLV size and optional proprietary file TLV(s), if present.

CC file and NDEF file are mandatory. CC file PHCE_T4T_FILE_CC should be created first. Followed by NDEF file PHCE_T4T_FILE_NDEF. Proprietary file(s) are optional.

Parameters
[in]pDataParamsPointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
[in]bFileTypeType of Elementary File. Supported file types are PHCE_T4T_FILE_CC, PHCE_T4T_FILE_NDEF and PHCE_T4T_FILE_PROPRIETARY.
[in]pFilePointer to the Elementary File. For example, elementary file can be a pointer to a buffer like aFile[1000].
[in]wFileIdElementary File ID. IDs as per NFC Forum T4T Specification 2.0 are supported. For CC file, the file ID should be set to the NFC Forum defined value of 0xE103. For NDEF and proprietary files the valid ID ranges are between 0001h to E101h, E104h to 3EFFh, 3F01h to 3FFEh and 4000h to FFFEh.
[in]dwFileSizeSize of elementary file. For example, if aFile[1000] is set as the elementary file then dwFileSize should be set to 1000.
[in]dwContentLenActual content length in elementary file. This specifies the length of actual valid content present in file. For example if aFile[1000] = {0x00, 0x02, 0x03, 0x00} is set as the elementary file then dwContentLen should be set to 4 and dwFileSize should be set to 1000.
Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_PARAMETERParameter value is invalid. An input parameter is invalid.
PH_ERR_INVALID_DATA_PARAMSInvalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.

§ phceT4T_Activate()

phStatus_t phceT4T_Activate ( void *  pDataParams)

Activate T4T card emulation functionality.

This shall be called from the reader library thread. This API calls phpalI14443p4mC_Receive to receive data from reader and pass it to phceT4T_ProcessCmd for processing the received C-APDU (Command Application Protocol Data Unit). After processing, it sends the R-APDU (Response Application Protocol Data Unit) to reader using phpalI14443p4mC_Transmit.

Based on the configuration options PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY and PHCE_T4T_CONFIG_RECEIVE_PROPRIETARY, UPDATE BINARY and PROPRIETARY commands are handled by itself or given to application thread (i.e. phceT4T_AppProcessCmd) for handling.

Waiting Time eXtension (WTX) is handled internally by this function. This function can be used in single threaded non RTOS environment if UPDATE BINARY and proprietary commands are configured to be handled by this function itself (i.e. with no application thread present). WTX is not supported in single threaded environment.

phceT4T_Activate shall be called only after successful activation of ISO 14443-4 card layer phpalI14443p4mC_Activate. This API exits only on error from lower layers, ABORT, external RF OFF or DESELECT.

Application shall use some synchronization mechanism like mutex or semaphore to synchronize between application thread and reader library thread (i.e. to synchronize entry to and exit from phceT4T_Activate and phceT4T_AppProcessCmd).

Parameters
[in]pDataParamsPointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
Returns
Status code
Return values
PH_ERR_SUCCESS_DESELECTEDTag DESELECTED. Tag got successfully DESELECTED after receiving DESELECT request from the reader.
PH_ERR_EXT_RF_ERRORExternal RF field is OFF.
PH_ERR_ABORTEDAborted due to HAL shutdown.
PH_ERR_INVALID_DATA_PARAMSInvalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
OtherError from underlying components.

Usage:

Reader Library Thread (Block Diagram):

hce_rdlib_thread.png

Reader Library Thread (Sample Code):

void TReaderLibrary(void *pParams)
{
phStatus_t status = 0;
// Set CC File.
&sceT4T,
aCcFile,
0xE103,
sizeof(aCcFile),
wCcFileContentLength);
// Set NDEF File.
&sceT4T,
aNdefFile,
wNdefFileId,
sizeof(aNdefFile),
wNdefFileContentLength);
// Loop always in listen mode.
while(1)
{
// Start discovery loop in listen mode
status = phacDiscLoop_Run(
&sDiscLoop,
if((status & PH_ERR_MASK) != PHAC_DISCLOOP_ACTIVATED_BY_PEER)
{
goto reset_tag;
}
// Validate RATS and send ATS.
&spalI14443p4mC,
pRxBuf,
wRxBufLen,
aAtsRes,
wAtsLength);
if((status & PH_ERR_MASK) != PH_ERR_SUCCESS)
{
goto reset_tag;
}
// Trigger phceT4T_AppProcessCmd in Application thread to start.
status = phOsal_Semaphore_Give(appstart);
// Activate HCE.
status = phceT4T_Activate(&sceT4T);
// Wait for phceT4T_AppProcessCmd in Application thread to exit.
status = phOsal_Semaphore_Take(appexit, 0xFFFFFFFF);
reset_tag:
// Reset Reader library layers.
(void)phpalI14443p4mC_ResetProtocol(&spalI14443p4mC);
(void)phceT4T_Reset(&sceT4T);
// Clear all events from all sources.
(void)phOsEventClear(pDataParams->Eventhandle, E_OS_EVENT_OPT_NONE, E_PH_OSAL_EVT_ALL, NULL);
}
}

§ phceT4T_ProcessCmd()

phStatus_t phceT4T_ProcessCmd ( void *  pDataParams,
uint16_t  wOption,
uint8_t pRxData,
uint16_t  wRxDataLen,
uint16_t pStatusWord,
uint8_t **  ppTxData,
uint16_t pTxDataLen 
)

Validate and process the received C-APDU (Command Application Protocol Data Unit).

If RTOS is not used, then this API shall be called directly by the application in the only existing application task. In multi-threaded application or when phceT4T_Activate is used by application, this API will be called internally by phceT4T_Activate.

Data received from phpalI14443p4mC_Receive (C-APDU) shall be passed to this API for validation and processing. The out data parameters, pStatusWord and ppTxData (R-APDU) shall be send to reader using phpalI14443p4mC_Transmit.

SELECT and READ BINARY commands are validated and processed by this API. Proprietary commands (commands with unsupported instruction byte) are not processed and the whole C-APDU (Command Application Protocol Data Unit) is returned back in out parameter (ppTxData). For UPDATE BINARY command the file will be updated if PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY is enabled else data to be written to file and data length is returned in out parameters ppTxData and pTxDataLen respectively.

Parameters
[in]pDataParamsPointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
[in]wOptionReceived Option. This indicates if the received data (pRxData) is complete or partial.
[in]pRxDataReceived data (C-APDU). Data (Command) received from reader side. Data can be received from reader using phpalI14443p4mC_Receive and passed to this API for processing.
[in]wRxDataLenReceived data length. Length of pRxData.
[out]pStatusWordStatus Word. Contains status word SW1 and SW2 (last 2 bytes of R-APDU to be send back to reader). For example a value of 0x9000 indicates that the received data (C-APDU) is valid and processed successfully. For a complete list of values refer ISO 7816-4 specification.
[out]ppTxDataData to be transmitted back to the reader. Contains the data field of R-APDU. This will be set to NULL if data field is not needed in R-APDU.
[out]pTxDataLenLength of data to be transmitted back to reader (length of R-APDU data field ppTxData). This will be set to 0 if ppTxData is NULL (i.e. no data field in R-APDU).
Returns
Status code
Return values
PH_CE_T4T_SELECTFile selected.
PH_CE_T4T_READ_BINARYFile read.
PH_CE_T4T_UPDATE_BINARYUpdate Binary received or file updated (if PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY is enabled).
PH_CE_T4T_PROPRIETARYProprietary C-APDU received.
PH_CE_T4T_FAILUREUnsupported C-APDU / Error. Check status word (pStatusWord) to get the actual type of error.
PH_ERR_INVALID_DATA_PARAMSInvalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.

§ phceT4T_AppProcessCmd()

phStatus_t phceT4T_AppProcessCmd ( void *  pDataParams,
phceT4T_AppCallback_t  pAppCallback 
)

Application process command.

This shall be called from the application thread when RTOS / multiple threads are used. Based on configuration options PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY and PHCE_T4T_CONFIG_RECEIVE_PROPRIETARY, UPDATE BINARY and PROPRIETARY commands are handled by phceT4T_Activate or by this API.

If UPDATE BINARY needs some special write methods (i.e. if files are in EEPROM) or if some proprietary commands needs to be supported then application callback phceT4T_AppCallback_t shall be provided for that. Else callback shall be set to NULL.

This API exits only on error from lower layers, ABORT, external RF OFF or DESELECT. Application shall use some synchronization mechanism like mutex or semaphore to synchronize between application thread and reader library thread (i.e. to synchronize entry to and exit from phceT4T_Activate and phceT4T_AppProcessCmd).

When phceT4T_Activate returns in reader library thread, this API will return with same status in application thread.

Parameters
[in]pDataParamsPointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
[in]pAppCallbackApplication callback. Application callback to handle UPDATE BINARY and proprietary commands. Can be set to NULL if not used.
Returns
Status code
Return values
PH_ERR_SUCCESS_DESELECTEDTag DESELECTED. Tag got successfully DESELECTED after receiving DESELECT request from the reader.
PH_ERR_EXT_RF_ERRORExternal RF field is OFF.
PH_ERR_ABORTEDAborted due to HAL shutdown.
PH_ERR_INVALID_DATA_PARAMSInvalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
OtherError from underlying components.

Usage:

Application Thread (Block Diagram):

hce_app_thread.png

Application Thread (Sample Code):

void TApplication(void *pParams)
{
phStatus_t status;
while(1)
{
// Wait for trigger from reader library thread to start.
status = phOsal_Semaphore_Take(appstart, 0xFFFFFFFF);
// Start Application processing of HCE.
status = phceT4T_AppProcessCmd(&sceT4T, AppCallback);
// Trigger reader lib thread about the phceT4T_AppProcessCmd exit.
status = phOsal_Semaphore_Give(appexit);
}
}

§ phceT4T_GetSelectedFileInfo()

phStatus_t phceT4T_GetSelectedFileInfo ( void *  pDataParams,
uint16_t pFileId,
uint8_t **  ppFile,
uint32_t pFileSize,
uint8_t pWriteAccess,
uint32_t pFileOffset 
)

Get information about currently selected file.

Application shall use this to get information about currently selected file when UPDATE BINARY and proprietary commands are handled by application callback.

Parameters
[in]pDataParamsPointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
[out]pFileIdID of selected file. Used to pass back the ID of currently selected file.
[out]ppFilePointer to selected file. Used to pass back the pointer to currently selected file.
[out]pFileSizeSize of selected file. Used to pass back the size of currently selected file.
[out]pWriteAccessWrite access of selected file. Used to pass back the write access of currently selected file. Only 0x00 and 0xFF are the supported vales. 0x00 - write access with out any restriction. 0xFF - no write access (read only file). All other values are RFU (not used).
[out]pFileOffsetUsed to pass back the offset of currently selected file from where it should be updated. This is valid only for UPDATE BINARY command. Application shall update the selected file (ppFile) starting from this offset (pFileOffset) for UPDATE BINARY command. When processing proprietary commands, value of this parameter shall be ignored as whole command (C-APDU) is processed by application callback itself.
Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSInvalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
PH_CE_T4T_INVALID_STATEInvalid State. Operation not supported in current tag state (i.e. no files are in selected state).

§ phceT4T_Reset()

phStatus_t phceT4T_Reset ( void *  pDataParams)

Reset the tag's state variables.

Application shall use this to reset variables and data parameters of tag after one cycle of operation or on error (i.e. after /ref phceT4T_Activate exists).

Parameters
[in]pDataParamsPointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSInvalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.

§ phceT4T_SetConfig()

phStatus_t phceT4T_SetConfig ( void *  pDataParams,
uint16_t  wConfig,
uint16_t  wValue 
)

Set value of the specified configurationidentifier".

The SetConfig command is used to set values for the different configuration parameters of this layer.

Parameters
[in]pDataParamsPointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
[in]wConfigConfiguration Identifier. Specify the configuration identifier to be set.
[in]wValueConfiguration Value. Value to be set for the specified configuration identifier (wConfig).
Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSInvalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
PH_ERR_INVALID_PARAMETERParameter value or configuration option is invalid.
PH_CE_T4T_INVALID_STATEInvalid state. Operation not supported in current tag state. Refer configuration options to known when each configuration can be set.

§ phceT4T_GetConfig()

phStatus_t phceT4T_GetConfig ( void *  pDataParams,
uint16_t  wConfig,
uint16_t pValue 
)

Get value of the specified configurationidentifier".

The GetConfig command is used to retrieve values of different configuration parameters of this layer.

Parameters
[in]pDataParamsPointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
[in]wConfigConfiguration Identifier. Specify the configuration identifier for which value to be retrieved.
[out]pValueConfiguration Value. Used to pass back the value of the specified configuration identifier (wConfig).
Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSInvalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
PH_ERR_INVALID_PARAMETERParameter value or configuration option is invalid.
PH_CE_T4T_INVALID_STATEInvalid state. Operation not supported in current tag state. Refer configuration options to known when each configuration value can be retrieved.