NXP Reader Library  v17.1.0.2535
Commands_FileManagement

Describes about the MIFARE DUOX File Management commands. More...

Collaboration diagram for Commands_FileManagement:

Modules

 Defines
 Macro Definitions for File Management commands.
 

Functions

phStatus_t phalMfDuoX_CreateStdDataFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t *pFileSize)
 Creates files for the storage of plain unformatted user data within an existing application on the PICC. More...
 
phStatus_t phalMfDuoX_CreateBackupDataFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t *pFileSize)
 Creates files for the storage of plain unformatted user data within an existing application on the PICC, additionally supporting the feature of an integrated backup mechanism. More...
 
phStatus_t phalMfDuoX_CreateValueFile (void *pDataParams, uint8_t bFileNo, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t *pLowerLmit, uint8_t *pUpperLmit, uint8_t *pValue, uint8_t bLimitedCredit)
 Creates files for the storage and manipulation of 32bit signed integer values within an existing application on the PICC. More...
 
phStatus_t phalMfDuoX_CreateLinearRecordFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t *pRecordSize, uint8_t *pMaxNoOfRec)
 Creates files for multiple storage of structural similar data, for example for loyalty programs within an existing application. More...
 
phStatus_t phalMfDuoX_CreateCyclicRecordFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t *pRecordSize, uint8_t *pMaxNoOfRec)
 Creates files for multiple storage of structural similar data, for example for logging transactions, within an existing application. More...
 
phStatus_t phalMfDuoX_CreateTransactionMacFile (void *pDataParams, uint16_t wOption, uint8_t bFileNo, uint8_t bFileOption, uint8_t *pAccessRights, uint16_t wKeyNo, uint8_t bTMKeyOption, uint8_t *pTMKey, uint8_t bTMKeyVer, uint8_t *pDivInput, uint8_t bDivInputLen, uint8_t *pTMIExclFileMap, uint8_t bTSIGKeyNo)
 Creates a Transaction MAC File and enables the Transaction MAC or Signature feature for the targeted application. More...
 
phStatus_t phalMfDuoX_DeleteFile (void *pDataParams, uint8_t bFileNo)
 Permanently deactivates a file within the file directory of the currently selected application. More...
 
phStatus_t phalMfDuoX_GetFileIDs (void *pDataParams, uint8_t **ppFileId, uint16_t *pFileIdLen)
 Returns the file IDs of all active files within the currently selected application. More...
 
phStatus_t phalMfDuoX_GetISOFileIDs (void *pDataParams, uint8_t **ppISOFileId, uint16_t *pISOFileIdLen)
 Get the ISO File IDs. More...
 
phStatus_t phalMfDuoX_GetFileSettings (void *pDataParams, uint8_t bFileNo, uint8_t **ppFSBuffer, uint16_t *pFSBufLen)
 Get information on the properties of a specific file. More...
 
phStatus_t phalMfDuoX_GetFileCounters (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t **ppFileCounters, uint16_t *pFileCounterLen)
 Get file related counters used for Secure Dynamic Messaging. More...
 
phStatus_t phalMfDuoX_ChangeFileSettings (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t *pAddInfo, uint8_t bAddInfoLen)
 Changes the access parameters of an existing file. More...
 

Detailed Description

Describes about the MIFARE DUOX File Management commands.

Function Documentation

◆ phalMfDuoX_CreateStdDataFile()

phStatus_t phalMfDuoX_CreateStdDataFile ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pISOFileId,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t pFileSize 
)

Creates files for the storage of plain unformatted user data within an existing application on the PICC.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETER
  • If the buffers are null.
  • For Invalid Option (bOption) information.
  • For Invalid File numbers (bFileNo).
  • For Invalid File communication mode (bFileOption).
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option to represent the presence of ISO information.
[in]bFileNo[In] The file number to be created. ORed with Secondary Application indicator.
[in]pISOFileId[In] ISO File ID to be used. Should be two bytes.
[in]bFileOption[In] Option for the targeted file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
  • Bit[15 - 12]: Read
  • Bit[11 - 8] : Write
  • Bit[7 - 4] : ReadWrite
  • Bit[3 - 0] : Change or RFU. Change for the 1st mandatory set of access condition else RFU (i.e. 0xF)
  • Below are the values for the above bits.
    • 0x0 - 0xD: Authentication Required
    • 0xD : [Optional] Free access over I2C, authentication required over NFC
    • 0xE : Free Access
    • 0xF : No Access or RFU
