uicc.access

Interface FileView

All Superinterfaces:

javacard.framework.Shareable

public interface FileView
extends javacard.framework.Shareable

The FileView interface defines the methods to access a UICC file system.
All the methods are based on the commands of the TS 102 221 specification.

See Also:

UICCSystem

Method Summary

Modifier and Type	Method and Description
void	activateFile() This method activates a deactivated EF.
void	deactivateFile() This method deactivates the currently selected EF.
short	increase(byte[] incr, short incrOffset, short incrLength, byte[] resp, short respOffset) This method increases the current cyclic EF record, as defined in TS 102 221.In addition to the behaviour defined in TS 102 221, the following rule applies: If the parameter incrLength is set to 0, the current value of the last increased or updated record is stored into the oldest record of the current cyclic EF.
short	readBinary(short fileOffset, byte[] resp, short respOffset, short respLength) This method reads the data bytes of the current transparent EF.
short	readRecord(short recNumber, byte mode, short recOffset, byte[] resp, short respOffset, short respLength) This method reads a record or a part of a record of the current linear fixed/cyclic EF of the calling applet into the given byte array.
short	searchRecord(byte mode, short recordNum, short searchIndication, byte[] patt, short pattOffset, short pattLength, short[] response, short respOffset, short respLength) This method searches a pattern in the current linear fixed/cyclic EF.
void	select(byte sfi) This method selects a file by SFI in the current directory of the FileView.
void	select(short fid) This method selects a file of the UICC file system or of an ADF file system.
short	select(short fid, byte[] fcp, short fcpOffset, short fcpLength) This method selects a file of the UICC file system or of an ADF file system.
short	status(byte[] fcp, short fcpOffset, short fcpLength) This method returns the FCP (File Control Parameter) of the current selected DF.
void	updateBinary(short fileOffset, byte[] data, short dataOffset, short dataLength) This method updates the data bytes of the current transparent EF.
void	updateRecord(short recNumber, byte mode, short recOffset, byte[] data, short dataOffset, short dataLength) This method updates the data bytes of the record of the current linear fixed/cyclic EF.

Method Detail

select

short select(short fid,
             byte[] fcp,
             short fcpOffset,
             short fcpLength)
      throws java.lang.NullPointerException,
             java.lang.ArrayIndexOutOfBoundsException,
             UICCException

This method selects a file of the UICC file system or of an ADF file system. The file search starts at the current DF of the FileView according to the file search method described in TS 102 221. The file context associated with the FileView object is changed after successful execution. This methods returns the FCP informations in form of a TLV structure as specified in TS 102 221.

Notes:

• If fcpOffset or fcpLength parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
• If fcpOffset+fcpLength is greater than fcp.length, the length of the fcp array a ArrayIndexOutOfBoundsException exception is thrown and no status is performed.

Parameters:

fid - is the File Identifier of the file to be selected.

fcp - is the reference to the target byte array for information of current file, coding is according to TS 102.221.

fcpOffset - is the offset in the fcp buffer for the response data.

fcpLength - is the length of the required data in the fcp byte array. If the fcpLength is greater than the length of the response, the whole response is copied into the fcp buffer and the length of the response is returned by the method. If the fcpLength is smaller than the length of the response, the first part of the response is copied into the fcp buffer and the fcpLength is returned by the method.

Returns:

length of the data which have been written in the fcp buffer (cannot be greater than fcpLength parameter)

Throws:

java.lang.NullPointerException - if fcp is null

java.lang.ArrayIndexOutOfBoundsException - if operation would cause access of data outside array bounds.

UICCException - in case of error

• FILE_NOT_FOUND
• MEMORY_PROBLEM
• INTERNAL_ERROR
• CONDITIONS_OF_USE_NOT_SATISFIED

select

void select(short fid)
     throws UICCException

This method selects a file of the UICC file system or of an ADF file system. The file search starts at the current DF of the FileView according to the file search method described in TS 102 221. The file context associated with the FileView object is changed after successful execution. This SELECT method allows to update the current file without handling the Select Response.

Parameters:

fid - is the File Identifier of the file to be selected.

Throws:

UICCException - in case of error

