ffi-hdhomerun 0.4 → 0.5

data/lib/ffi-hdhomerun.rb

@@ -5,12 +5,18 @@ require 'pry'
 # Documentation can be found under HDHomeRun::Tuner
 #
 module HDHomeRun
-  VERSION = "0.4"
+  VERSION = "0.5"
   ERROR_STRING_UNKNOWN_VARIABLE = "ERROR: unknown getset variable"
+  ERROR_REGEX_TUNER_LOCKED = /^ERROR: resource locked by /
+  ERROR_STRING_TUNER_LOCK_EXPIRED = "ERROR: lock no longer held"
   MAX_TUNERS = 8
 
+  class InvalidDeviceIdError < Exception; end
   class ConnectionError < Exception; end
+  class InvalidTunerError < Exception; end
   class UnknownVariableError < Exception; end
+  class TunerLockedError < Exception; end
+  class LockExpiredError < Exception; end
 
   #
   # Discover tuners on the network.
@@ -24,7 +30,8 @@ module HDHomeRun
   #   :tuner_count -- number of tuners on the device (int)
   #
   def self.discover
-    results_ptr = FFI::MemoryPointer.new(FFI::HDHomeRun::Device, 64)
+    results_ptr = FFI::MemoryPointer.new(
+                    FFI::HDHomeRun::DiscoverDevice, 64)
     count = FFI::HDHomeRun::discover_find_devices_custom(
               FFI::HDHomeRun::DEVICE_ID_WILDCARD,
               FFI::HDHomeRun::DEVICE_TYPE_TUNER,
@@ -38,7 +45,7 @@ module HDHomeRun
     (0..count-1).map do |i|
 
       # construct our hash
-      p = FFI::HDHomeRun::Device.new(results_ptr[i])
+      p = FFI::HDHomeRun::DiscoverDevice.new(results_ptr[i])
       out = { :id => "%08X" % p.device_id, 
               :type => p.device_type,
               :ip_addr => p.ip_addr }
@@ -74,9 +81,11 @@ module HDHomeRun
       p[:id] = "%08X" % p[:id] if p[:id].is_a? Fixnum
 
       @hd = create_from_str(p[:id].to_s, nil)
-      raise ArgumentError, "Invalid device id: %s" % p[:id] if @hd.null?
+      raise InvalidDeviceIdError, "Invalid device id: %s" % p[:id] \
+        if @hd.null?
+      @hd = FFI::HDHomeRun::Device.new(@hd)
       @id = get_device_id_requested(@hd)
-      raise ArgumentError, "Invalid device id: %08X" % id \
+      raise InvalidDeviceIdError, "Invalid device id: %08X" % @id \
         unless validate_device_id(@id)
       raise ConnectionError, "Unable to connect to device" \
         unless get_model_str(@hd)
@@ -104,7 +113,7 @@ module HDHomeRun
       error = error.read_string
       raise UnknownVariableError, "unknown variable '%s'" % key if
         error == ERROR_STRING_UNKNOWN_VARIABLE
- 
+
       # otherwise, it's a generic runtime error.
       raise RuntimeError, error
     end
@@ -126,9 +135,14 @@ module HDHomeRun
 
       # Throw a useful exception if this get was for an unknown variable.
       error = error.read_string
-      raise UnknownVariableError, "unknown variable '%s'" % key if
-        error == ERROR_STRING_UNKNOWN_VARIABLE
- 
+      raise UnknownVariableError, "unknown variable '%s'" % key \
+        if error == ERROR_STRING_UNKNOWN_VARIABLE
+
+      # Check for locking exceptions
+      raise TunerLockedError, error if error =~ ERROR_REGEX_TUNER_LOCKED
+      raise LockExpiredError, error \
+        if error == ERROR_STRING_TUNER_LOCK_EXPIRED
+
       # otherwise, it's a generic runtime error.
       raise RuntimeError, error
     end
@@ -200,6 +214,7 @@ module HDHomeRun
     # Arguments:
     # [:id] HDHomeRun id (default: "FFFFFFFF")
     # [:tuner] Tuner number (default: "/tuner0")
+    # [:key] lockkey for tuner, see lock (default: nil)
     #
     # Create a tuner instance for the first tuner on any HDHomeRun box
     # on the network:
@@ -213,9 +228,17 @@ module HDHomeRun
       super(p)
       @tuner = p[:tuner] || 0
       @tuner = "/tuner%d" % @tuner if @tuner.is_a? Fixnum
+      self.key = p[:key] if p[:key]
+
+      # Verify the format of the tuner argument
+      raise InvalidTunerError, "invalid tuner: %s" % @tuner \
+        if set_tuner_from_str(@hd, @tuner) <= 0
 
-      if set_tuner_from_str(@hd, @tuner) <= 0
-        raise RuntimeError, "invalid tuner: %s" % @tuner
+      # Final check to see if the tuner exists on our device.
+      begin
+        get_tuner("status")
+      rescue UnknownVariableError => e
+        raise InvalidTunerError, "invalid tuner: %s, %s" % [@tuner, e]
       end
     end
 
@@ -292,6 +315,108 @@ module HDHomeRun
       end
     end
 
+    # Lock the tuner.  Optionally a key can be provided to allow
+    # locking across non-persistent connections.
+    #
+    # [:k:] optional key for non-persistent connections
+    #
+    # Examples:
+    #
+    # Locking with a persistent connection:
+    #
+    #   t = Tuner.new(:id => 0xFEFEFEFE, :tuner => 0)
+    #   t.lock            # => true
+    #   t.channel = 3     # => 3
+    #   # Create a second instance of the tuner and try to change
+    #   # the channel.
+    #   t2 = Tuner.new(:id => 0xFEFEFEFE, :tuner => 0)
+    #   t2.channel = 4    # => TunerLockedError exception
+    #   # first tuner instance releases lock
+    #   t.unlock          # => true
+    #   # Now second tuner can make changes.
+    #   t2.channel = 4    # => 4
+    #
+    # Locking across non-persistent connections:
+    #
+    #   # Grab a tuner and lock it.
+    #   t = Tuner.new(:id => 0xFEFEFEFE, :tuner => 0)
+    #   t.lock 0xFFFF     # => true
+    #   t.channel = 3     # => 3
+    #   t = nil           # => nil
+    #
+    #   # Create a new instance referencing the same tuner, cannot
+    #   # set tuner variables without setting the key first.
+    #   t2 = Tuner.new(:id => 0xFEFEFEFE, :tuner => 0)
+    #   t2.channel = 4    # => TunerLockedError exception
+    #   t2.key = 0xFFFF   # => true
+    #   t2.channel = 4    # => 4
+    #   t2 = nil          # => nil
+    #
+    #   # tuner key can be passed in instansiation arguments.
+    #   t3 = Tuner.new(:id => 0xFEFEFEFE, :tuner => 0, :key => 0xFFFF)
+    #   t3.channel = 5    # => 5
+    #
+    #   # Invalid keys (or expired keys) result in a LockExpiredError
+    #   t3.key = 0x1234   # => true
+    #   t3.channel = 6    # => LockExpiredError exception
+    #   t3 = nil          # => nil
+    #
+    def lock(k = nil)
+      # If no key was provided, generate a random key for this
+      # session.
+      k ||= rand(0xFFFFFFFF)
+      set_tuner("lockkey", k)
+      self.key = k
+      true
+    end
+
+    # Unlock the tuner.  Requires you to already have the correct
+    # key set or use the [:force:] argument.
+    #
+    # Example:
+    #   t = Tuner.new(:id => 0xFEFEFEFE, :tuner => 0)
+    #   t2 = Tuner.new(:id => 0xFEFEFEFE, :tuner => 0)
+    #
+    #   # Lock the tuner and try to unlock it without the key
+    #   t.lock            # => true
+    #   t2.unlock         # => TunerLockedError exception
+    #   t.locked?         # => true
+    #
+    #   # force the tuner to unlock
+    #   t2.unlock :force  # => true
+    #   t.locked?         # => false
+    #
+    def unlock(force=false)
+      # FIXME uncommenting the following line causes the tests to core
+      # dump.
+      # return true unless locked?
+      set_tuner("lockkey", force != false ? "force" : "none")
+      self.key = 0
+
+      # Strange behavior here, setting the lockkey to "none" without
+      # the correct lockkey does not generate an error.  Instead the
+      # new value is ignored by the tuner.  So we have to check here
+      # to see if the tuner is still locked here to tell if our unlock
+      # was successful.
+      raise TunerLockedError if locked?
+      true
+    end
+
+    # Specify the key to use when communicating with this tuner.
+    def key=(key)
+      lockkey_use_value(@hd, key.to_i)
+    end
+
+    # check to see if the tuner is locked
+    def locked?
+      get_tuner("lockkey") != "none"
+    end
+
+    # Return the ip address that holds the lock on the tuner
+    def lock_owner
+      get_tuner("lockkey")
+    end
+
     def to_s
       "<%s:0x%08x @id=%08X, @tuner=%s>" % 
         [ self.class, object_id, @id, @tuner ]

data/lib/ffi/hdhomerun.rb

@@ -47,6 +47,9 @@ module FFI # :nodoc:
                       :hdhomerun_discover_find_devices_custom,
                       [ :uint32, :uint32, :uint32, :pointer, :int ],
                       :int
+    attach_function :lockkey_use_value,
+                      :hdhomerun_device_tuner_lockkey_use_value,
+                      [:pointer, :ulong], :void
 
     # HDHomeRun capture statistics for a given tuner
     #
@@ -71,6 +74,25 @@ module FFI # :nodoc:
       end
     end
 
+    class Device < FFI::Struct
+      layout :cs, :pointer,
+             :vs, :pointer,
+             :dbg, :pointer,
+             :scan, :pointer,
+             :multicast_ip, :uint32,
+             :multicast_port, :uint16,
+             :device_id, :uint,
+             :lockkey, :uint32,
+             :name, [:char, 32],
+             :model, [:char, 32]
+
+      members.each do |name|
+        define_method name.to_s do
+          send(:[], name.to_sym)
+        end
+      end
+    end
+
     # Discover device structure
     #
     # Silicon dust changed this structure at some point between
@@ -82,7 +104,7 @@ module FFI # :nodoc:
     # FFI_HDHOMERUN_OLD_DEVICE_STRUCT environment variable has been
     # set.
     #
-    class Device < FFI::Struct
+    class DiscoverDevice < FFI::Struct
       if ENV['FFI_HDHOMERUN_OLD_DEVICE_STRUCT']
         layout :ip_addr, :uint32,
                :device_type, :uint32,

data/spec/hdhomerun_spec.rb

@@ -19,7 +19,7 @@ describe HDHomeRun::Device do
 
   it "throws exception on invalid name" do
     lambda { HDHomeRun::Device.new("WOOF WOOF, I'm a puppy!") } \
-      .should raise_error(ArgumentError)
+      .should raise_error(HDHomeRun::InvalidDeviceIdError)
   end
 
   it "throws exception on unreachable device" do
@@ -74,6 +74,13 @@ describe HDHomeRun::Tuner do
          "to a channel that comes in clearly on your tuner" unless @channel
   end
 
+  it "throws exception for invalid tuners" do
+    lambda { HDHomeRun::Tuner.new(:tuner => "woof") } \
+      .should raise_error(HDHomeRun::InvalidTunerError)
+    lambda { HDHomeRun::Tuner.new(:tuner => 9999) } \
+      .should raise_error(HDHomeRun::InvalidTunerError)
+  end
+
   it "can set and get the channel" do
     @tuner.channel = "none"
     @tuner.channel.should eq("none")
@@ -100,5 +107,78 @@ describe HDHomeRun::Tuner do
 
     bytes.size.should be > 0
   end
+
+  it "can be locked non-persistently" do
+    tuner2 = HDHomeRun::Tuner.new(:id => @tuner.id, :tuner => @tuner.tuner)
+    @tuner.lock.should be true
+    @tuner.channel = 33
+
+    lambda { tuner2.channel = 3 } \
+      .should raise_error(HDHomeRun::TunerLockedError)
+
+    @tuner.unlock
+  end
+
+  it "can be locked persistently" do
+    t = HDHomeRun::Tuner.new(:id => @tuner.id, :tuner => @tuner.tuner)
+    t.lock(0xFACE).should be true
+    t.key = 0xFACE
+    t.channel = 11
+
+    lambda { @tuner.channel = 3 } \
+      .should raise_error(HDHomeRun::TunerLockedError)
+
+    t = nil
+    t = HDHomeRun::Tuner.new(:id => @tuner.id, :tuner => @tuner.tuner)
+    t.key = 0xFACE
+
+    t.channel = 7
+
+    lambda { @tuner.channel = 3 } \
+      .should raise_error(HDHomeRun::TunerLockedError)
+
+    t.unlock
+
+    @tuner.channel = 3
+  end
+
+  it "cannot be double locked" do
+    t = HDHomeRun::Tuner.new(:id => @tuner.id, :tuner => @tuner.tuner)
+    @tuner.lock
+    lambda { t.lock(0x3333) } \
+      .should raise_error(HDHomeRun::TunerLockedError)
+    @tuner.unlock
+  end
+
+  it "rejects invalid keys" do
+    @tuner.unlock(:force)
+    @tuner.key = 0xFEEDFACE
+    lambda { @tuner.channel = 3 } \
+      .should raise_error(HDHomeRun::LockExpiredError)
+  end
+
+  it "can check to see if the tuner is locked" do
+    @tuner.locked?.should be false
+    t = HDHomeRun::Tuner.new(:id => @tuner.id, :tuner => @tuner.tuner)
+    t.lock
+    @tuner.locked?.should be true
+    t.unlock
+  end
+
+  it "cannot unlock without the correct key" do
+    t = HDHomeRun::Tuner.new(:id => @tuner.id, :tuner => @tuner.tuner)
+    @tuner.lock
+    lambda { t.unlock } \
+      .should raise_error(HDHomeRun::TunerLockedError)
+    @tuner.locked?.should be true
+    @tuner.unlock
+  end
+
+  it "can force a tuner to unlock" do
+    t = HDHomeRun::Tuner.new(:id => @tuner.id, :tuner => @tuner.tuner)
+    @tuner.lock
+    t.unlock(:force)
+    @tuner.locked?.should be false
+  end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ffi-hdhomerun
 version: !ruby/object:Gem::Version
-  version: '0.4'
+  version: '0.5'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-07 00:00:00.000000000 Z
+date: 2012-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi