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_i for a unix epoch in seconds
-
use .to_f for a unix epoch with fractions
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
@param tstamp A representation of a timestampe
# 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
@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
@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
# 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
@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
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