Class: DevId::DeviceUuid

Inherits:
DeviceIdentifier show all
Defined in:
lib/dev-id/device_uuid.rb

Overview

Model for a device UUID.

16 bytes.

Constant Summary collapse

DEFAULT_TO_PRETTY_OPTS =

Default options for conversion to ASCII in the pretty method.

{
  :sep => '-',  # typically "-"
  :upcase => false,
}.freeze
UUID_VARIANT_NCS =

0b0xx, reserved, NCS backward compatibility (also used for the nil UUID)

:ncs
UUID_VARIANT_RFC_4122 =

0b10x, the variant specified by RFC 4122

:rfc4122
UUID_VARIANT_MICROSOFT =

0b110, reserved, Microsoft backward compatibility

:microsoft
UUID_VARIANT_FUTURE =

0b111, reserved for future definition

:future

Constants inherited from BinaryAddress

BinaryAddress::DEFAULT_TO_ASCII_OPTS

Instance Attribute Summary

Attributes inherited from BinaryAddress

#raw

Instance Method Summary collapse

Methods inherited from BinaryAddress

#!~, #<=>, #==, #=~, #ascii, #before_validation, #bytes, #bytesize, #byteslice, from_hex, from_raw, #getbyte, #starts_with?, #to_int

Methods inherited from BasicActiveModel

#assign_attributes, #before_validation, #do_before_validation, #initialize, #persisted?

Constructor Details

This class inherits a constructor from DevId::BasicActiveModel

Instance Method Details

#null? ⇒ Boolean

Whether the device UUID is the “nil”/“null” address (16 NULL bytes).

Returns:



30
31
32
33
 
# File 'lib/dev-id/device_uuid.rb', line 30

def null?
  return nil  if ! valid?
  return raw == (?\0.force_encoding( ::Encoding::ASCII_8BIT ) * 16)
end

#pretty(opts = nil) ⇒ Object

Pretty ASCII representation in UUID format (8-4-4-4-12).



37
38
39
40
41
42
43
44
45
 
# File 'lib/dev-id/device_uuid.rb', line 37

def pretty( opts = nil )
  return nil  if ! valid?
  opts = DEFAULT_TO_PRETTY_OPTS.merge( opts || {} )
  #return ascii( opts )
  #return ::Kernel.sprintf( '%.2x%.2x%.2x%.2x-%.2x%.2x-%.2x%.2x-%.2x%.2x-%.2x%.2x%.2x%.2x%.2x%.2x', * self.bytes )
  uuid_str = raw.unpack( 'H8H4H4H4H12' ).join( opts[:sep] )
  uuid_str = uuid_str.upcase  if opts[:upcase]
  return uuid_str
end

#to_s(opts = nil) ⇒ Object

to_s is an alias for pretty.



59
60
61
 
# File 'lib/dev-id/device_uuid.rb', line 59

def to_s( opts = nil )
  pretty( opts )
end

#uuid ⇒ Object 



68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/dev-id/device_uuid.rb', line 68

def uuid
  if @uuid == nil
    if ! valid?
      @uuid = false
    else
      require_uuid_tools()
      @uuid = ::UUIDTools::UUID.parse_raw( raw )
    end
  end
  @uuid
end

#uuid_mac_addr ⇒ Object

Returns the MAC address (lowercase, “:”-separated) used to generate this UUID, or nil if a MAC address was not used. Applies only to version 1 UUIDs with a given (i.e. non-random) node ID.



174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/dev-id/device_uuid.rb', line 174

def uuid_mac_addr
  #return nil  if ! uuid
  #return nil  if ! uuid_variant_rfc4122?
  #return uuid.mac_address.upcase
  
  return nil  if ! valid?
  return nil  if ! uuid_variant_rfc4122?
  return nil  if uuid_version != 1
  return nil  if uuid_random_node_id?
  opts = ::DevId::MacAddress::DEFAULT_TO_PRETTY_OPTS
  return self.byteslice( 10, 6 ).bytes.map{ |b| (opts[:upcase] ? '%02X' : '%02x') % [b] }.join( opts[:sep] )
end

#uuid_random_node_id? ⇒ Boolean

This method applies only to version 1 UUIDs. Checks if the node ID was generated from a random number or from a MAC address. Always returns false for UUIDs that aren’t version 1. This should not be confused with version 4 UUIDs where more than just the node ID is random.

Returns:



193
194
195
196
197
198
199
200
201
202
 
# File 'lib/dev-id/device_uuid.rb', line 193

def uuid_random_node_id?
  #return nil  if ! uuid
  #return nil  if ! uuid_variant_rfc4122?
  #return uuid.random_node_id?
  
  return nil  if ! valid?
  return nil  if ! uuid_variant_rfc4122?
  return false  if uuid_version != 1
  return ((raw.getbyte( 10 ) & 0x01) == 1)
end

#uuid_str ⇒ Object

Pretty ASCII representation in UUID format (8-4-4-4-12).

This is the same as .pretty with default options ({ :sep => ‘-’, :upcase => false }) but slightly faster.



52
53
54
55
 
