Field Detail

• CLOCK_SOURCE_PRTC

  public static final byte CLOCK_SOURCE_PRTC

  Calendar instances created with this clock source will configure their time based on secure time - Protected Real Time Clock.

  See Also:

  Constant Field Values

• SET_TIME_INFO_LENGTH

  public static final byte SET_TIME_INFO_LENGTH

  The size that must be used for the set_time_info array when calling the setTime method.

  See Also:

  setTime(int, byte[], int), Constant Field Values

Method Detail

• createDateTime

  public static Calendar.DateTime createDateTime(short year,
                                 byte month,
                                 byte day,
                                 byte hour,
                                 byte minute,
                                 byte second)
                                          throws UtilException

  Creates a new DateTime instance.
  All parameters are treated as binary (non-BCD) format. Hours are represented by 24-hour format.
  

  Parameters:

  year - the year part of the DateTime is number from the range [0,32767].

  month - the month part of the DateTime is number from the range [1,12].

  day - the day part of the DateTime is number from the range [1,31].

  hour - the hour part of the DateTime is number from the range [0,23].

  minute - the minute part of the DateTime is number from the range [0,59].

  second - the second part of the DateTime is number from the range [0,59].

  Returns:

  A new DateTime instance with the specified configuration

  Throws:

  IllegalParameterException - if one or more of the DateTime parameters are not in the range.

  UtilException - if an internal error occurred

• createDateTime

  public static Calendar.DateTime createDateTime(int unixTime)

  Creates a new DateTime instance.
  The UNIX time must be in the range between "01 January 2000 00:00:00" and the "19 January 2038 03:14:07".
  

  Parameters:

  unixTime - UNIX timestamp format (number of seconds elapsed since January 1, 1970).

  Returns:

  A new DateTime instance converted from UNIX time.

  Throws:

  IllegalParameterException - if UNIX time is not in the range.

  UtilException - if an internal error occurred

• createTimeRange

  public static Calendar.TimeRange createTimeRange(Calendar.DateTime start,
                                   Calendar.DateTime end)
                                            throws UtilException

  Creates a new Calendar.TimeRange. The time range is closed and bounded from both sides. It means that, point is in the range if and only if point is either strictly between two end-point or is equals to one of the end-points.
  The range can be defined as follows: (start,end) = {x | start

  Parameters:

  start - the range's starting date time

  end - the range's ending date time

  Returns:

  A new TimeRange instance with the specified configuration

  Throws:

  IllegalParameterException - if 'start' parameter is later than 'end' parameter.

  UtilException

  • getMillisFromStartup

    public static long getMillisFromStartup()
                                     throws UtilException

    Returns the number of milli-seconds from the system startup

    Returns:

    the number of milli-seconds from the system startup

    Throws:

    UtilException - when an internal error occurred

  • getInstance

    public static final Calendar getInstance(byte clock_source,
                       TimeZone zone)
                                      throws UtilException

    Creates a Calendar instance that will use the specified clock source.

    Parameters:

    clock_source - defines the clock source for the created instance. The available sources are:

    • CLOCK_SOURCE_PRTC

    zone - defines the TimeZone to be used along with this instance. This parameter must be set for CLOCK_SOURCE_PRTC.

    Returns:

    The Calendar instance based on the specified clock source.

    Throws:

    IllegalParameterException - in the following cases:

    • If the clock source is CLOCK_SOURCE_PRTC and zone is null.
    • If the clock source specified is invalid.

    UtilException

  • setTimeZone

    public abstract void setTimeZone(TimeZone zone)
                              throws UtilException

    Updates the time zone used by this Calendar instance.

    Parameters:

    zone - the new Time zone to be used with this Calendar

    Throws:

    IllegalParameterException - when this method is used on an instance based on calendar type CLOCK_SOURCE_PRTC and the zone is null.

    UtilException

  • setTime

    public abstract void setTime(int time,
               byte[] set_time_info,
               int offset)
                          throws UtilException

    Sets the time for this Calendar instance. Calling this method has no impact on the time of any applet except the caller applet. Upon return, the caller receives the configured time meta-data (which includes an applet offset from the secure time and the current secure time version). This data must be saved by the applet (for example, in hard drive storage) and used as input in any subsequent calls to the getTime method.

    Parameters:

    time - the current time in UNIX timestamp format (number of seconds elapsed since January 1, 1970). Maximal representable time is "20 Jan 2031 03:14:07 GMT".

    set_time_info - a byte array that, when returned, holds the meta-data of this time configuration. The method will write into the array the meta_data of this time configuration whose size is SET_TIME_INFO_LENGTH bytes. The applet does not need to know the internal structure of this data.

    offset - the offset in the set_time_info array

    Throws:

    IllegalParameterException - when the time is invalid (earlier than the current PRTC time, or a number which is more than the number of seconds elapsed between 1970 and 2031).

    NotSupportedException - in case FEATURE_SET_SECURE_TIME is not enabled.

    UtilException - in case of an internal error.

  • getTime

    public abstract int getTime(byte[] set_time_info,
              int offset)
                         throws UtilException

    Gets the current time of this Calendar instance. If a TimeZone instance was configured for this Calendar instance, the time zone offset is added to the time base of this Calendar instance and returned as the current time by this method.

    Calling this method on an instance based on the calendar type CLOCK_SOURCE_PRTC without first calling the setTime method, will act as if SetTime was called with 0 param.

    Note: When Calendar is supported (PlatformInfo.getFeatureSet() FEATURE_SET_SECURE_TIME is enabled) and
    PlatformInfo.isCoinBatteryPresent() returns false, the Calendar may reset occasionally.
    (see details in PlatformInfo.isCoinBatteryPresent()).

    Parameters:

    offset - the offset in the set_time_info array which points to the beginning of the set_time_info data.

    set_time_info - the byte array holding time configuration meta-data that was received from the setTime method. If all valus in this array are zeros, then the offset from the PRTC will be returned. Calling with set_time_info with all zeros will return the current offset from the PRTC.

    Returns:

    The current time in UNIX timestamp format (number of seconds elapsed since January 1, 1970). If a TimeZone instance was configured for this Calendar instance, the time zone offset will be added to the time base.

    Throws:

    IllegalParameterException - when set_time_info is invalid (for example, the offset from PRTC time is invalid, or the version is different from the current PRTC version due to RTC reset). In such cases calling the setTime method again might resolve the problem.

    NotSupportedException - in case FEATURE_SET_SECURE_TIME is not enabled.

    UtilException - in case of an internal error.