TABLE OF CONTENTS

 

[Modules] Files

NAME

   DesfireAPI :: File management functions

COPYRIGHT

DESCRIPTION

   Implementation of management functions to create or delete
   files withing a DESFIRE application.

[Functions] ChangeFileSettings

NAME

   ChangeFileSettings

DESCRIPTION

   Changes the access parameters of an existing file

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_ChangeFileSettings(BYTE file_id,
                                     BYTE comm_mode,
                                     WORD access_rights);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_ChangeFileSettings(SPROX_INSTANCE rInst,
                                     BYTE file_id,
                                     BYTE comm_mode,
                                     WORD access_rights);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_ChangeFileSettings(SCARDHANDLE hCard,
                                     BYTE file_id,
                                     BYTE comm_mode,
                                     WORD access_rights);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights

RETURNS

   DF_OPERATION_OK    : change succeeded
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   GetFileIDs
   GetFileSettings

[Functions] CreateBackupDataFile

NAME

   CreateBackupDataFile

DESCRIPTION

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

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateBackupDataFile(BYTE file_id,
                                            BYTE comm_mode,
                                            WORD access_rights,
                                            DWORD file_size);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateBackupDataFile(SPROX_INSTANCE rInst,
                                             BYTE file_id,
                                             BYTE comm_mode,
                                             WORD access_rights,
                                             DWORD file_size);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateBackupDataFile(SCARDHANDLE hCard,
                                           BYTE file_id,
                                           BYTE comm_mode,
                                           WORD access_rights,
                                           DWORD file_size);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   DWORD file_size             : size of the file in bytes

RETURNS

   DF_OPERATION_OK    : Backup Data File  succeeded
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateStdDataFile
   CreateValueFile
   CreateLinearRecordFile
   CreateCyclicRecordFile
   DeleteFile

[Functions] CreateCyclicRecordFile

NAME

   CreateCyclicRecordFile

DESCRIPTION

   Creates a cyclic record file

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateCyclicRecordFile(BYTE file_id,
                                              BYTE comm_mode,
                                              WORD access_rights,
                                              DWORD record_size,
                                              DWORD max_records);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateCyclicRecordFile(SPROX_INSTANCE rInst,
                                               BYTE file_id,
                                               BYTE comm_mode,
                                               WORD access_rights,
                                               DWORD record_size,
                                               DWORD max_records);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateCyclicRecordFile(SCARDHANDLE hCard,
                                             BYTE file_id,
                                             BYTE comm_mode,
                                             WORD access_rights,
                                             DWORD record_size,
                                             DWORD max_records);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   DWORD file_size             : size of the file in bytes
   DWORD record_size           : size of one single record in bytes
   DWORD max_records           : maximum number of records

RETURNS

   DF_OPERATION_OK    : file created successfully
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateStdDataFile
   CreateBackupDataFile
   CreateValueFile
   CreateLinearRecordFile
   DeleteFile

[Functions] CreateIsoBackupDataFile

NAME

   CreateIsoBackupDataFile

DESCRIPTION

   Creates files for the storage of plain unformatted user data within an existing application
   on the DESFIRE card, additionally supporting the feature of integrated backup mechanism.
   Using this function, an ISO EF IDentifier is specified as well as a legacy DESFIRE File ID.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateIsoBackupDataFile(BYTE file_id,
                                               WORD iso_ef_id,
                                               BYTE comm_mode,
                                               WORD access_rights,
                                               DWORD file_size);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateIsoBackupDataFile(SPROX_INSTANCE rInst,
                                                WORD iso_ef_id,
                                                BYTE file_id,
                                                BYTE comm_mode,
                                                WORD access_rights,
                                                DWORD file_size);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateIsoBackupDataFile(SCARDHANDLE hCard,
                                              WORD iso_ef_id,
                                              BYTE file_id,
                                              BYTE comm_mode,
                                              WORD access_rights,
                                              DWORD file_size);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   WORD iso_ef_id              : IDentifier of the EF for ISO 7816-4 applications
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   DWORD file_size             : size of the file in bytes

RETURNS

   DF_OPERATION_OK    : Backup Data File  succeeded
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateStdDataFile
   CreateValueFile
   CreateLinearRecordFile
   CreateCyclicRecordFile
   DeleteFile

[Functions] CreateIsoCyclicRecordFile

NAME

   CreateIsoCyclicRecordFile

