Package uicc.access

Interface FileView

  • All Superinterfaces:
    javacard.framework.Shareable
    All Known Subinterfaces:
    AdminBERTLVFileView, AdminFileView, BERTLVFileView
    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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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.
      The file context associated with the FileView object is changed after successful execution.
      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