• FILE_NOT_FOUND
• MEMORY_PROBLEM
• INTERNAL_ERROR
• CONDITIONS_OF_USE_NOT_SATISFIED

select

void select(byte sfi)
     throws UICCException

This method selects a file by SFI in the current directory of the FileView.
The file context associated with the FileView object is changed after successful execution. This SELECT method allows to update the current file without handling the Select Response.

Parameters:

sfi - is the Short File Identifier of the file to be selected.

Throws:

UICCException - in case of error

• FILE_NOT_FOUND if a file with the corresponding SFI is not found or if the sfi parameter is invalid.
• MEMORY_PROBLEM
• INTERNAL_ERROR
• CONDITIONS_OF_USE_NOT_SATISFIED

status

short status(byte[] fcp,
             short fcpOffset,
             short fcpLength)
      throws java.lang.NullPointerException,
             java.lang.ArrayIndexOutOfBoundsException,
             UICCException

This method returns the FCP (File Control Parameter) of the current selected DF.

Notes:

• If fcpOffset or fcpLength parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
• If fcpOffset+fcpLength is greater than fcp.length, the length of the fcp array a ArrayIndexOutOfBoundsException exception is thrown and no status is performed.

Parameters:

fcp - is the reference to the target byte array for FCP (File Control Parameter) of current DF (or MF), coding is according to TS 102.221.

fcpOffset - is the offset in the fcp buffer for the response data.

fcpLength - is the length of the required data in the fcp byte array. If the fcpLength is greater than the length of the response, the whole response is copied into the fcp buffer and the length of the response is returned by the method. If the fcplength is smaller than the length of the response, the first part of the response is copied into the fcp buffer and the fcpLength is returned by the method.

Returns:

length of the data which have been written in the fcp buffer (cannot be greater than fcpLength parameter)

Throws:

java.lang.NullPointerException - if fcp is null

java.lang.ArrayIndexOutOfBoundsException - if operation would cause access of data outside array bounds.

UICCException - in case of error

• MEMORY_PROBLEM
• INTERNAL_ERROR

readBinary

short readBinary(short fileOffset,
                 byte[] resp,
                 short respOffset,
                 short respLength)
          throws java.lang.NullPointerException,
                 java.lang.ArrayIndexOutOfBoundsException,
                 UICCException

This method reads the data bytes of the current transparent EF.

Notes:

• If respOffset or respLength parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
• If respOffset+respLength is greater than resp.length, the length of the resp array a ArrayIndexOutOfBoundsException exception is thrown and no read is performed.

Parameters:

fileOffset - is the offset in the source transparent file.

resp - is the reference to the response byte array for read data.

respOffset - is the offset in the response byte array.

respLength - is the number of bytes to read.

Returns:

respOffset+respLength

Throws:

java.lang.NullPointerException - if resp is null

java.lang.ArrayIndexOutOfBoundsException - if reading would cause access of data outside array bounds

UICCException - in case of error

• INTERNAL_ERROR
• OUT_OF_FILE_BOUNDARIES
• COMMAND_INCOMPATIBLE
• SECURITY_STATUS_NOT_SATISFIED
• REF_DATA_INVALIDATED
• NO_EF_SELECTED
• COMMAND_NOT_ALLOWED if the referenced file is terminated

updateBinary

void updateBinary(short fileOffset,
                  byte[] data,
                  short dataOffset,
                  short dataLength)
           throws java.lang.NullPointerException,
                  java.lang.ArrayIndexOutOfBoundsException,
                  UICCException

This method updates the data bytes of the current transparent EF.

Notes:

• If dataOffset or dataLength parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
• If dataOffset+dataLength is greater than data.length, the length of the data array a ArrayIndexOutOfBoundsException exception is thrown and no update is performed.

Parameters:

fileOffset - is the offset in the destination transparent file.

data - is the reference to the source byte array for data to update.

dataOffset - is the offset in the data byte array.

dataLength - is the number of bytes to update.

Throws:

java.lang.NullPointerException - if data is null

java.lang.ArrayIndexOutOfBoundsException - if updating would cause access of data outside array bounds

UICCException - in case of error

• MEMORY_PROBLEM
• INTERNAL_ERROR
• COMMAND_INCOMPATIBLE
• SECURITY_STATUS_NOT_SATISFIED
• REF_DATA_INVALIDATED
• NO_EF_SELECTED
• OUT_OF_FILE_BOUNDARIES
• COMMAND_NOT_ALLOWED if the referenced file is terminated

readRecord

short readRecord(short recNumber,
                 byte mode,
                 short recOffset,
                 byte[] resp,
                 short respOffset,
                 short respLength)
          throws java.lang.NullPointerException,
                 java.lang.ArrayIndexOutOfBoundsException,
                 UICCException

This method reads a record or a part of a record of the current linear fixed/cyclic EF of the calling applet into the given byte array. The current record pointer can be changed due to the chosen mode.

Notes:

• If respOffset or respLength parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
• If respOffset+respLength is greater than resp.length, the length of the resp array a ArrayIndexOutOfBoundsException exception is thrown and no read is performed.

Parameters:

recNumber - is the record number (for absolute mode only)

mode - is the mode for reading record

recOffset - is the offset in the record for the data to read.

resp - is the reference to the response byte array for read data.

respOffset - is the offset in the response byte array.

respLength - is the number of bytes to read.

Returns:

respOffset+respLength

Throws:

java.lang.NullPointerException - if resp is null

java.lang.ArrayIndexOutOfBoundsException - if reading would cause access of data outside array bounds

UICCException - in case of error

• OUT_OF_RECORD_BOUNDARIES
• INTERNAL_ERROR
• COMMAND_INCOMPATIBLE
• SECURITY_STATUS_NOT_SATISFIED
• REF_DATA_INVALIDATED
• NO_EF_SELECTED
• INVALID_MODE
• RECORD_NOT_FOUND
• COMMAND_NOT_ALLOWED if the referenced file is terminated

updateRecord

void updateRecord(short recNumber,
                  byte mode,
                  short recOffset,
                  byte[] data,
                  short dataOffset,
                  short dataLength)
           throws java.lang.NullPointerException,
                  java.lang.ArrayIndexOutOfBoundsException,
                  UICCException

This method updates the data bytes of the record of the current linear fixed/cyclic EF. The current record pointer can be changed due to the chosen mode.

Notes:

• If dataOffset or dataLength parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
• If dataOffset+dataLength is greater than data.length, the length of the data array a ArrayIndexOutOfBoundsException exception is thrown and no update is performed.

Parameters:

recNumber - is the record number, if null then mode is used

mode - is the mode for updating record, if recNumber is given then mode is in ABSOLUTE mode

recOffset - is the offset in the record for the data to update.

data - is the reference to the source byte array for data to update.

dataOffset - is the offset in the source byte array.

dataLength - is the number of bytes to update.

Throws:

java.lang.NullPointerException - if data is null

java.lang.ArrayIndexOutOfBoundsException - if updating would cause access of data outside array bounds

UICCException - in case of error

• COMMAND_INCOMPATIBLE
• SECURITY_STATUS_NOT_SATISFIED
• REF_DATA_INVALIDATED
• OUT_OF_RECORD_BOUNDARIES
• RECORD_NOT_FOUND
• NO_EF_SELECTED<
• MEMORY_PROBLEM
• INVALID_MODE
• INTERNAL_ERROR
• COMMAND_NOT_ALLOWED if the referenced file is terminated

searchRecord

short searchRecord(byte mode,
                   short recordNum,
                   short searchIndication,
                   byte[] patt,
                   short pattOffset,
                   short pattLength,
                   short[] response,
                   short respOffset,
                   short respLength)
            throws java.lang.NullPointerException,
                   java.lang.ArrayIndexOutOfBoundsException,
                   UICCException

This method searches a pattern in the current linear fixed/cyclic EF.

Notes:

• If patOffset or pattLength or respOffset or respLengthparameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
• If pattOffset+pattLength is greater than patt.length, the length of the patt array a ArrayIndexOutOfBoundsException exception is thrown and no search is performed.
• If respOffset+respLength is greater than response.length, the length of the response array a ArrayIndexOutOfBoundsException exception is thrown and no search is performed.

Parameters:

mode - is the search mode, according to TS 102.221 (no type information).

