ffi-coremidi 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89758a3263039237eb24cae058898e594f1fd858
-  data.tar.gz: a57e14a01b6cc31687995806ee0032fd7d957498
+  metadata.gz: 4c86ac17739ef22c4478c0b6074602c35e6797d7
+  data.tar.gz: 612c5638da885ab668b64952087d52d49112fbdc
 SHA512:
-  metadata.gz: b55637a189a1c6cabc55ecf13503c5bc3562de7159b6ee9ebfd3250530d628fb66bd052ae9b026b98bf1e50e3d50397c66b60b1fff9c533b2639fcbd766ceeab
-  data.tar.gz: d7e2e91d8a2a1e98819d173f45b8795626d64109ecfb99108ecc1a86b39550084bb6c696e87b2b95acdb83ef838701fc667f1294fe1161083b91bb8a6cefc774
+  metadata.gz: dad0821c9b3019da6993960a098d0275a79d009535e09a8e63509908542c3a29b888cfc739cf06b2933e775f8575150c0092d63af9400812c7c0c46dc7db07b0
+  data.tar.gz: 379c75695cea32e8f7ff3347bc6556eb1ead7301781d0ad845261ccf9630b00d39bf006dc5f4294a3193ebdb6a334cb5f0e27fe93c2636864a5a48d277250c9b

data/README.md

