com.nokia.nfc.nxp.mfstd
Interface MFApplicationDirectory

public interface MFApplicationDirectory

Provides access to Mifare Standard Card's application directory (MAD).

The create and delete methods of this interface communicate with the card. The rest of the methods use the information that was read from the card during the getApplicationDirectory and createApplicationDirectory of the MFStandardConnection interface. Calling the create and delete methods of course update this information.

Applications are identified by using application identifiers (AID). The term AID slot refers to a sector that is reserved for application use. The first AID slot index is 0 and it refers to the sector number 1. If MAD version 2 is used then the AID slot index 15 refers to sector number 17 - the second MAD sector is sector number 16 and is not a valid AID slot. MAD version 1 means that the first sector of a 1k or 4k card is used for storing the application directory information. If MAD version 2 is used then sector number 16 is also used for storing this information. MAD version 2 only applies for Mifare Standard 4k cards.

Application identifiers are represented in this interface as byte arrays. The array has two bytes. The first byte in the array is the least significant byte, i.e. the application code. The second byte is the most significant byte - the function cluster code.

MAD trailer is updated only when the GPB needs to be changed. If default keys are being used and the trailer must be written then the key 0xFFFFFFFFFFFF is used as the B key.

Field Summary

static int

AID_LENGTH Amount of bytes used for representing an application identifier.

Method Summary

boolean	canWrite() Checks whether if modifying the MAD area is allowed using this MFApplicationDirectory instance, i.e. whether the application directory was opened in read-only mode or not.
MFApplication	create(byte[] newAID, byte[] initialContents, MFTrailerContents trailer, boolean continuous) Creates a new application with given the AID and contents.
MFApplication	create(byte[] newAID, int[] entryIndexes, MFTrailerContents trailer) Creates a new application with given the AID and reserves the specified slots for the application.
MFApplication	create(byte[] newAID, int sizeToAllocate, MFTrailerContents trailer, boolean continuous) Creates a new application with given the AID.
void	delete(byte[] aid) Deletes the application specified by the application identifier.
byte[]	getAID(int aidIndex) Returns the AID of the application in slot aidIndex.
int	getApplicationCount() Returns the number of different applications listed in the application directory.
int	getGPB() Returns the general purpose byte (GPB) of the MAD.
int	getInfo() Returns the contents of the MAD's Info field.
int	getVersion() Returns the version of the MAD.
boolean	isFree(int aidIndex) Checks whether the specified AID slot is free, i.e. not reserved for any application.
int	numSlots() Returns the amount of AID slots.
MFApplication	open(byte[] aid) Opens access to the specified application.
int	size(boolean continuous) Returns the number of bytes available for applications, i.e. the number of bytes not reserved for any application.

Field Detail

AID_LENGTH

static final int AID_LENGTH

Amount of bytes used for representing an application identifier.

See Also:

Constant Field Values

Method Detail

canWrite

boolean canWrite()

Checks whether if modifying the MAD area is allowed using this MFApplicationDirectory instance, i.e. whether the application directory was opened in read-only mode or not.

Returns:

true if writing is allowed and false if not.

getAID

byte[] getAID(int aidIndex)

Returns the AID of the application in slot aidIndex.

Parameters:

aidIndex - index of the AID slot.

Returns:

the AID of the application in the specified slot.

Throws:

java.lang.IllegalArgumentException - if aidIndex < 0 or aidIndex > numSlots()-1.

isFree

boolean isFree(int aidIndex)

Checks whether the specified AID slot is free, i.e. not reserved for any application.

Parameters:

aidIndex - index of the AID slot.

Returns:

true if the AID slot is not reserved for any application and false if it is.

Throws:

java.lang.IllegalArgumentException - if aidIndex < 0 or aidIndex > numSlots()-1.

numSlots

int numSlots()

Returns the amount of AID slots. The return value is different in Mifare Standard 1k and 4k cards.

Returns:

the total number of application identifier slots.

getApplicationCount

int getApplicationCount()

Returns the number of different applications listed in the application directory.

Returns:

number of applications in MAD.

size

int size(boolean continuous)

Returns the number of bytes available for applications, i.e. the number of bytes not reserved for any application. If the parameter continous is set to true then this method will return the largest continuous data area available.

Parameters:

continuous - if only continues free areas should be checked.

Returns:

available space for applications in bytes.

getInfo

int getInfo()

Returns the contents of the MAD's Info field. The Info field is a single byte.

Returns:

the Info field.

getVersion

int getVersion()

Returns the version of the MAD.

Returns:

the MAD version.

See Also:

MFStandardConnection.MAD_V1, MFStandardConnection.MAD_V2

getGPB

int getGPB()