recordNum - is the record number to start the search, 0 indicates from the current record

searchIndication - indication of the search mode for the enhanced search

patt - is the reference to the byte array containing the search pattern.

pattOffset - is the offset of the search pattern in the byte array.

pattLength - is the length of the search pattern.

response - reference to response array to hold the record numbers

respOffset - is the offset into the response array to store the record numbers

respLength - - is the maximum number of elements to be copied into the response array. If the respLength is greater than the number of records found, the whole response is copied into the response buffer and the number of elements copied is returned by the method. If the respLength is smaller than the number of records found, the first respLength record numbers are copied into the response buffer and respLength is returned by the method.

Returns:

number of array elements copied into the response array. Returns 0 if no record containing containing the pattern was found.

Throws:

java.lang.NullPointerException - if patt is null

java.lang.ArrayIndexOutOfBoundsException - if searching would cause access of data outside array bounds

UICCException - in case of error

• INTERNAL_ERROR
• OUT_OF_RECORD_BOUNDARIESif pattLengthis greater than the record size
• COMMAND_INCOMPATIBLE
• SECURITY_STATUS_NOT_SATISFIED
• REF_DATA_INVALIDATED
• NO_EF_SELECTED
• RECORD_NOT_FOUND: record with number recordNum not found in file
• INVALID_MODE
• COMMAND_NOT_ALLOWED if the referenced file is terminated

increase

short increase(byte[] incr,
               short incrOffset,
               short incrLength,
               byte[] resp,
               short respOffset)
        throws java.lang.NullPointerException,
               java.lang.ArrayIndexOutOfBoundsException,
               UICCException

This method increases the current cyclic EF record, as defined in TS 102 221.In addition to the behaviour defined in TS 102 221, the following rule applies: If the parameter incrLength is set to 0, the current value of the last increased or updated record is stored into the oldest record of the current cyclic EF. The record pointer is set to the oldest record and this record becomes record number 1. The response buffer will contain the value of the increased record.

Notes:

• If incrOffset or incrLength or respOffset parameter is negative an ArrayIndexOutOfBoundsException exception is thrown.
• If incrOffset+incrLength is greater than increase.length, the length of the increase array an ArrayIndexOutOfBoundsException exception is thrown and no increase is performed.
• If respOffset is greater than response.length, the length of the response array a ArrayIndexOutOfBoundsException exception is thrown and no increase is performed.

Parameters:

incr - is the reference to the source byte array, containing the value to increase. The increase is only performed if the result would not exceed the maximum value of the record.

incrOffset - is the offset in the source byte array.

incrLength - is the length of the data in the incr array, 0<= incrLength <128

resp - is the reference to the response byte array for the new record value. If resp buffer is bigger than the record size, the resp buffer is filled with the record value and left justified.

respOffset - is the offset in the response byte array.

Returns:

length of the valid data in the resp buffer

Throws:

java.lang.NullPointerException - if incr or resp is null

java.lang.ArrayIndexOutOfBoundsException - if increasing would cause access of data outside array bounds

UICCException - in case of error

• NO_EF_SELECTED
• MEMORY_PROBLEM
• INTERNAL_ERROR
• COMMAND_INCOMPATIBLE
• SECURITY_STATUS_NOT_SATISFIED
• REF_DATA_INVALIDATED
• RECORD_NOT_FOUND
• MAX_VALUE_REACHED
• COMMAND_NOT_ALLOWED if the referenced file is terminated

deactivateFile

void deactivateFile()
             throws UICCException

This method deactivates the currently selected EF. No exception shall be thrown when deactivating an already deactivated EF.

Throws:

UICCException - in case of error

• NO_EF_SELECTED
• SECURITY_STATUS_NOT_SATISFIED
• INTERNAL_ERROR
• COMMAND_NOT_ALLOWED if the referenced file is terminated

activateFile

void activateFile()
           throws UICCException

This method activates a deactivated EF. No exception shall be thrown when activating an already activated EF.

Throws:

UICCException - in case of error

• NO_EF_SELECTED
• SECURITY_STATUS_NOT_SATISFIED
• INTERNAL_ERROR
• COMMAND_NOT_ALLOWED if the referenced file is terminated