uicc.access

## Interface FileView

- All Known Subinterfaces:
    AdminBERTLVFileView, AdminFileView, BERTLVFileView

      public interface FileView

  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 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. 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 `respLength` parameter 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_BOUNDARIES`if `pattLength`is 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

Copyright © 2017 ETSI All Rights Reserved.