# File 'lib/dev-id/device_uuid.rb', line 52

def uuid_str
  return nil  if ! valid?
  return raw.unpack( 'H8H4H4H4H12' ).join( '-' )
end

#uuid_timestamp ⇒ Object

This method applies only to version 1 UUIDs. Returns the timestamp used to generate this UUID.

Returns:

  • Time instance timestamp



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/dev-id/device_uuid.rb', line 209

def uuid_timestamp
  return nil  if ! uuid
  return nil  if ! uuid_variant_rfc4122?
  #return uuid.timestamp
  
  return nil  if ! valid?
  return nil  if ! uuid_variant_rfc4122?
  return nil  if uuid_version != 1
  
  tlmh = raw.unpack('Nnn')  # time_low, time_mid, time_hi_and_version
  t_utc_100_ns = tlmh[0] + (tlmh[1] << 32) + ((tlmh[2] & 0x0FFF) << 48)
  
  # Subtract offset between UUID time and Unix time.
  # UUID UTC base time is October 15, 1582 (1582-10-15 00:00:00 Z).
  # Unix UTC base time is January  1, 1970 (1970-01-01 00:00:00 Z).
  return ::Time.at(
    (t_utc_100_ns - 0x01B21DD213814000) / 10000000.0 )
end

#uuid_to_uri ⇒ Object Also known as: uuid_to_urn

Returns an URI string (“urn:uuid:”…) for this UUID.



230
231
232
 
# File 'lib/dev-id/device_uuid.rb', line 230

def uuid_to_uri
  uuid ? "urn:uuid:#{self.uuid_str}" : nil
end

#uuid_variant ⇒ Object Also known as: uuid_type

Returns the UUID type (a.k.a. variant).

Possible values:

- 0b000: reserved, NCS backward compatibility (also used for the nil UUID)
- 0b001:   ", mapped to 0b000
- 0b010:   ", mapped to 0b000
- 0b011:   ", mapped to 0b000
- 0b100: the variant specified by RFC 4122
- 0b101:   ", mapped to 0b100
- 0b110: reserved, Microsoft backward compatibility
- 0b111: reserved for future definition



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/dev-id/device_uuid.rb', line 92

def uuid_variant
  #return nil  if ! uuid
  #return uuid.variant
  
  return nil  if ! valid?
  var_raw = raw.getbyte(8) >> 5
  ret = nil
  if (var_raw >> 2) == 0
    ret = 0x000
  elsif (var_raw >> 1) == 2
    ret = 0x100
  else
    ret = var_raw
  end
  return (ret >> 6)
end

#uuid_variant_future? ⇒ Boolean Also known as: uuid_type_future?

Returns:



139
140
141
142
 
# File 'lib/dev-id/device_uuid.rb', line 139

def uuid_variant_future?
  v = uuid_variant
  v ? (v == 0b111) : nil
end

#uuid_variant_microsoft? ⇒ Boolean Also known as: uuid_type_microsoft?

Returns:



133
134
135
136
 
# File 'lib/dev-id/device_uuid.rb', line 133

def uuid_variant_microsoft?
  v = uuid_variant
  v ? (v == 0b110) : nil
end

#uuid_variant_name ⇒ Object Also known as: uuid_type_name 



110
111
112
113
114
115
116
117
118
 
# File 'lib/dev-id/device_uuid.rb', line 110

def uuid_variant_name
  v = uuid_variant
  {
    0b100 => UUID_VARIANT_RFC_4122,
    0b000 => UUID_VARIANT_NCS,
    0b110 => UUID_VARIANT_MICROSOFT,
    0b111 => UUID_VARIANT_FUTURE,
  }[ v ]
end

#uuid_variant_ncs? ⇒ Boolean Also known as: uuid_type_ncs?

Returns:



121
122
123
124
 
# File 'lib/dev-id/device_uuid.rb', line 121

def uuid_variant_ncs?
  v = uuid_variant
  v ? (v == 0b000) : nil
end

#uuid_variant_rfc4122? ⇒ Boolean Also known as: uuid_type_rfc4122?

Returns:



127
128
129
130
 
# File 'lib/dev-id/device_uuid.rb', line 127

def uuid_variant_rfc4122?
  v = uuid_variant
  v ? (v == 0b100) : nil
end

#uuid_version ⇒ Object Also known as: uuid_sub_type

Returns the UUID sub-type (a.k.a. version).

Possible values:

- 1: time-based with unique or random host identifier
- 2: DCE Security version, with embedded POSIX UIDs
- 3: name-based (uses MD5 hash)
- 4: random
- 5: name-based (uses SHA-1 hash)



154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/dev-id/device_uuid.rb', line 154

def uuid_version
  #return nil  if ! uuid
  #return nil  if ! uuid_variant_rfc4122?
  #return uuid.version
  
  return nil  if ! valid?
  return nil  if ! uuid_variant_rfc4122?
  #b6 = self.bytes.to_a[ 6 ]
  b6 = (raw || '').getbyte( 6 )
  return nil  if ! b6
  #b6.div( 16 )  # return value
  b6 >> 4  # return value
end