device-identifier 0.0.1 → 0.0.2

data/README.md

@@ -7,11 +7,47 @@ Rationale:
 - Hard-phones have an Ethernet MAC address.
 - Soft-phones don't. They have/need some sort of identification string
   (any sequence of bytes).
-- Both are device identifiers, with the MAC address being a sub-class.
+- Soft-phones may use UUIDs as identifiers.
+- All of them are device identifiers, with the MAC address resp. UUID being sub-classes.
 
 Author: Philipp Kempgen, [http://kempgen.net](http://kempgen.net)
 
 
+## Usage
+
+	require 'dev-id'
+	
+	m = DevId::MacAddress.from_hex ""
+	m.valid?       # => false
+	
+	m = DevId::MacAddress.from_hex "001122aabbcc"
+	m.valid?       # => true
+	
+	m = DevId::MacAddress.from_hex "00:11:22:aa:bb:cc"
+	m.valid?       # => true
+	
+	m = DevId::MacAddress.from_hex "00-11-22-AA-BB-CC"
+	m.valid?       # => true
+	m.ascii        # => "001122aabbcc"
+	m.pretty       # => "00:11:22:AA:BB:CC"
+	m.to_s         # => "00:11:22:AA:BB:CC"
+	m.pretty({ :sep => '-', :upcase => false })
+                   # => "00-11-22-aa-bb-cc"
+	m.raw          # => "\x00\x11\x22\xAA\xBB\xCC"
+	m.bytes.to_a   # => [0, 17, 34, 170, 187, 204]
+	m.bytesize     # => 6
+	m.to_int       # => 73596058572
+	m.starts_with? DevId::MacAddressOui.from_hex '00:11:22'
+	               # => true
+	m.starts_with? DevId::MacAddressPartial.from_hex '00:11:22:aa'
+	               # => true
+	
+	# MacAddress specific:
+	m.null?        # => false
+	m.multicast?   # => false
+	m.oui_raw      # => "\x00\x11\x22"
+
+
 ## Inheritance
 
 The class inheritance is as follows:
@@ -31,6 +67,10 @@ The class inheritance is as follows:
 			- **`MacAddress`**
 				
 				Model for a MAC address.
+			
+			- **`DeviceUuid`**
+				
+				Model for a device identifier UUID.
 		
 		- **`MacAddressPartial`**
 			
@@ -43,9 +83,9 @@ The class inheritance is as follows:
 
 ## Device identifiers
 
-There are 2 kinds of device identifiers: the generic `DeviceIdentifier` and the more specific `MacAddress`.
+There are 3 kinds of device identifiers: the generic `DeviceIdentifier`, and the more specific `MacAddress` and `DeviceUuid`.
 
-Both support the methods in following (amongst others):
+All of them support the methods in following (amongst others):
 
 - `bytes`
 	
@@ -101,6 +141,15 @@ Instance methods:
 	
 	The number of bytes.
 
+- `getbyte( index )`
+	
+	Returns one of the raw bytes as an integer.
+
+- `byteslice( from, len = nil )`
+	
+	Returns a slice (sub-string) of the raw bytes.
+	`from` can be an `Integer` or a `Range` – in the latter case `len` must not be specified.
+
 - `length`
 	
 	Alias for `bytesize`.
@@ -161,7 +210,7 @@ Instance methods:
 
 - `null?`
 	
-	If it's a null address (all 6 bytes \x00: 00:00:00:00:00:00).
+	If it's a null address (all 6 bytes `\x00`: `00:00:00:00:00:00`).
 
 - `pretty( opts = nil )`
 
@@ -181,6 +230,38 @@ Instance methods:
 	The OUI (vendor) part (first 3 bytes) in raw format.
 
 
+### `DeviceUuid`
+
+**Inheritance**:
+`Base` >
+`BinaryAddress` >
+`DeviceIdentifier` >
+`DeviceUuid`
+
+Model for a device UUID.
+
+Instance methods:
+
+- `null?`
+	
+	If it's a null address (all bytes `\x00`: `00000000-0000-0000-0000-000000000000`).
+
+- `pretty( opts = nil )`
+
+	A pretty ASCII representation (hex format).
+	
+	Default options are:
+		
+		{
+			:sep     => '-',    # separator, typically "-"
+			:upcase  => false,  # use uppercase?
+		}
+	
+	If the default options are used this method returns the canonical UUID representation.
+
+- A couple of UUID specific methods (named `uuid`...).
+
+
 ### `MacAddressPartial`
 
 **Inheritance**:
@@ -203,4 +284,3 @@ Model for the OUI (vendor) part of a MAC address.
 
 Validates that the raw address has a length of 3 bytes.
 
-

data/lib/dev-id.rb

@@ -6,4 +6,5 @@ require 'dev-id/base'
 require 'dev-id/binary_address'
 require 'dev-id/device_identifier'
 require 'dev-id/mac_address'
+require 'dev-id/device_uuid'
 

data/lib/dev-id/base.rb

@@ -1,5 +1,21 @@
-require 'dev-id'
-require 'active_model'
+#require 'dev-id'  # for DevId
+require 'active_model'  # for ActiveModel (from the "activemodel" gem)
+#if ! ::ActiveModel.const_defined?( :MassAssignmentSecurity )
+#	# ActiveModel::MassAssignmentSecurity is no longer part of the
+#	# "activemodel" gem as of version 4, but went into the
+#	# "protected_attributes" gem.
+#	begin
+#		require 'protected_attributes'
+#	rescue ::LoadError => e
+#		STDERR.puts "------------------------------------------------------------"
+#		STDERR.puts "#{e.message} (#{e.class.name})"
+#		STDERR.puts (e.backtrace || []).reject{|l| l.match( %r{ /lib/rake/ }x )}.map{|l| "  #{l}"}
+#		STDERR.puts "------------------------------------------------------------"
+#		STDERR.puts "For ActiveModel >= 4 please add the \"protected_attributes\" gem to your bundle."
+#		STDERR.puts "  ActiveModel version: #{::ActiveModel::VERSION::STRING}"
+#		STDERR.puts "------------------------------------------------------------"
+#	end
+#end
 
 module ::DevId
 	
@@ -7,7 +23,13 @@ module ::DevId
 	class BasicActiveModel
 		extend  ::ActiveModel::Naming
 		include ::ActiveModel::Validations
-		include ::ActiveModel::MassAssignmentSecurity
+		
+		if ::ActiveModel::VERSION::MAJOR <= 3
+			include ::ActiveModel::MassAssignmentSecurity
+		else
+			include ::ActiveModel::ForbiddenAttributesProtection
+		end
+		
 		include ::ActiveModel::Conversion
 	#	extend  ::ActiveModel::Callbacks
 		
@@ -24,7 +46,11 @@ module ::DevId
 			attributes = new_attributes.stringify_keys
 			
 			unless options[:without_protection]
-				attributes = sanitize_for_mass_assignment( attributes, options[:as] || :default )
+				if ::ActiveModel::VERSION::MAJOR <= 3
+					attributes = sanitize_for_mass_assignment( attributes, options[:as] || :default )
+				else
+					attributes = sanitize_for_mass_assignment( attributes )
+				end
 			end
 			
 			attributes.each { |k, v|

data/lib/dev-id/binary_address.rb

@@ -36,6 +36,20 @@ module ::DevId
 		end
 		alias :length :bytesize
 		
+		def byteslice( from, len=nil )
+			return nil  if ! raw
+			if len
+				raw.byteslice( from, len )
+			else
+				raw.byteslice( from )  # from can be a Fixnum or a Range
+			end
+		end
+		alias :'[]' :'byteslice'
+		
+		def getbyte( idx )
+			(raw || '').getbyte( idx )
+		end
+		
 		# Construct a new instance from a raw string.
 		#
 		def self.from_raw( str )
@@ -129,8 +143,6 @@ module ::DevId
 			return ! (self =~ other)
 		end
 		
-		#TODO getbyte, [], byteslice
-		
 	end
 end
 

data/lib/dev-id/device_uuid.rb

@@ -0,0 +1,237 @@
+require 'dev-id/device_identifier'
+require 'dev-id/binary_address'
+require 'dev-id/mac_address'
+
+module ::DevId
+	
+	# Model for a device UUID.
+	#
+	# 16 bytes.
+	#
+	class DeviceUuid < DeviceIdentifier
+		
+		validates_length_of :raw, :is => 16
+		
+		# Default options for conversion to ASCII in the `pretty`
+		# method.
+		DEFAULT_TO_PRETTY_OPTS = {
+			:sep => '-',  # typically "-"
+			:upcase => false,
+		}.freeze
+		
+		UUID_VARIANT_NCS        = :ncs         # 0b0xx, reserved, NCS backward compatibility (also used for the nil UUID)
+		UUID_VARIANT_RFC_4122   = :rfc4122     # 0b10x, the variant specified by RFC 4122
+		UUID_VARIANT_MICROSOFT  = :microsoft   # 0b110, reserved, Microsoft backward compatibility
+		UUID_VARIANT_FUTURE     = :future      # 0b111, reserved for future definition
+		
+		# Whether the device UUID is the "nil"/"null" address (16
+		# NULL bytes).
+		#
+		def null?
+			return nil  if ! valid?
+			return raw == (?\0.force_encoding( ::Encoding::ASCII_8BIT ) * 16)
+		end
+		
+		# Pretty ASCII representation in UUID format (8-4-4-4-12).
+		#
+		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
+		
+		# 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.
+		#
+		def uuid_str
+			return nil  if ! valid?
+			return raw.unpack( 'H8H4H4H4H12' ).join( '-' )
+		end
+		
+		# `to_s` is an alias for `pretty`.
+		#
+		def to_s( opts = nil )
+			pretty( opts )
+		end
+		
+		def require_uuid_tools
+			require 'uuidtools'  unless ::Module.const_defined?( :UUIDTools )
+		end
+		private :require_uuid_tools
+		
+		def uuid
+			if @uuid == nil
+				if ! valid?
+					@uuid = false
+				else
+					require_uuid_tools()
+					@uuid = ::UUIDTools::UUID.parse_raw( raw )
+				end
+			end
+			@uuid
+		end
+		
+		# 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
+		#
+		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
+		alias :uuid_type :uuid_variant
+		
+		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
+		alias :uuid_type_name :uuid_variant_name
+		
+		def uuid_variant_ncs?
+			v = uuid_variant
+			v ? (v == 0b000) : nil
+		end
+		alias :'uuid_type_ncs?' :'uuid_variant_ncs?'
+		
+		def uuid_variant_rfc4122?
+			v = uuid_variant
+			v ? (v == 0b100) : nil
+		end
+		alias :'uuid_type_rfc4122?' :'uuid_variant_rfc4122?'
+		
+		def uuid_variant_microsoft?
+			v = uuid_variant
+			v ? (v == 0b110) : nil
+		end
+		alias :'uuid_type_microsoft?' :'uuid_variant_microsoft?'
+		
+		def uuid_variant_future?
+			v = uuid_variant
+			v ? (v == 0b111) : nil
+		end
+		alias :'uuid_type_future?' :'uuid_variant_future?'
+		
+		# 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)
+		#
+		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
+		alias :uuid_sub_type :uuid_version
+		
+		# 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.
+		#
+		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
+		
+		# 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.
+		#
+		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
+		
+		# This method applies only to version 1 UUIDs. Returns the
+		# timestamp used to generate this UUID.
+		#
+		# @return  `Time` instance   timestamp
+		#
+		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
+		
+		# Returns an URI string ("`urn:uuid:`"...) for this UUID.
+		#
+		def uuid_to_uri
+			uuid ? "urn:uuid:#{self.uuid_str}" : nil
+		end
+		alias :uuid_to_urn :uuid_to_uri
+		
+	end
+end
+

data/lib/dev-id/mac_address.rb

@@ -18,13 +18,21 @@ module ::DevId
 			:upcase => true,
 		}.freeze
 		
-		# Whether the MAC address is a multicast address.
+		# Whether the MAC address is a group address (multicast address).
 		#
 		def multicast?
 			return nil  if ! valid?
 			return (raw.getbyte(0).to_i % 2) != 0
 		end
 		
+		# Whether the MAC address is a local address (as compared to a global address).
+		#
+		def local?
+			return nil  if ! valid?
+			#return raw.getbyte(0).to_s(2).rjust(8,'0')[-2] == '1'
+			return ((raw.getbyte(0).to_i >> 1) % 2) != 0
+		end
+		
 		# Whether the MAC address is the "null" address (6 NULL
 		# bytes).
 		#

data/lib/dev-id/version.rb

@@ -4,7 +4,7 @@
 module ::DevId
 	
 	# The version of this Gem.
-	VERSION = [ 0, 0, 1 ].freeze
+	VERSION = [ 0, 0, 2 ].freeze
 	
 	# The version of this Gem as a string.
 	VERSION_STR = VERSION.map(& :to_s).join('.').freeze

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: device-identifier
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,16 +9,70 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-17 00:00:00.000000000 Z
+date: 2013-11-27 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: uuidtools
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.4
 - !ruby/object:Gem::Dependency
   name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - <
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - <
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: uuidtools
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: 2.1.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +80,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: 2.1.4
 description: Models for device identifiers, e.g. MAC addresses for hardware clients
   and arbitrary identifier strings for software clients.
 email: 
@@ -37,6 +91,7 @@ files:
 - lib/dev-id/base.rb
 - lib/dev-id/binary_address.rb
 - lib/dev-id/device_identifier.rb
+- lib/dev-id/device_uuid.rb
 - lib/dev-id/mac_address.rb
 - lib/dev-id/version.rb
 - lib/dev-id.rb