class Jamf::Timestamp

A timestamp as used in the Jamf Pro API JSON data

Instantiate with any of:

- A string parsable by Time.parse. Timestamps from the API are always
  strings in iso6801 format
- a Time or Jamf::Timestamp instance
- an Integer, or Stringified Integer, a unix epoch value. If it is
  1_000_000_000_000 or higher, it is treated as a Jamf-stype epoch,
  meaning the last 3 digits are milliseconds.
- nil or an empty string, which will 'unset' a time value with an empty
  string when sent back to the API

To unset a timestamp value in the API, instantiate one of these with nil or an empty string. The Time value will be ‘1970-01-01 00:00:00 -0000’, the unix epoch, and the to_jamf method will return an empty string, which is what will be sent to the API

NOTE: Passing ‘1970-01-01 00:00:00 -0000’ or the equivalent explicitly will NOT be treated as an empty timestamp, but as that actual value. You must pass nil or an empty string to indicate an empty value

TODO: Find out: will an empty string work, e.g. in ext attrs with a DATE value, when used in criteria?

This class is a subclass of Time, so all Time methods are available.

Use to_jamf to get the formated string to use in JSON for sending to the API - it should always be in ISO8601 format, or an empty string.

Constants

J_EPOCH_INT_START

Integers with this value or higher are a jamf-style epoch, meaning the first 10 digits are a unix epoch, and the last 3 are milliseconds. Integers below this shouldn’t appear, but will be treated as a regular unix epoch. (999_999_999_999 = 33658-09-27 01:46:39 UTC)

J_EPOCH_STR_LEN

Stings containing integers of this length are a jamf-style epoch, meaning the first 10 digits are a unix epoch, and the last 3 are milliseconds. This length-test will be valid until the year 2286.

NIL_TIMESTAMP

When we are unsetting a timestamp by intializing with nil, we still have to have a time object - so use the unix epoch

Public Class Methods

new(tstamp) click to toggle source

@param tstamp A representation of a timestampe

Calls superclass method
   # File lib/jamf/api/jamf_pro/other_classes/timestamp.rb
79 def initialize(tstamp)
80   # use a Time object to parse the input and generate our own
81   # object
82   time = parse_init_tstamp(tstamp)
83 
84   super(
85     time.year,
86     time.month,
87     time.day,
88     time.hour,
89     time.min,
90     (time.sec + (time.usec / 1_000_000.0)).round(3),
91     time.utc_offset
92   )
93 end

Public Instance Methods

msec() click to toggle source

@return [Integer] the milliseconds of the Time

    # File lib/jamf/api/jamf_pro/other_classes/timestamp.rb
 96 def msec
 97   return 0 if @empty_timestamp
 98 
 99   (usec / 1000.0).round
100 end
to_jamf() click to toggle source

@return [String] the timestamp formatted for passing to the API as a string.

    # File lib/jamf/api/jamf_pro/other_classes/timestamp.rb
103 def to_jamf
104   return Jamf::BLANK if @empty_timestamp
105 
106   iso8601
107 end
to_jamf_epoch() click to toggle source
    # File lib/jamf/api/jamf_pro/other_classes/timestamp.rb
109 def to_jamf_epoch
110   (to_f.round(3) * 1000).to_i
111 end

Private Instance Methods

parse_init_tstamp(tstamp) click to toggle source

@param tstamp @see initialize @return [Time]

    # File lib/jamf/api/jamf_pro/other_classes/timestamp.rb
119 def parse_init_tstamp(tstamp)
120   case tstamp
121   when Time
122     tstamp
123 
124   when Integer
125     Time.at real_epoch_from_j_epoch(tstamp)
126 
127   when /^\d+$/
128     Time.at real_epoch_from_j_epoch(tstamp.to_i)
129 
130   when Jamf::BLANK, nil
131     @empty_timestamp = true
132     NIL_TIMESTAMP
133 
134   else
135     Time.parse tstamp.to_s
136   end # case
137 end
real_epoch_from_j_epoch(j_epoch) click to toggle source

convert an integer into a float if needed for parsing @param j_epoch [Integer] @return [Integer, Float]

    # File lib/jamf/api/jamf_pro/other_classes/timestamp.rb
142 def real_epoch_from_j_epoch(j_epoch)
143   j_epoch >= J_EPOCH_INT_START ? (j_epoch / 1000.0) : j_epoch
144 end