[in]pFileSize[In] The size of the file. Will be of 3 bytes with LSB first. If size 0x10 need to be created, then the FileSize will be 10 00 00.

◆ phalMfDuoX_CreateBackupDataFile()

phStatus_t phalMfDuoX_CreateBackupDataFile ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pISOFileId,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t pFileSize 
)

Creates files for the storage of plain unformatted user data within an existing application on the PICC, additionally supporting the feature of an integrated backup mechanism.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETER
  • If the buffers are null.
  • For Invalid Option (bOption) information.
  • For Invalid File numbers (bFileNo).
  • For Invalid File communication mode (bFileOption).
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option to represent the presence of ISO information.
[in]bFileNo[In] The file number to be created. ORed with Secondary Application indicator.
[in]pISOFileId[In] ISO File ID to be used. Should be two bytes.
[in]bFileOption[In] Option for the targeted file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
  • Bit[15 - 12]: Read
  • Bit[11 - 8] : Write
  • Bit[7 - 4] : ReadWrite
  • Bit[3 - 0] : Change or RFU. Change for the 1st mandatory set of access condition else RFU (i.e. 0xF)
  • Below are the values for the above bits.
    • 0x0 - 0xD: Authentication Required
    • 0xD : [Optional] Free access over I2C, authentication required over NFC
    • 0xE : Free Access
    • 0xF : No Access or RFU
[in]pFileSize[In] The size of the file. Will be of 3 bytes with LSB first. If size 0x10 need to be created, then the FileSize will be 10 00 00.

◆ phalMfDuoX_CreateValueFile()

phStatus_t phalMfDuoX_CreateValueFile ( void *  pDataParams,
uint8_t  bFileNo,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t pLowerLmit,
uint8_t pUpperLmit,
uint8_t pValue,
uint8_t  bLimitedCredit 
)

Creates files for the storage and manipulation of 32bit signed integer values within an existing application on the PICC.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETER
  • If the buffers are null.
  • For Invalid File numbers (bFileNo).
  • For Invalid File communication mode (bFileOption).
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bFileNo[In] The file number to be created. ORed with Secondary Application indicator.
[in]bFileOption[In] Option for the targeted file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
[in]pLowerLmit[In] The lower limit for the file. Will be of 4 bytes with LSB first. If value 0x10 need to be set as lower limit, then the value will be 10 00 00 00.
[in]pUpperLmit[In] The upper limit for the file. Will be of 4 bytes with LSB first. If value 0x20 need to be set as upper limit, then the value will be 20 00 00 00.
[in]pValue[In] The initial value. Will be of 4 bytes with LSB first. If value 0x10 need to be set as initial value, then the value will be 10 00 00 00.
[in]bLimitedCredit[In] Encodes if LimitedCredit and free GetValue are allowed for this file.

◆ phalMfDuoX_CreateLinearRecordFile()

phStatus_t phalMfDuoX_CreateLinearRecordFile ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pISOFileId,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t pRecordSize,
uint8_t pMaxNoOfRec 
)

Creates files for multiple storage of structural similar data, for example for loyalty programs within an existing application.

Once the file is filled, further writing is not possible unless it is cleared.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETER
  • If the buffers are null.
  • For Invalid Option (bOption) information.
  • For Invalid File numbers (bFileNo).
  • For Invalid File communication mode (bFileOption).
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option to represent the presence of ISO information.
[in]bFileNo[In] The file number to be created. ORed with Secondary Application indicator.
[in]pISOFileId[In] ISO File ID to be used. Should be two bytes.
[in]bFileOption[In] Option for the targeted file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
  • Bit[15 - 12]: Read
  • Bit[11 - 8] : Write
  • Bit[7 - 4] : ReadWrite
  • Bit[3 - 0] : Change or RFU. Change for the 1st mandatory set of access condition else RFU (i.e. 0xF)
  • Below are the values for the above bits.
    • 0x0 - 0xD: Authentication Required
    • 0xD : [Optional] Free access over I2C, authentication required over NFC
    • 0xE : Free Access
    • 0xF : No Access or RFU