Returns the general purpose byte (GPB) of the MAD. If MAD version 2 is used then for both sectors to be valid the GPBs must be equal.

Returns:

the general purpose byte.

open

MFApplication open(byte[] aid)
                   throws java.io.IOException,
                          MFStandardException

Opens access to the specified application.

Parameters:

aid - the application identifier.

Returns:

MFApplication instance, null if the application does not exist.

Throws:

MFStandardException - if authentication fails.

java.io.IOException - if a connection error occurs.

java.lang.IllegalArgumentException - if aid.length is not AID_LENGTH.

java.lang.NullPointerException - if aid is null.

delete

void delete(byte[] aid)
            throws java.io.IOException,
                   MFStandardException

Deletes the application specified by the application identifier. Deleting means marking the sectors reserved for the application as free. Free sectors use the identifier 0x00 00.

Parameters:

aid - the application identifier.

Throws:

MFStandardException - if authentication fails or this object is in read-only mode.

java.io.IOException - if a connection error occurs.

java.lang.IllegalArgumentException - if the application does not exist.

java.lang.IllegalArgumentException - if aid.length is not AID_LENGTH.

java.lang.NullPointerException - if the aid is null.

create

MFApplication create(byte[] newAID,
                     int sizeToAllocate,
                     MFTrailerContents trailer,
                     boolean continuous)
                     throws java.io.IOException,
                            MFStandardException

Creates a new application with given the AID. Reserves the specified amount of space for the application (as number of sectors). If the trailer parameter is null then it is left up to the application to initialize the trailers. This method will update the MAD contents and if necessary write the trailers of the reserved sectors.

Note that the trailer object must always define both authentication keys and access bits.

Parameters:

newAID - identifier of the application

sizeToAllocate - number of sectors to reserve for the application.

trailer - the sector trailer contents to be used for application's sectors.

continuous - defines if the reserved area should be continuous or not.

Returns:

the created application, never null.

Throws:

MFStandardException - if authentication fails or this object is in read-only mode.

java.io.IOException - if a connection error occurs.

java.lang.IllegalArgumentException - if the specified space cannot be reserved for the application or sizeToAllocate is 0.

java.lang.IllegalArgumentException - if newAID.length is not AID_LENGTH.

java.lang.NullPointerException - if the newAID is null.

create

MFApplication create(byte[] newAID,
                     byte[] initialContents,
                     MFTrailerContents trailer,
                     boolean continuous)
                     throws java.io.IOException,
                            MFStandardException

Creates a new application with given the AID and contents. The amount of reserved sectors is decided based on the length of the initialContents array. If the trailer parameter is null then it is left up to the application to initialize the trailers. This method will update the MAD contents, write the initial contents to the reserved sectors and if necessary write the trailers of the reserved sectors.

The key B of the specified trailer will be used for writing data to the reserved sectors. The initial contents will be written to the beginning of the reserved application area.

Note that the trailer object must always define both authentication keys and access bits.

Parameters:

newAID - identifier of the application

initialContents - the initial application contents to be written.

trailer - the sector trailer contents to be used for application's sectors.

continuous - defines if the reserved area should be continuous or not.

Returns:

the created application, never null.

Throws:

MFStandardException - if authentication fails or this object is in read-only mode.

java.io.IOException - if a connection error occurs.

java.lang.IllegalArgumentException - if the initialContents length is 0.

java.lang.IllegalArgumentException - if the specified space cannot be reserved for the application.

java.lang.IllegalArgumentException - if newAID.length is not AID_LENGTH.

java.lang.NullPointerException - if the newAID or initialContents is null.

create

MFApplication create(byte[] newAID,
                     int[] entryIndexes,
                     MFTrailerContents trailer)
                     throws java.io.IOException,
                            MFStandardException

Creates a new application with given the AID and reserves the specified slots for the application. If the trailer parameter is null then it is left up to the application to initialize the trailers. This method will update the MAD contents and if necessary write the trailers of the reserved sectors.

Note that the trailer object must always define both authentication keys and access bits.

The entryIndexes array must be ordered so that the first element specifies the slot with the smallest slot index and the last element specifies the slot with the largest slot index.

Parameters:

newAID - identifier of the application

entryIndexes - the AID slots to reserve for the application.

trailer - the sector trailer contents to be used for application's sectors.

Returns:

the created application, never null.

Throws:

MFStandardException - if authentication fails or this object is in read-only mode.

java.io.IOException - if a connection error occurs.

java.lang.IllegalArgumentException - if the entryIndexes length is 0.

java.lang.IllegalArgumentException - if the specified space cannot be reserved for the application.

java.lang.IllegalArgumentException - if newAID.length is not AID_LENGTH.

java.lang.NullPointerException - if the newAID or entryIndexes is null.