Package uicc.suspendresume

Class SuspendUtil

java.lang.Object
uicc.suspendresume.SuspendUtil
public class SuspendUtil extends Object
The SuspendUtil class contains utility methods to compare and manipulate time formated as in the SUSPEND UICC command defined in TS 102 221. The TimeUnit needed for the UICC SUSPEND command, is encoded in seconds, minutes, hours, days and ten days indicating the duration of suspension.

  • Method Summary

    Modifier and Type
    Method
    Description
    static final short
    secondsToTime(byte[] bArray, short bOff, short bLen)
    This method converts the time encoded in the byte array bArray in seconds provided as an unsigned integer to the short value which is composed of the concatenation of TimeUnit and TimeValue.
    The TimeUnit needed for the UICC SUSPEND command, is encoded in seconds, minutes, hours, days and ten days indicating the duration of suspension.
    The value in the array shall be big endian encoded, i.e.
    static final boolean
    timeCompare(byte TimeUnit1, short TimeValue1, short CompareOperation, byte TimeUnit2, short TimeValue2)
    This method compares two provided times Time1 (composed of TimeUnit1 and TimeValue1) and Time2 (composed of TimeUnit2 and TimeValue2) according to the comparison method requested encoded in CompareOperation.
    static final short
    timeToSeconds(byte TimeUnit, short TimeValue, byte[] bArray, short bOff)
    This method converts the provided time Time (composed of TimeUnit and TimeValue) to a value in seconds in the destination array bArray.
    The value in the array is an unsigned integer which is big endian encoded i.e.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • timeCompare

      public static final boolean timeCompare(byte TimeUnit1, short TimeValue1, short CompareOperation, byte TimeUnit2, short TimeValue2) throws SuspendException
      This method compares two provided times Time1 (composed of TimeUnit1 and TimeValue1) and Time2 (composed of TimeUnit2 and TimeValue2) according to the comparison method requested encoded in CompareOperation.
      Parameters:
      TimeUnit1 - time unit of Time1 defined in TIME_UNIT_XXX.
      TimeValue1 - time value of Time1.
      CompareOperation - comparison method defined in COMPARE_IS_XXX.
      TimeUnit2 - time unit of Time2 defined in TIME_UNIT_XXX.
      TimeValue2 - time value of Time2.
      Returns:
      Throws:
      SuspendException - with the following reason codes:

    • timeToSeconds

      public static final short timeToSeconds(byte TimeUnit, short TimeValue, byte[] bArray, short bOff) throws ArrayIndexOutOfBoundsException, NullPointerException, SuspendException
      This method converts the provided time Time (composed of TimeUnit and TimeValue) to a value in seconds in the destination array bArray.
      The value in the array is an unsigned integer which is big endian encoded i.e. with the MSB byte in bOff and the LSB byte in bOff+bLen-1, bLen is the number of bytes needed to represent Time in an unsigned integer. The value of bLen is between 1 to 4.
      Parameters:
      TimeUnit - time unit of Time defined in TIME_UNIT_XXX.
      TimeValue - time value of Time.
      bArray - destination byte array.
      bOff - offset within destination byte array.
      Returns:
      bOff+bLen where bLen is the the number of bytes set in the array.
      Throws:
      SuspendException - with the reason codes:
      ArrayIndexOutOfBoundsException - if the bOff parameter is negative or if bOff+bLen is greater than the length of bArray
      NullPointerException - if the bArray parameter is null

    • secondsToTime

      public static final short secondsToTime(byte[] bArray, short bOff, short bLen) throws ArrayIndexOutOfBoundsException, NullPointerException, SuspendException
      This method converts the time encoded in the byte array bArray in seconds provided as an unsigned integer to the short value which is composed of the concatenation of TimeUnit and TimeValue.
      The TimeUnit needed for the UICC SUSPEND command, is encoded in seconds, minutes, hours, days and ten days indicating the duration of suspension.
      The value in the array shall be big endian encoded, i.e. with the MSB byte in bOff and the LSB byte in bOff+bLen-1 where the value of bLen is between 1 to 4.
      The method secondsToTime converts the suspension time given in seconds to the most appropriate value and unit.

      The strategy for the conversion work as follows:
      • Use the smallest possible TimeUnit in order to achieve the best possible resolution,
      • The value of TimeValue in the resulting unit should be chosen to minimize the inaccuracy with the value provided as input in seconds, however, the method to minimize this inaccuracy is implementation dependent.
      • Upon switching to the next higher TimeUnit the TimeValue in seconds from which the next TimeUnit is used is determined in such a way that the resulting inaccuracy from the conversion is miminized: as a result values of 256 to 277 seconds are encoded as 255 seconds while 278 seconds and up are encoded in 5 minutes and higher, ...

      For details see the following table:
      TimeUnit selection
      Input range in seconds Output Unit Output range
      Minimum Maximum Minimum Maximum
      Dec Hex Dec Hex Dec Hex Dec Hex
      0 0x00 277 0x0115 TIME_UNIT_SECONDS 0 0x00 255 0xFF
      278 0x116 16650 0x410A TIME_UNIT_MINUTES 5 0x05 255 0xFF
      16651 0x410B 934200 0x0E4138 TIME_UNIT_HOURS 5 0x05 255 0xFF
      934201 0x0E4139 22248000 0x01537A40 TIME_UNIT_DAYS 11 0x0B 255 0xFF
      22248001 0x01537A41 221183999 0x0D2EFFFF TIME_UNIT_TEN_DAYS 26 0x1A 255 0xFF
      Parameters:
      bArray - destination byte array.
      bOff - offset within destination byte array.
      bLen - length within destination byte array.
      Returns:
      Encoded Time as:
      • In MSB byte: the time unit selected from the predefined constants TIME_UNIT_XXX in SuspendConstants interface
      • In LSB byte: the maximum acceptable time value as an unsigned byte.
      Throws:
      SuspendException - with the reason code UNEXPECTED_OVERFLOW if the provided value in seconds is above the maximum available (221183999 or 0x0D2EFFFF seconds corresponding to 256 times ten days minus 1 second).
      ArrayIndexOutOfBoundsException - if the bOff parameter is negative or if bOff+bLen is greater than the length of bArray
      NullPointerException - if the bArray parameter is null