@@ -4,15 +4,15 @@
 
 This is a Ruby implementation of the [Apple Core MIDI framework API](https://developer.apple.com/library/mac/#documentation/MusicAudio/Reference/CACoreMIDIRef/MIDIServices/).
 
-Note that in the interest of allowing people on other platforms to utilize your code, please consider using [UniMIDI](http://github.com/arirusso/unimidi).  UniMIDI is a platform independent wrapper which implements this library with a similar API.
+Note that in the interest of allowing people on other platforms to utilize your code, please consider using [UniMIDI](http://github.com/arirusso/unimidi).  UniMIDI is a platform independent wrapper which implements this library and has a similar API.
 
 ### Features
 
-* Simpler API than Core MIDI
+* Simplified API
 * Input and output on multiple devices concurrently
-* Agnostically handle different MIDI Message types (including SysEx)
+* Generalized handling of different MIDI Message types (including SysEx)
 * Timestamped input events
-* Internally patch MIDI to other programs using IAC 
+* Patch MIDI via software to other programs using IAC 
 
 ### Requirements
 

data/lib/coremidi.rb

@@ -18,5 +18,5 @@ require "coremidi/source"
 require "coremidi/destination"
 
 module CoreMIDI
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/lib/coremidi/destination.rb

@@ -8,74 +8,85 @@ module CoreMIDI
     attr_reader :entity
 
     # Close this output
+    # @return [Boolean]
     def close
-      @enabled = false
+      if @enabled
+        @enabled = false
+        true
+      else
+        false
+      end
     end
 
     # Send a MIDI message comprised of a String of hex digits
+    # @param [String] data A string of hex digits eg "904040"
+    # @return [Boolean]
     def puts_s(data)
       data = data.dup
-	    output = []
+	    bytes = []
       until (str = data.slice!(0,2)).eql?("")
-      	output << str.hex
+      	bytes << str.hex
       end
-
-      puts_bytes(*output)
+      puts_bytes(*bytes)
+      true
     end
     alias_method :puts_bytestr, :puts_s
     alias_method :puts_hex, :puts_s
 
-    # Send a MIDI messages comprised of Numeric bytes
+    # Send a MIDI message comprised of numeric bytes
+    # @param [*Fixnum] data Numeric bytes eg 0x90, 0x40, 0x40
+    # @return [Boolean]
     def puts_bytes(*data)
-
-      format = "C" * data.size
-      bytes = (FFI::MemoryPointer.new FFI.type_size(:char) * data.size)
-      bytes.write_string(data.pack(format))
-
-      if data.first.eql?(0xF0) && data.last.eql?(0xF7)
-        puts_sysex(bytes, data.size)
-      else
-        puts_small(bytes, data.size)
-      end
+      type = sysex?(data) ? :sysex : :small
+      bytes = pack_data(data)
+      send("puts_#{type.to_s}", bytes, data.size)
+      true
     end
 
-    # Send a MIDI message of an indeterminant type
-    def puts(*a)
-  	  case a.first
-        when Array then puts_bytes(*a.first)
-    	when Numeric then puts_bytes(*a)
-    	when String then puts_bytestr(*a)
+    # Send a MIDI message of indeterminate type
+    # @param [*Array<Fixnum>, *Array<String>, *Fixnum, *String] args
+    # @return [Boolean]
+    def puts(*args)
+  	  case args.first
+      when Array then puts_bytes(*args.first)
+    	when Fixnum then puts_bytes(*args)
+    	when String then puts_bytestr(*args)
       end
     end
     alias_method :write, :puts
 
     # Enable this device
+    # @return [Destination]
     def enable(options = {}, &block)
-      @enabled = true
-      if block_given?
-      	begin
-      		yield(self)
-      	ensure
-      		close
-      	end
-      else
-        self
+      if !@enabled
+        @enabled = true
+        if block_given?
+      	  begin
+      		  yield(self)
+      	  ensure
+      		  close
+      	  end
+        end
       end
+      self
     end
     alias_method :open, :enable
     alias_method :start, :enable
 
     # Shortcut to the first output endpoint available
+    # @return [Destination]
     def self.first
       Endpoint.first(:destination)
     end
     
     # Shortcut to the last output endpoint available
+    # @return [Destination]
     def self.last
       Endpoint.last(:destination)
     end
 
     # All output endpoints
+    # @return [Array<Destination>]
     def self.all
       Endpoint.all_by_type[:destination]
     end
@@ -84,6 +95,7 @@ module CoreMIDI
 
     # Base initialization for this endpoint -- done whether or not the endpoint is enabled to
     # check whether it is truly available for use
+    # @return [Boolean]
     def connect
       client_error = enable_client
       port_error = initialize_port
@@ -105,6 +117,7 @@ module CoreMIDI
         packet_ptr = Map.MIDIPacketListAdd(packet_list, 256, packet_ptr, 0, 0, size, bytes)
       end
       Map.MIDISend( @handle, @resource, packet_list )
+      true
     end
 
     # Output a System Exclusive MIDI message
@@ -117,6 +130,7 @@ module CoreMIDI
       request[:completion_proc] = SysexCompletionCallback
       request[:completion_ref_con] = request
       Map.MIDISendSysex(request)
+      true
     end
 
     SysexCompletionCallback =
@@ -133,6 +147,21 @@ module CoreMIDI
       error
     end
 
+    # Pack the given data into a coremidi MIDI packet
+    def pack_data(data)
+      format = "C" * data.size
+      packed_data = data.pack(format)
+      char_size = FFI.type_size(:char) * data.size
+      bytes = FFI::MemoryPointer.new(char_size)
+      bytes.write_string(packed_data)
+      bytes
+    end
+
+    # Is the given data a MIDI sysex message?
+    def sysex?(data)
+      data.first.eql?(0xF0) && data.last.eql?(0xF7)
+    end
+
   end
 
 end

data/lib/coremidi/device.rb

@@ -6,21 +6,24 @@ module CoreMIDI
                 :id, # Unique Numeric id
                 :name # Device name from coremidi
 
+    # @param [Fixnum] id The ID for the device
+    # @param [Object] device_pointer The underlying device pointer
+    # @param [Hash] options
+    # @option options [Boolean] :include_offline Whether to include offline entities (default: false)
     def initialize(id, device_pointer, options = {})
-      include_if_offline = options.fetch(:include_offline, false)
       @id = id
       @resource = device_pointer
       @entities = []
-      populate_name
-      populate_entities(:include_offline => include_if_offline)
+      populate(options)
     end
             
     # Endpoints for this device
     # @return [Array<Endpoint>]
     def endpoints
       endpoints = { :source => [], :destination => [] }
-      endpoints.keys.each do |k|
-        endpoints[k] += entities.map { |entity| entity.endpoints[k] }.flatten
+      endpoints.keys.each do |key|
+        endpoint_group = entities.map { |entity| entity.endpoints[key] }.flatten
+        endpoints[key] += endpoint_group
       end
       endpoints
     end
@@ -29,9 +32,9 @@ module CoreMIDI
     # @param [Integer] last_id The highest already used endpoint ID 
     # @return [Integer] The highest used endpoint ID after populating this device's endpoints
     def populate_endpoint_ids(last_id)
-      i = 0
-      entities.each { |entity| i += entity.populate_endpoint_ids(i + last_id) }
-      i
+      id = 0
+      entities.each { |entity| id += entity.populate_endpoint_ids(id + last_id) }
+      id
     end
 
     # All cached devices
@@ -42,13 +45,13 @@ module CoreMIDI
     def self.all(options = {})
       use_cache = options[:cache] || true
       include_offline = options[:include_offline] || false
-      if @devices.nil? || @devices.empty? || !use_cache
+      if !populated? || !use_cache
         @devices = []
-        i = 0
-        while !(device_pointer = Map.MIDIGetDevice(i)).null?
-          device = new(i, device_pointer, :include_offline => include_offline)
+        counter = 0
+        while !(device_pointer = Map.MIDIGetDevice(counter)).null?
+          device = new(counter, device_pointer, :include_offline => include_offline)
           @devices << device
-          i+=1
+          counter += 1
         end
         populate_endpoint_ids
       end
@@ -62,34 +65,30 @@ module CoreMIDI
       @devices
     end
 
+    # Has the device list been populated?
+    def self.populated?
+      !@devices.nil? && !@devices.empty? 
+    end
+
     private
 
     # Populate the device name
     def populate_name
-      prop = Map::CF.CFStringCreateWithCString( nil, "name", 0 )
-
-      begin
-        name_ptr = FFI::MemoryPointer.new(:pointer)
-        Map::MIDIObjectGetStringProperty(@resource, prop, name_ptr)
-        name = name_ptr.read_pointer
-        len = Map::CF.CFStringGetMaximumSizeForEncoding(Map::CF.CFStringGetLength(name), :kCFStringEncodingUTF8)
-        bytes = FFI::MemoryPointer.new(len + 1)
-        raise RuntimeError.new("CFStringGetCString") unless Map::CF.CFStringGetCString(name, bytes, len, :kCFStringEncodingUTF8)
-        @name = bytes.read_string
-      ensure
-        Map::CF.CFRelease(name) unless name.nil? || name.null?
-        Map::CF.CFRelease(prop) unless prop.null?
-      end
+      @name = Map.get_string(@resource, "name")
+      raise RuntimeError.new("Can't get device name") unless @name
     end
     
     # All of the endpoints for all devices a consecutive local id
     def self.populate_endpoint_ids
-      i = 0
-      all.each { |device| i += device.populate_endpoint_ids(i) }
+      counter = 0
+      all.each { |device| counter += device.populate_endpoint_ids(counter) }
+      counter
     end
 
     # Populates the entities for this device. These entities are in turn used to gather the endpoints.
-    #
+    # @param [Hash] options
+    # @option options [Boolean] :include_offline Whether to include offline entities (default: false)
+    # @return [Fixnum] The number of entities populated
     def populate_entities(options = {})
       include_if_offline = options[:include_offline] || false
       i = 0
@@ -97,6 +96,13 @@ module CoreMIDI
         @entities << Entity.new(entity_pointer, :include_offline => include_if_offline)
         i += 1
       end
+      i
+    end
+
+    # Populate the instance
+    def populate(options = {})
+      populate_name
+      populate_entities(:include_offline => options[:include_offline])
     end
 
   end

data/lib/coremidi/endpoint.rb

@@ -22,26 +22,32 @@ module CoreMIDI
     end
     
     # Is this endpoint online?
+    # @return [Boolean]
     def online?
       @entity.online? && connect?
     end
     
-    # Set the id for this endpoint (the id is immutable once its set)
-    def id=(val)
-      @id ||= val
+    # Set the id for this endpoint (the id is immutable)
+    # @param [Fixnum] val
+    # @return [Fixnum]
+    def id=(id)
+      @id ||= id
     end
 
     # Select the first endpoint of the specified type
+    # @return [Destination, Source]
     def self.first(type)
       all_by_type[type].first
     end
 
     # Select the last endpoint of the specified type
+    # @return [Destination, Source]
     def self.last(type)
       all_by_type[type].last
     end
 
     # A Hash of :source and :destination endpoints
+    # @return [Hash]
     def self.all_by_type
       {
         :source => Device.all.map { |d| d.endpoints[:source] }.flatten,
@@ -50,15 +56,26 @@ module CoreMIDI
     end
 
     # All endpoints of both types
+    # @return [Array<Destination, Source>]
     def self.all
-      Device.all.map { |d| d.endpoints }.flatten
+      Device.all.map(&:endpoints).flatten
+    end
+
+    # Get the class for the given endpoint type name
+    # @param [Symbol] type The endpoint type eg :source, :destination
+    # @return [Class] eg Source, Destination
+    def self.get_class(type)
+      case type
+      when :source then Source
+      when :destination then Destination
+      end  
     end
     
     protected
     
     # Enables the coremidi MIDI client that will go with this endpoint
     def enable_client
-      client_name = Map::CF.CFStringCreateWithCString( nil, "Client #{@resource_id} #{name}", 0 )
+      client_name = Map::CF.CFStringCreateWithCString(nil, "Client #{@resource_id} #{name}", 0)
       client_ptr = FFI::MemoryPointer.new(:pointer)
       error = Map.MIDIClientCreate(client_name, nil, nil, client_ptr)
       @client = client_ptr.read_pointer

data/lib/coremidi/entity.rb

@@ -9,46 +9,68 @@ module CoreMIDI
                 :name,
                 :resource
                 
-    alias_method :online?, :is_online
-
+    # @param [FFI::Pointer] resource A pointer to the underlying entity
+    # @param [Hash] options
     def initialize(resource, options = {}, &block)
-      @endpoints = { :source => [], :destination => [] }
+      @endpoints = { 
+        :source => [], 
+        :destination => [] 
+      }
       @resource = resource
-      @manufacturer = get_property(:manufacturer)
-      @model = get_property(:model)
-      @name = "#{@manufacturer} #{@model}"
-      @is_online = get_property(:offline, :type => :int) == 0
-      @endpoints.keys.each { |type| populate_endpoints(type) }
+      populate
     end
     
     # Assign all of this Entity's endpoints an consecutive local id
+    # @param [Fixnum] starting_id
+    # @return [Fixnum]
     def populate_endpoint_ids(starting_id)
-      i = 0
-      @endpoints.values.flatten.each do |e|  
-        e.id = (i + starting_id)
-        i += 1
+      counter = 0
+      @endpoints.values.flatten.each do |endpoint|  
+        endpoint.id = counter + starting_id
+        counter += 1
       end
-      i
+      counter
     end
     
+    # Is the entity online?
+    # @return [Boolean]
+    def online?
+      get_property(:offline, :type => :int) == 0
+    end
+
     private
+
+    # Construct a display name for the entity
+    # @return [String]
+    def get_name
+      "#{@manufacturer} #{@model}"
+    end
     
     # Populate endpoints of a specified type for this entity
-    def populate_endpoints(type, options = {})
-      include_if_offline = options[:include_offline] || false
-      endpoint_class = case type
-        when :source then Source
-        when :destination then Destination
-      end  
+    # @param [Symbol] type The endpoint type eg :source, :destination
+    # @param [Hash] options
+    # @option options [Boolean] :include_offline Include offline endpoints in the list
+    # @return [Fixnum]
+    def populate_endpoints_by_type(type, options = {})
+      endpoint_class = Endpoint.get_class(type)
       num_endpoints = number_of_endpoints(type)
       (0..num_endpoints).each do |i|
-        ep = endpoint_class.new(i, self)
-        @endpoints[type] << ep if ep.online? || include_if_offline
+        endpoint = endpoint_class.new(i, self)
+        if endpoint.online? || options[:include_offline]
+          @endpoints[type] << endpoint
+        end
       end  
       @endpoints[type].size   
     end
+
+    # Populate the endpoints for this entity
+    # @return [Fixnum]
+    def populate_endpoints
+      @endpoints.keys.map { |type| populate_endpoints_by_type(type) }.reduce(&:+)
+    end
     
     # The number of endpoints for this entity
+    # @param [Symbol] type The endpoint type eg :source, :destination
     def number_of_endpoints(type)
       case type
         when :source then Map.MIDIEntityGetNumberOfSources(@resource)
@@ -56,33 +78,43 @@ module CoreMIDI
       end
     end
     
-    # A CFString property
-    def get_string(name, pointer)
-      prop = Map::CF.CFStringCreateWithCString( nil, name.to_s, 0 )
-      val = Map::CF.CFStringCreateWithCString( nil, name.to_s, 0 ) # placeholder
-      Map::MIDIObjectGetStringProperty(pointer, prop, val)
-      Map::CF.CFStringGetCStringPtr(val.read_pointer, 0).read_string rescue nil
+    # A CFString property from the underlying entity
+    # @param [Symbol, String] name The property name
+    # @return [String, nil]
+    def get_string(name)
+      Map.get_string(@resource, name)
     end
     
-    # An Integer property
-    def get_int(name, pointer)
-      prop = Map::CF.CFStringCreateWithCString( nil, name.to_s, 0 )
-      val = FFI::MemoryPointer.new(:pointer, 32)
-      Map::MIDIObjectGetIntegerProperty(pointer, prop, val)
-      val.read_int
+    # An Integer property from the underlying entity
+    # @param [Symbol, String] name The property name
+    # @return [Fixnum, nil]
+    def get_int(name)
+      property = Map::CF.CFStringCreateWithCString(nil, name.to_s, 0)
+      value = FFI::MemoryPointer.new(:pointer, 32)
+      Map::MIDIObjectGetIntegerProperty(@resource, property, value)
+      value.read_int
     end        
 
-    # A CString or Integer property from this Endpoint's entity
+    # A CString or Integer property from the underlying entity
+    # @param [Symbol, String] name The property name
+    # @param [Hash] options
+    # @option options [Symbol] :type The property type eg :int, :string (default :string)
+    # @return [Fixnum, String, nil]
     def get_property(name, options = {})
-      from = options[:from] || @resource
-      type = options[:type] || :string
-      
-      case type
-        when :string then get_string(name, from)
-        when :int then get_int(name, from)
+      case options[:type]
+        when :string, nil then get_string(name)
+        when :int then get_int(name)
       end
     end
 
+    # Populate the entity properties from the underlying resource
+    def populate
+      @manufacturer = get_property(:manufacturer)
+      @model = get_property(:model)
+      @name = get_name
+      populate_endpoints
+    end
+
   end
 
 end

data/lib/coremidi/map.rb

@@ -46,6 +46,28 @@ module CoreMIDI
 
     end
 
+    # @param [FFI::Pointer] resource A pointer to an underlying struct
+    # @param [String, Symbol] name The property name to get
+    # @return [String]
+    def self.get_string(resource, name)
+      property = Map::CF.CFStringCreateWithCString(nil, name.to_s, 0)
+      begin
+        pointer = FFI::MemoryPointer.new(:pointer)
+        Map::MIDIObjectGetStringProperty(resource, property, pointer)
+        string = pointer.read_pointer
+        length = Map::CF.CFStringGetMaximumSizeForEncoding(Map::CF.CFStringGetLength(string), :kCFStringEncodingUTF8)
+
+        bytes = FFI::MemoryPointer.new(length + 1)
+
+        if Map::CF.CFStringGetCString(string, bytes, length + 1, :kCFStringEncodingUTF8)
+          bytes.read_string.force_encoding("utf-8")
+        end
+      ensure
+        Map::CF.CFRelease(string) unless string.nil? || string.null?
+        Map::CF.CFRelease(property) unless property.null?
+      end
+    end
+
     callback :MIDIReadProc, [MIDIPacketList.by_ref, :pointer, :pointer], :pointer
 
     attach_function :MIDIClientCreate, [:pointer, :pointer, :pointer, :pointer], :int

data/lib/coremidi/source.rb

@@ -49,23 +49,25 @@ module CoreMIDI
     alias_method :gets_bytestr, :gets_s
 
     # Enable this the input for use; can be passed a block
+    # @return [Source]
     def enable(options = {}, &block)
-      @enabled = true
-
-      if block_given?
-        begin
-          yield(self)
-        ensure
-          close
+      if !@enabled
+        @enabled = true
+        if block_given?
+          begin
+            yield(self)
+          ensure
+            close
+          end
         end
-      else
-        self
       end
+      self
     end
     alias_method :open, :enable
     alias_method :start, :enable
 
     # Close this input
+    # @return [Boolean]
     def close
       #error = Map.MIDIPortDisconnectSource( @handle, @resource )
       #raise "MIDIPortDisconnectSource returned error code #{error}" unless error.zero?
@@ -75,21 +77,28 @@ module CoreMIDI
       #raise "MIDIPortDispose returned error code #{error}" unless error.zero?
       #error = Map.MIDIEndpointDispose(@resource)
       #raise "MIDIEndpointDispose returned error code #{error}" unless error.zero?
-      @enabled = false
-      true
+      if @enabled
+        @enabled = false
+        true
+      else
+        false
+      end
     end
 
     # Shortcut to the first available input endpoint
+    # @return [Source]
     def self.first
       Endpoint.first(:source)
     end
 
     # Shortcut to the last available input endpoint
+    # @return [Source]
     def self.last
       Endpoint.last(:source)
     end
 
     # All input endpoints
+    # @return [Array<Source>]
     def self.all
       Endpoint.all_by_type[:source]
     end
@@ -181,6 +190,8 @@ module CoreMIDI
     end
     
     # Convert an array of numeric byes to a hex string (e.g. [0x90, 0x40, 0x40] becomes "904040")
+    # @param [Array<Fixnum>] bytes
+    # @return [String]
     def numeric_bytes_to_hex_string(bytes)
       string_bytes = bytes.map do |byte| 
         str = byte.to_s(16).upcase

data/test/input_buffer_test.rb

@@ -2,42 +2,41 @@ require "helper"
 
 class InputBufferTest < Test::Unit::TestCase
 
-  include CoreMIDI
-  include TestHelper
+  context "CoreMIDI" do
 
-  def test_input_buffer
-    sleep(1)
+    setup do
+      sleep(1)
+    end
 
-    messages = VariousMIDIMessages
-    bytes = []
+    context "Source#buffer" do
 
-    $test_device[:output].open do |output|
-      $test_device[:input].open do |input|
-        
-        input.buffer.clear
+      setup do
+        @messages = TestHelper::VariousMIDIMessages
+        @messages_arr = @messages.inject { |a,b| a+b }.flatten
+        @received_arr = []
+        @pointer = 0
 
-        messages.each do |msg|
+        @output = $test_device[:output].open
+        @input = $test_device[:input].open
+        @input.buffer.clear
+      end
 
-          $>.puts "sending: " + msg.inspect
+      should "have the correct messages in the buffer" do
+        bytes = []
+        @messages.each do |message|
+          puts "sending: #{message.inspect}"
+          @output.puts(message)
+          bytes += message 
 
-          output.puts(msg)
-          
-          bytes += msg 
-          
           sleep(0.5)
-          
-          buffer = input.buffer.map { |m| m[:data] }.flatten
 
-          $>.puts "received: " + buffer.to_s
-          
+          buffer = @input.buffer.map { |m| m[:data] }.flatten
+          puts "received: #{buffer.to_s}"
           assert_equal(bytes, buffer)
-
         end
-        
-        assert_equal(bytes.length, input.buffer.map { |m| m[:data] }.flatten.length)
-
+        assert_equal(bytes.length, @input.buffer.map { |m| m[:data] }.flatten.length)
       end
     end
-  end
 
+  end
 end

data/test/io_test.rb

@@ -1,4 +1,4 @@
-require 'helper'
+require "helper"
 
 class CoreMIDI::IOTest < Test::Unit::TestCase
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ffi-coremidi
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Ari Russo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-31 00:00:00.000000000 Z
+date: 2014-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi