NXP NFC Reader Library v4.040.05.011646

Modules | Macros | Typedefs | Functions
NFC Forum Type 4A Card Emulation
Host 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.

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] | bState | Tag State indicating received command type (PHCE_T4T_STATE_FILE_UPDATE or PHCE_T4T_STATE_PROPRIETARY).
  [in] | wRxOption | Receive option indicating if received data (pRxData) is partial or complete.
  [in] | pRxData | Data received from reader library thread.
  [in] | wRxDataLen | Length of received data (length of pRxData).
  [out] | pStatusWord | Status Word to be sent (as part of R-APDU). For example set pStatusWord as 0x9000 when requested command is successfully completed.
  [out] | ppTxData | Data 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] | pTxDataLen | Length 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_SUCCESS | Operation successful.
  PH_ERR_INTERNAL_ERROR | for 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
if(bState == PHCE_T4T_STATE_FILE_UPDATE)
{
// Get Selected file info.
status = phceT4T_GetSelectedFileInfo(
&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;
}
return PH_ERR_SUCCESS;
}

## 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:

- PHCE_T4T_FILE_CC
- PHCE_T4T_FILE_NDEF
- PHCE_T4T_FILE_PROPRIETARY

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] | pDataParams | Pointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
  [in] | bFileType | Type of Elementary File. Supported file types are PHCE_T4T_FILE_CC, PHCE_T4T_FILE_NDEF and PHCE_T4T_FILE_PROPRIETARY.
  [in] | pFile | Pointer to the Elementary File. For example, elementary file can be a pointer to a buffer like aFile[1000].
  [in] | wFileId | Elementary 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] | dwFileSize | Size of elementary file. For example, if aFile[1000] is set as the elementary file then dwFileSize should be set to 1000.
  [in] | dwContentLen | Actual 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_SUCCESS | Operation successful.
  PH_ERR_INVALID_PARAMETER | Parameter value is invalid. An input parameter is invalid.
  PH_ERR_INVALID_DATA_PARAMS | Invalid 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] | pDataParams | Pointer to this layer's parameter structure phceT4T_Sw_DataParams_t.

Returns
  Status code

Return values

  PH_ERR_SUCCESS_DESELECTED | Tag DESELECTED. Tag got successfully DESELECTED after receiving DESELECT request from the reader.
  PH_ERR_EXT_RF_ERROR | External RF field is OFF.
  PH_ERR_ABORTED | Aborted due to HAL shutdown.
  PH_ERR_INVALID_DATA_PARAMS | Invalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
  Other | Error from underlying components.

Usage:

Reader Library Thread (Block Diagram):

Reader Library Thread (Sample Code):

void TReaderLibrary(void *pParams)
{
phStatus_t status = 0;
// Set CC File.
status = phceT4T_SetElementaryFile(
&sceT4T,
PHCE_T4T_FILE_CC,
aCcFile,
0xE103,
sizeof(aCcFile),
wCcFileContentLength);
// Set NDEF File.
status = phceT4T_SetElementaryFile(
&sceT4T,
PHCE_T4T_FILE_NDEF,
aNdefFile,
wNdefFileId,
sizeof(aNdefFile),
wNdefFileContentLength);
// Loop always in listen mode.
while(1)
{
// Start discovery loop in listen mode
status = phacDiscLoop_Run(
&sDiscLoop,
PHAC_DISCLOOP_ENTRY_POINT_LISTEN);
if((status & PH_ERR_MASK) != PHAC_DISCLOOP_ACTIVATED_BY_PEER)
{
goto reset_tag;
}
// Validate RATS and send ATS.
status = phpalI14443p4mC_Activate(
&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] | pDataParams | Pointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
  [in] | wOption | Received Option. This indicates if the received data (pRxData) is complete or partial.
  [in] | pRxData | Received 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] | wRxDataLen | Received data length. Length of pRxData.
  [out] | pStatusWord | Status 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] | ppTxData | Data 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] | pTxDataLen | Length 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_SELECT | File selected.
  PH_CE_T4T_READ_BINARY | File read.
  PH_CE_T4T_UPDATE_BINARY | Update Binary received or file updated (if PHCE_T4T_CONFIG_HANDLE_UPDATEBINARY is enabled).
  PH_CE_T4T_PROPRIETARY | Proprietary C-APDU received.
  PH_CE_T4T_FAILURE | Unsupported C-APDU / Error. Check status word (pStatusWord) to get the actual type of error.
  PH_ERR_INVALID_DATA_PARAMS | Invalid 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] | pDataParams | Pointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
  [in] | pAppCallback | Application 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_DESELECTED | Tag DESELECTED. Tag got successfully DESELECTED after receiving DESELECT request from the reader.
  PH_ERR_EXT_RF_ERROR | External RF field is OFF.
  PH_ERR_ABORTED | Aborted due to HAL shutdown.
  PH_ERR_INVALID_DATA_PARAMS | Invalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
  Other | Error from underlying components.

Usage:

Application Thread (Block Diagram):

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] | pDataParams | Pointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
  [out] | pFileId | ID of selected file. Used to pass back the ID of currently selected file.
  [out] | ppFile | Pointer to selected file. Used to pass back the pointer to currently selected file.
  [out] | pFileSize | Size of selected file. Used to pass back the size of currently selected file.
  [out] | pWriteAccess | Write 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] | pFileOffset | Used 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_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
  PH_CE_T4T_INVALID_STATE | Invalid 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] | pDataParams | Pointer to this layer's parameter structure phceT4T_Sw_DataParams_t.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid 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] | pDataParams | Pointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
  [in] | wConfig | Configuration Identifier. Specify the configuration identifier to be set.
  [in] | wValue | Configuration Value. Value to be set for the specified configuration identifier (wConfig).

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
  PH_ERR_INVALID_PARAMETER | Parameter value or configuration option is invalid.
  PH_CE_T4T_INVALID_STATE | Invalid 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] | pDataParams | Pointer to this layer's parameter structure phceT4T_Sw_DataParams_t.
  [in] | wConfig | Configuration Identifier. Specify the configuration identifier for which value to be retrieved.
  [out] | pValue | Configuration Value. Used to pass back the value of the specified configuration identifier (wConfig).

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid data parameter. The provided data parameter (pDataParams) is invalid or this layer is not initialized.
  PH_ERR_INVALID_PARAMETER | Parameter value or configuration option is invalid.
  PH_CE_T4T_INVALID_STATE | Invalid state. Operation not supported in current tag state. Refer configuration options to known when each configuration value can be retrieved.