DESCRIPTION

   Creates a cyclic record file.
   Using this function, an ISO EF IDentifier is specified as well as a legacy DESFIRE File ID.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateIsoCyclicRecordFile(BYTE file_id,
                                                 WORD iso_ef_id,
                                                 BYTE comm_mode,
                                                 WORD access_rights,
                                                 DWORD record_size,
                                                 DWORD max_records);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateIsoCyclicRecordFile(SPROX_INSTANCE rInst,
                                                  WORD iso_ef_id,
                                                  BYTE file_id,
                                                  BYTE comm_mode,
                                                  WORD access_rights,
                                                  DWORD record_size,
                                                  DWORD max_records);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateIsoCyclicRecordFile(SCARDHANDLE hCard,
                                                WORD iso_ef_id,
                                                BYTE file_id,
                                                BYTE comm_mode,
                                                WORD access_rights,
                                                DWORD record_size,
                                                DWORD max_records);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   WORD iso_ef_id              : IDentifier of the EF for ISO 7816-4 applications
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   DWORD file_size             : size of the file in bytes
   DWORD record_size           : size of one single record in bytes
   DWORD max_records           : maximum number of records

RETURNS

   DF_OPERATION_OK    : file created successfully
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateStdDataFile
   CreateBackupDataFile
   CreateValueFile
   CreateLinearRecordFile
   DeleteFile

[Functions] CreateIsoLinearRecordFile

NAME

   CreateIsoLinearRecordFile

DESCRIPTION

   Creates a linear record file.
   Using this function, an ISO EF IDentifier is specified as well as a legacy DESFIRE File ID.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateIsoLinearRecordFile(BYTE file_id,
                                                 WORD iso_ef_id,
                                                 BYTE comm_mode,
                                                 WORD access_rights,
                                                 DWORD record_size,
                                                 DWORD max_records);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateIsoLinearRecordFile(SPROX_INSTANCE rInst,
                                                  WORD iso_ef_id,
                                                  BYTE file_id,
                                                  BYTE comm_mode,
                                                  WORD access_rights,
                                                  DWORD record_size,
                                                  DWORD max_records);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateIsoLinearRecordFile(SCARDHANDLE hCard,
                                                WORD iso_ef_id,
                                                BYTE file_id,
                                                BYTE comm_mode,
                                                WORD access_rights,
                                                DWORD record_size,
                                                DWORD max_records);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   WORD iso_ef_id              : IDentifier of the EF for ISO 7816-4 applications
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   DWORD record_size           : size of one single record in bytes
   DWORD max_records           : maximum number of records

RETURNS

   DF_OPERATION_OK    : file created successfully
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateStdDataFile
   CreateBackupDataFile
   CreateValueFile
   CreateCyclicRecordFile
   DeleteFile

[Functions] CreateIsoStdDataFile

NAME

   CreateIsoStdDataFile

DESCRIPTION

   Creates files for the storage of plain unformatted user data within an existing application
   on the DESFIRE card.
   Using this function, an ISO EF IDentifier is specified as well as a legacy DESFIRE File ID.

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateIsoStdDataFile(BYTE file_id,
                                            WORD iso_ef_id,
                                            BYTE comm_mode,
                                            WORD access_rights,
                                            DWORD file_size);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateIsoStdDataFile(SPROX_INSTANCE rInst,
                                             WORD iso_ef_id,
                                             BYTE file_id,
                                             BYTE comm_mode,
                                             WORD access_rights,
                                             DWORD file_size);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateIsoStdDataFile(SCARDHANDLE hCard,
                                           WORD iso_ef_id,
                                           BYTE file_id,
                                           BYTE comm_mode,
                                           WORD access_rights,
                                           DWORD file_size);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   WORD iso_ef_id              : IDentifier of the EF for ISO 7816-4 applications
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   DWORD file_size             : size of the file in bytes

RETURNS

   DF_OPERATION_OK    : creation succeeded
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateBackupDataFile
   CreateValueFile
   CreateLinearRecordFile
   CreateCyclicRecordFile
   DeleteFile

[Functions] CreateLinearRecordFile

NAME

   CreateLinearRecordFile

DESCRIPTION

   Creates a linear record file

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateLinearRecordFile(BYTE file_id,
                                     BYTE comm_mode,
                                     WORD access_rights,
                                     DWORD record_size,
                                     DWORD max_records);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateLinearRecordFile(SPROX_INSTANCE rInst,
                                     BYTE file_id,
                                     BYTE comm_mode,
                                     WORD access_rights,
                                     DWORD record_size,
                                     DWORD max_records);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateLinearRecordFile(SCARDHANDLE hCard,
                                     BYTE file_id,
                                     BYTE comm_mode,
                                     WORD access_rights,
                                     DWORD record_size,
                                     DWORD max_records);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   DWORD record_size           : size of one single record in bytes
   DWORD max_records           : maximum number of records

