ffi-hdhomerun 0.2.aa238f1f25e6 → 0.3.100b91730e74

data/README.txt

@@ -1,22 +1,17 @@
-ffi-hdhomerun
-==========
+= ffi-hdhomerun
 http://bitbucket.org/dmlary/ffi-hdhomerun
 
-Description
------------
+== Description
 Ruby-FFI bindings and wrappers for libhdhomerun.
 
-Features
---------
+== Features
 Allows the user to capture video from an HDHomeRun device within Ruby.
 
-What's missing
---------------
+== What's missing
 * Discovery
 * Documentation
 
-Usage
------
+== Usage
   require 'ffi-hdhomerun'
 
   # Allocate a tuner
@@ -36,35 +31,32 @@ Usage
     end
   end
 
-Requirements
-------------
- * libhdhomerun >= 1.0
- * ffi >= 1.0
+== Requirements
+- libhdhomerun >= 1.0
+- ffi >= 1.0
 
-Copyright
----------
+== Copyright
 Copyright (c) 2011, David M. Lary 
 All rights reserved.
 
-License
--------
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-  * Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-  * Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
-  * The name of the author may not be used to endorse or promote products
-    derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
-INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
-THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+== License
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * The name of the author may not be used to endorse or promote products
+      derived from this software without specific prior written permission.
+  
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+  ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/ffi-hdhomerun.rb

@@ -1,8 +1,38 @@
 require 'ffi/hdhomerun'
 
+#
+# Documentation can be found under HDHomeRun::Tuner
+#
 module HDHomeRun
-  VERSION = "0.2"
-
+  VERSION = "0.3"
+
+  # HDHomeRun tuner wrapper.
+  #
+  # Basic usage:
+  #
+  #   # Get a tuner instance for the first tuner on the network.
+  #   tuner = HDHomeRun::Tuner.new(:id => "FFFFFFFF", :tuner => 0)
+  #
+  #   # Set the channel and program
+  #   tuner.channel = 20
+  #   tuner.program = 3
+  #
+  #   # Open a file to write the video stream to
+  #   File.open("capture.ts", "w") do |output|
+  #     puts "Capturing (^C to stop):"
+  #
+  #     # Read the video stream from the tuner
+  #     tuner.capture do |video_data|
+  # 
+  #       # write the video data to the output file
+  #       output.write(video_data)
+  #
+  #       # Display some sort of feedback to show we're capturing.
+  #       STDOUT.write(video_data.size > 0 ? "." : "?")
+  #       STDOUT.flush
+  #     end
+  #   end
+  #   
   class Tuner
     include FFI::HDHomeRun
 
@@ -11,13 +41,22 @@ module HDHomeRun
     # Initialize new hdhomerun tuner
     #
     # Arguments:
-    #   [:id] HDHomeRun id (default: "FFFFFFFF")
-    #   [:tuner] Tuner number (default: "/tuner0")
+    # [:id] HDHomeRun id (default: "FFFFFFFF")
+    # [:tuner] Tuner number (default: "/tuner0")
+    #
+    # Create a tuner instance for the first tuner on any HDHomeRun box
+    # on the network:
+    #   tuner => HDHomeRun::Tuner.new(0)
+    #
+    # Create a tuner instance for the second tuner on the HDHomeRun box
+    # with id FE92EBD0
+    #   tuner = HDHomeRun::Tuner.new(:id => "FE92EBD0", :tuner => 1)
     #
     def initialize(p={})
       p = {:id => p} unless p.is_a? Hash
       p[:id] ||= "FFFFFFFF"
-      p[:tuner] ||= "/tuner0"
+      p[:tuner] ||= 0
+      p[:tuner] = "/tuner%d" % p[:tuner] if p[:tuner].is_a? Fixnum
 
       @hd = create_from_str(p[:id].to_s, nil)
       raise ArgumentError, "Invalid device id: #{id}" if @hd.null?
@@ -35,42 +74,6 @@ module HDHomeRun
         unless get_model_str(@hd)
     end
 
