Package uicc.suspendresume

Class SuspendUtil

  • public class SuspendUtil
extends java.lang.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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static 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 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 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 Detail

      • 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 java.lang.ArrayIndexOutOfBoundsException,
                                        java.lang.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:
        java.lang.ArrayIndexOutOfBoundsException - if the bOff parameter is negative or if bOff+bLen is greater than the length of bArray
        java.lang.NullPointerException - if the bArray parameter is null

      • secondsToTime

        public static final short secondsToTime​(byte[] bArray,
                                        short bOff,
                                        short bLen)
                                 throws java.lang.ArrayIndexOutOfBoundsException,
                                        java.lang.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).
        java.lang.ArrayIndexOutOfBoundsException - if the bOff parameter is negative or if bOff+bLen is greater than the length of bArray
        java.lang.NullPointerException - if the bArray parameter is null