[in]pRecordSize[In] The size of the file. Will be of 3 bytes with LSB first. If size 0x10 need to be created, then the RecordSize will be 10 00 00.
[in]pMaxNoOfRec[In] The maximum number of record in the file. Will be of 3 bytes with LSB first. If size 0x04 need to be created, then the value will be 04 00 00.

◆ phalMfDuoX_CreateCyclicRecordFile()

phStatus_t phalMfDuoX_CreateCyclicRecordFile ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pISOFileId,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t pRecordSize,
uint8_t pMaxNoOfRec 
)

Creates files for multiple storage of structural similar data, for example for logging transactions, within an existing application.

Once the file is filled, the PICC automatically overwrites the oldest record with the latest written one.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETER
  • If the buffers are null.
  • For Invalid Option (bOption) information.
  • For Invalid File numbers (bFileNo).
  • For Invalid File communication mode (bFileOption).
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option to represent the presence of ISO information.
[in]bFileNo[In] The file number to be created. ORed with Secondary Application indicator.
[in]pISOFileId[In] ISO File ID to be used. Should be two bytes.
[in]bFileOption[In] Option for the targeted file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
  • Bit[15 - 12]: Read
  • Bit[11 - 8] : Write
  • Bit[7 - 4] : ReadWrite
  • Bit[3 - 0] : Change or RFU. Change for the 1st mandatory set of access condition else RFU (i.e. 0xF)
  • Below are the values for the above bits.
    • 0x0 - 0xD: Authentication Required
    • 0xD : [Optional] Free access over I2C, authentication required over NFC
    • 0xE : Free Access
    • 0xF : No Access or RFU
[in]pRecordSize[In] The size of the file. Will be of 3 bytes with LSB first. If size 0x10 need to be created, then the RecordSize will be 10 00 00.
[in]pMaxNoOfRec[In] The maximum number of record in the file. Will be of 3 bytes with LSB first. If size 0x04 need to be created, then the value will be 04 00 00.

◆ phalMfDuoX_CreateTransactionMacFile()

phStatus_t phalMfDuoX_CreateTransactionMacFile ( void *  pDataParams,
uint16_t  wOption,
uint8_t  bFileNo,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint16_t  wKeyNo,
uint8_t  bTMKeyOption,
uint8_t pTMKey,
uint8_t  bTMKeyVer,
uint8_t pDivInput,
uint8_t  bDivInputLen,
uint8_t pTMIExclFileMap,
uint8_t  bTSIGKeyNo 
)

Creates a Transaction MAC File and enables the Transaction MAC or Signature feature for the targeted application.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETER
  • If the buffers are null.
  • For Invalid File numbers (bFileNo).
  • For Invalid File communication mode (bFileOption).
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]wOption[In] Options to be used for diversifying TransactionMAC Key. One of the below values.
[in]bFileNo[In] The file number to be created. ORed with Secondary Application indicator.
[in]bFileOption[In] Option for the targeted file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
  • Bit[15 - 12]: Read
  • Bit[11 - 8] : RFU (0xF)
  • Bit[7 - 4] : ReadWrite
    • 0x0 - 0xD: CommitReaderID enabled, requiring authentication with the specified key index or granting equivalent access rights via asymmetric authentication
    • 0xE : CommitReaderID enabled with Free Access
    • 0xF : Commit Reader ID Disabled
  • Bit[3 - 0] : Change or RFU. Change for the 1st mandatory set of access condition else RFU (i.e. 0xF)
  • Below are the values for the above bits.
    • 0x0 - 0xD: Authentication Required
    • 0xD : [Optional] Free access over I2C, authentication required over NFC
    • 0xE : Free Access
    • 0xF : No Access or RFU
[in]wKeyNo[In] Key number in SAM KeyStore. For software is not applicable.
[in]bTMKeyOption[In] Options for Transaction MAC Key.
[in]pTMKey[In] The 16 byte key value to be stored in the PICC. This is applicable for Software only.
[in]bTMKeyVer[In] The version for the key to be stored in the PICC. This is applicable for Software and SAM.
[in]pDivInput[In] Diversification input. Can be NULL.
[in]bDivInputLen[In] Length of bytes available in pDivInput buffer.
[in]pTMIExclFileMap[In] TMI exclusion FileMap. Should be 4 byte.
[in]bTSIGKeyNo[In] Key Number pointing to AppTransactionSIGKey. Here the key number (TSIGKeyNo) will be used directly for command exchange.

◆ phalMfDuoX_DeleteFile()

phStatus_t phalMfDuoX_DeleteFile ( void *  pDataParams,
uint8_t  bFileNo 
)

Permanently deactivates a file within the file directory of the currently selected application.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bFileNo[In] The file number to be deleted. ORed with Secondary Application indicator.

◆ phalMfDuoX_GetFileIDs()

phStatus_t phalMfDuoX_GetFileIDs ( void *  pDataParams,
uint8_t **  ppFileId,
uint16_t pFileIdLen 
)

Returns the file IDs of all active files within the currently selected application.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETERIf the buffer is null.
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[out]ppFileId[Out] The buffer containing the available File ID(s).
[out]pFileIdLen[Out] Length of bytes available in ppFid buffer.

◆ phalMfDuoX_GetISOFileIDs()

phStatus_t phalMfDuoX_GetISOFileIDs ( void *  pDataParams,
uint8_t **  ppISOFileId,
uint16_t pISOFileIdLen 
)

Get the ISO File IDs.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETERIf the buffer is null.
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[out]ppISOFileId[Out] The buffer containing the available ISO File ID(s).
[out]pISOFileIdLen[Out] Length of bytes available in ppFid buffer.

◆ phalMfDuoX_GetFileSettings()

phStatus_t phalMfDuoX_GetFileSettings ( void *  pDataParams,
uint8_t  bFileNo,
uint8_t **  ppFSBuffer,
uint16_t pFSBufLen 
)

Get information on the properties of a specific file.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETERIf the buffer is null.
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bFileNo[In] The file number for which the setting to be retrieved. ORed with Secondary Application indicator.
[out]ppFSBuffer[Out] The buffer containing the settings.
[out]pFSBufLen[Out] Length of bytes available in ppFSBuffer buffer.

◆ phalMfDuoX_GetFileCounters()

phStatus_t phalMfDuoX_GetFileCounters ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t **  ppFileCounters,
uint16_t pFileCounterLen 
)

Get file related counters used for Secure Dynamic Messaging.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETERIf the buffer is null.
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Indicates the mode of communication to be used while exchanging the data to PICC.
[in]bFileNo[In] File number for which the Counter information need to be received. ORed with Secondary Application indicator.
[out]ppFileCounters[Out] The SDMReadCounter information returned by the PICC.
[out]pFileCounterLen[Out] Length of bytes available in ppFileCounters buffer.

◆ phalMfDuoX_ChangeFileSettings()

phStatus_t phalMfDuoX_ChangeFileSettings ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t pAddInfo,
uint8_t  bAddInfoLen 
)

Changes the access parameters of an existing file.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
PH_ERR_INVALID_DATA_PARAMSIf DataParams is null.
PH_ERR_INVALID_PARAMETER
  • If the buffers are null.
  • For Invalid File numbers (bFileNo).
  • For Invalid File communication mode (bFileOption).
XXXX
  • Depending on status codes return by PICC.
  • Other Depending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Indicates the mode of communication to be used while exchanging the data to PICC.
[in]bFileNo[In] File number for which the setting need to be updated. ORed with Secondary Application indicator.
[in]bFileOption[In] Option for the targeted file.
[in]pAccessRights[In] Set of access conditions for the 1st set in the file. Should be 2 byte.
[in]pAddInfo[In] Buffer should contain the following information.
  • [NrAddARs] || [Additional access rights] ||
  • [SDMOption || SDM AccessRights || VCUIDOffset || SDMReadCtrOffset || PICCDataOffset || GPIOStatusOffset || SDMMACInputOffset || SDMENCOffset || SDMENCLength || SDMMACOffset || SDMReadCtrLimit] ||
  • [TMIExclFileMap] ||
  • [TMCLimit] ||
  • [CRLOptions || CNSSize] || CRLSigKey]
[in]bAddInfoLen[In] Length of bytes available in pAddInfo buffer.