RETURNS

   DF_OPERATION_OK    : file created successfully
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateStdDataFile
   CreateBackupDataFile
   CreateValueFile
   CreateCyclicRecordFile
   DeleteFile

[Functions] CreateStdDataFile

NAME

   CreateStdDataFile

DESCRIPTION

   Creates files for the storage of plain unformatted user data within an existing application
   on the DESFIRE card

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateStdDataFile(BYTE file_id,
                                         BYTE comm_mode,
                                         WORD access_rights,
                                         DWORD file_size);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateStdDataFile(SPROX_INSTANCE rInst,
                                          BYTE file_id,
                                          BYTE comm_mode,
                                          WORD access_rights,
                                          DWORD file_size);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateStdDataFile(SCARDHANDLE hCard,
                                        BYTE file_id,
                                        BYTE comm_mode,
                                        WORD access_rights,
                                        DWORD file_size);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   DWORD file_size             : size of the file in bytes

RETURNS

   DF_OPERATION_OK    : creation succeeded
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateBackupDataFile
   CreateValueFile
   CreateLinearRecordFile
   CreateCyclicRecordFile
   DeleteFile

[Functions] CreateValueFile

NAME

   CreateValueFile

DESCRIPTION

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

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_CreateValueFile(BYTE file_id,
                                       BYTE comm_mode,
                                       WORD access_rights,
                                       LONG lower_limit,
                                       LONG upper_limit,
                                       LONG initial_value,
                                       BYTE limited_credit_enabled);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_CreateValueFile(SPROX_INSTANCE rInst,
                                        BYTE file_id,
                                        BYTE comm_mode,
                                        WORD access_rights,
                                        LONG lower_limit,
                                        LONG upper_limit,
                                        LONG initial_value,
                                        BYTE limited_credit_enabled);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_CreateValueFile(SCARDHANDLE hCard,
                                      BYTE file_id,
                                      BYTE comm_mode,
                                      WORD access_rights,
                                      LONG lower_limit,
                                      LONG upper_limit,
                                      LONG initial_value,
                                      BYTE limited_credit_enabled);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   BYTE comm_mode              : file's Communication Settings
   WORD access_rights          : file's Access Rights
   LONG lower_limit            : lower limit which is valid for this file. The lower limit marks 
                                 the boundary which must not be passed by a Debit calculation on 
                                 the current value
   LONG upper_limit            : the upper limit which sets the boundary in the same manner but for
                                 the Credit operation
   LONG initial_value          : specifies the initial value of the value file
   BYTE limited_credit_enabled : activation of the LimitedCredit feature (0 disabled, 1 enabled)

RETURNS

   DF_OPERATION_OK    : file created
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateStdDataFile
   CreateBackupDataFile
   CreateLinearRecordFile
   CreateCyclicRecordFile
   DeleteFile

[Functions] DeleteFile

NAME

   DeleteFile

DESCRIPTION

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

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_DeleteFile(BYTE file_id);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_DeleteFile(SPROX_INSTANCE rInst,
                                   BYTE file_id);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_DeleteFile(SCARDHANDLE hCard,
                                 BYTE file_id);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier

RETURNS

   DF_OPERATION_OK    : File deleted successfully
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and its
   acceptable parameters.

SEE ALSO

   CreateStdDataFile
   CreateBackupDataFile
   CreateValueFile
   CreateLinearRecordFile
   CreateCyclicRecordFile

[Types] DF_ADDITIONAL_FILE_SETTINGS

NAME

   DF_ADDITIONAL_FILE_SETTINGS

DESCRIPTION

   Union for returning the information supplied by the GetFileSettings command.
   Use stDataFileSettings for Standard Data Files and Backup Data Files.
   Use stValueFileSettings for Value Files.
   Use stRecordFileSettings for Linear Record Files and Cyclic Record Files.