-    def get(key)
-      value = FFI::MemoryPointer.new(:pointer, 1)
-      error = FFI::MemoryPointer.new(:pointer, 1)
-
-      if get_var(@hd, key, value, error) < 0
-        raise RuntimeError, 
-          "communication error sending request to hdhomerun device"
-      end
-      value = value.read_pointer
-      error = error.read_pointer
-
-      raise RuntimeError, error.read_string unless error.null?
-      value.read_string
-    end
-
-    def set(key, value)
-      error = FFI::MemoryPointer.new(:pointer, 1)
-
-      if set_var(@hd, key, value.to_s, nil, error) < 0
-        raise RuntimeError, 
-          "communication error sending request to hdhomerun device"
-      end
-      error = error.read_pointer
-
-      raise RuntimeError, error.read_string unless error.null?
-      true
-    end
-
-    def get_tuner(key)
-      get("%s/%s" % [@tuner, key.to_s])
-    end
-
-    def set_tuner(key, value)
-      set("%s/%s" % [@tuner, key.to_s], value)
-    end
-
     # Dynamically define the following getter and setter methods
     %w{channel channelmap filter program target}.each do |name|
       define_method name do
@@ -89,6 +92,9 @@ module HDHomeRun
       end
     end
 
+    # Get the capture statistics for the tuner.
+    #
+    # Returns: FFI::HDHomeRun::Stats
     def stats
       ptr = FFI::MemoryPointer.new Stats
       out = Stats.new ptr;
@@ -96,6 +102,19 @@ module HDHomeRun
       out
     end
 
+    # Capture video data from the tuner.  
+    #
+    # As data is received from the tuner, that data will be yielded to the
+    # block provided.  If no data has been received from the tuner in over
+    # a second, capture will yield a string of length zero to the block.
+    #
+    # If the block returns [false], the tuner will stop capturing and return.
+    #
+    # Capture from the tuner, but abort if we see no data:
+    #   tuner.capture do |buf|
+    #     break false if buf.empty?
+    #   end
+    #
     def capture(p={}, &block)
       raise ArgumentError, "no block" unless block_given?
       raise RuntimeError, "unable to start stream" \
@@ -127,5 +146,43 @@ module HDHomeRun
         stream_stop(@hd)
       end
     end
+
+    private
+
+    def get(key)
+      value = FFI::MemoryPointer.new(:pointer, 1)
+      error = FFI::MemoryPointer.new(:pointer, 1)
+
+      if get_var(@hd, key, value, error) < 0
+        raise RuntimeError, 
+          "communication error sending request to hdhomerun device"
+      end
+      value = value.read_pointer
+      error = error.read_pointer
+
+      raise RuntimeError, error.read_string unless error.null?
+      value.read_string
+    end
+
+    def set(key, value)
+      error = FFI::MemoryPointer.new(:pointer, 1)
+
+      if set_var(@hd, key, value.to_s, nil, error) < 0
+        raise RuntimeError, 
+          "communication error sending request to hdhomerun device"
+      end
+      error = error.read_pointer
+
+      raise RuntimeError, error.read_string unless error.null?
+      true
+    end
+
+    def get_tuner(key)
+      get("%s/%s" % [@tuner, key.to_s])
+    end
+
+    def set_tuner(key, value)
+      set("%s/%s" % [@tuner, key.to_s], value)
+    end
   end
 end

data/lib/ffi/hdhomerun.rb

@@ -1,6 +1,6 @@
 require 'ffi'
 
-module FFI
+module FFI # :nodoc:
   module HDHomeRun
     extend FFI::Library
     ffi_lib "libhdhomerun.so.1"
@@ -41,6 +41,14 @@ module FFI
                       :hdhomerun_device_get_video_stats, 
                       [:pointer, :pointer], :void
 
+    # HDHomeRun capture statistics for a given tuner
+    #
+    # packets:: Number of packets captured
+    # network_errors:: Number of network errors
+    # transport_errors:: Number of transport errors
+    # sequence_errors:: Number of sequence errors
+    # overflow_errors:: Number of overflow errors
+    #
     class Stats < FFI::Struct
       layout :packets, :uint,
              :network_errors, :uint,

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: ffi-hdhomerun
 version: !ruby/object:Gem::Version
-  version: 0.2.aa238f1f25e6
-  prerelease: 4
+  version: 0.3.100b91730e74
+  prerelease: 7
 platform: ruby
 authors:
 - David M. Lary
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-07 00:00:00.000000000Z
+date: 2011-10-03 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
-  requirement: &18999740 !ruby/object:Gem::Requirement
+  requirement: &12302400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *18999740
+  version_requirements: *12302400
 description: Ruby FFI bindings for libhdhomerun
 email:
 - dmlary@gmail.com