SOURCE

   {
     struct
     {
       DWORD   eFileSize;             //user file size
     } stDataFileSettings;
       
     struct
     {
       LONG    lLowerLimit;           // lower limit of the file
       LONG    lUpperLimit;           // upper limit of the file
       DWORD   eLimitedCredit;        // limited credit value
       BYTE    bLimitedCreditEnabled; // limited credit enabled
     } stValueFileSettings;
     
     struct
     {
       DWORD   eRecordSize;           // record size
       DWORD   eMaxNRecords;          // maximum number of records
       DWORD   eCurrNRecords;         // current number of records
     } stRecordFileSettings;
   } DF_ADDITIONAL_FILE_SETTINGS;

[Functions] GetFileIDs

NAME

   GetFileIDs

DESCRIPTION

   Returns the DESFIRE File IDentifiers of all active files within the currently selected application

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_GetFileIDs(BYTE fid_max_count,
                                     BYTE fid_list[],
                                     BYTE *fid_count);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_GetFileIDs(SPROX_INSTANCE rInst,
                                     BYTE fid_max_count,
                                     BYTE fid_list[],
                                     BYTE *fid_count);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_GetFileIDs(SCARDHANDLE hCard,
                                     BYTE fid_max_count,
                                     BYTE fid_list[],
                                     BYTE *fid_count);

INPUTS

   BYTE fid_max_count          : maximum number of DESFIRE File IDentifiers
   BYTE fid_list[]             : DESFIRE File IDentifiers list 
   BYTE *fid_count             : number of DESFIRE File IDentifiers in the selected application

RETURNS

   DF_OPERATION_OK    : operation succeeded
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and the
   returned values.

SEE ALSO

   GetFileSettings
   ChangeFileSettings

[Functions] GetFileSettings

NAME

   GetFileSettings

DESCRIPTION

   Get information on the properties of a specific file

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_GetFileSettings(BYTE file_id,
                                     BYTE *file_type,
                                     BYTE *comm_mode,
                                     WORD *access_rights,
                                     DF_ADDITIONAL_FILE_SETTINGS *additionnal_settings);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_GetFileSettings(SPROX_INSTANCE rInst,
                                     BYTE file_id,
                                     BYTE *file_type,
                                     BYTE *comm_mode,
                                     WORD *access_rights,
                                     DF_ADDITIONAL_FILE_SETTINGS *additionnal_settings);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_GetFileSettings(SCARDHANDLE hCard,
                                     BYTE file_id,
                                     BYTE *file_type,
                                     BYTE *comm_mode,
                                     WORD *access_rights,
                                     DF_ADDITIONAL_FILE_SETTINGS *additionnal_settings);

INPUTS

   BYTE file_id                : DESFIRE File IDentifier
   BYTE *file_type             : type of file (DF_STANDARD_DATA_FILE, DF_BACKUP_DATA_FILE, 
                                 DF_VALUE_FILE, DF_LINEAR_RECORD_FILE or DF_CYCLIC_RECORD_FILE)
   BYTE *comm_mode             : file's Communication Settings
   WORD *access_rights         : file's Access Rights
   DF_ADDITIONAL_FILE_SETTINGS *additionnal_settings : information file

RETURNS

   DF_OPERATION_OK    : operation succeeded
   Other code if internal or communication error has occured. 

NOTES

   Please refer to DESFIRE datasheet for details regarding this function and the
   returned values.

SEE ALSO

   GetFileIDs
   ChangeFileSettings

[Functions] GetIsoFileIDs

NAME

   GetIsoFileIDs

DESCRIPTION

   Returns the File IDentifiers of all active files within the currently selected application

SYNOPSIS

   [[sprox_desfire.dll]]
   SWORD SPROX_Desfire_GetIsoFileIDs(BYTE fid_max_count,
                                     WORD fid_list[],
                                     BYTE *fid_count);

   [[sprox_desfire_ex.dll]]
   SWORD SPROXx_Desfire_GetIsoFileIDs(SPROX_INSTANCE rInst,
                                      BYTE fid_max_count,
                                      WORD fid_list[],
                                      BYTE *fid_count);

   [[pcsc_desfire.dll]]
   LONG  SCardDesfire_GetIsoFileIDs(SCARDHANDLE hCard,
                                    BYTE fid_max_count,
                                    WORD fid_list[],
                                    BYTE *fid_count);

INPUTS

   BYTE fid_max_count          : maximum number of File IDentifiers
   WORD fid_list[]             : File IDentifiers list 
   BYTE *fid_count             : number of File IDentifiers in the selected application

RETURNS

   DF_OPERATION_OK    : operation succeeded
   Other code if internal or communication error has occured. 

SEE ALSO

   GetFileIDs
   GetIsoDFNames

Generated from sprox_desfire_files.c on Mon Jan 30 14:25:28 2012