ffi-coremidi 0.1.8 → 0.2.0

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2011 Ari Russo
+Copyright 2011-2013 Ari Russo
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -10,4 +10,4 @@ Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
-limitations under the License.
+limitations under the License.

data/README.md

@@ -0,0 +1,51 @@
+# ffi-coremidi
+
+#### Realtime MIDI IO with Ruby for OSX
+
+This is a Ruby implementation of the Apple Core MIDI framework 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 with a similar API.
+
+### Features
+
+* Simpler API than Core MIDI
+* Input and output on multiple devices concurrently
+* Agnostically handle different MIDI Message types (including SysEx)
+* Timestamped input events
+* Internally patch MIDI to other programs using IAC 
+
+### Requirements
+
+* [ffi](http://github.com/ffi/ffi)
+
+### Install
+
+If you're using Bundler, add this line to your application's Gemfile:
+
+`gem "ffi-coremidi"`
+  
+Otherwise
+
+`gem install ffi-coremidi`
+  
+### Documentation
+
+[rdoc](http://rubydoc.info/github/arirusso/ffi-coremidi)
+
+### Author
+
+[Ari Russo](http://github.com/arirusso) <ari.russo at gmail.com>
+
+### Credits
+
+This library began with some coremidi/ffi binding code for MIDI output by [Colin Harris](http://github.com/aberant) contained in [his fork of MIDIator](http://github.com/aberant/midiator) and a [blog post](http://aberant.tumblr.com/post/694878119/sending-midi-sysex-with-core-midi-and-ruby-ffi).
+
+[MIDIator](http://github.com/bleything/midiator) is (c)2008 by Ben Bleything and Topher Cyll and released under the MIT license (see LICENSE.midiator and LICENSE.prp)
+
+Also thank you to [Jeremy Voorhis](http://github.com/jvoorhis) for some useful debugging.
+
+### License
+
+Apache 2.0, See the file LICENSE
+
+Copyright (c) 2011-2013 [Ari Russo](http://github.com/arirusso)

data/lib/coremidi.rb

@@ -1,9 +1,6 @@
-#!/usr/bin/env ruby
-#
 # ffi-coremidi
 # Realtime MIDI IO with Ruby for OSX
-# (c)2011 Ari Russo
-# 
+# (c)2011-2013 Ari Russo
 
 # libs
 require 'ffi'
@@ -20,5 +17,5 @@ require 'coremidi/source'
 require 'coremidi/destination'
 
 module CoreMIDI
-  VERSION = "0.1.8"
+  VERSION = "0.2.0"
 end

data/lib/coremidi/destination.rb

@@ -1,29 +1,18 @@
-#!/usr/bin/env ruby
-
 module CoreMIDI
 
-  #
   # Output/Destination endpoint class
-  #
   class Destination
 
     include Endpoint
 
     attr_reader :entity
 
-    # close this output
+    # Close this output
     def close
-      #error = Map.MIDIClientDispose(@handle)
-      #raise "MIDIClientDispose returned error code #{error}" unless error.zero?
-      #error = Map.MIDIPortDispose(@handle)
-      #raise "MIDIPortDispose returned error code #{error}" unless error.zero?
-      #error = Map.MIDIEndpointDispose(@resource)
-      #raise "MIDIEndpointDispose returned error code #{error}" unless error.zero?
       @enabled = false
-
     end
 
-    # sends a MIDI message comprised of a String of hex digits
+    # Send a MIDI message comprised of a String of hex digits
     def puts_s(data)
       data = data.dup
 	    output = []
@@ -35,7 +24,7 @@ module CoreMIDI
     alias_method :puts_bytestr, :puts_s
     alias_method :puts_hex, :puts_s
 
-    # sends a MIDI messages comprised of Numeric bytes
+    # Send a MIDI messages comprised of Numeric bytes
     def puts_bytes(*data)
 
       format = "C" * data.size
@@ -49,7 +38,7 @@ module CoreMIDI
       end
     end
 
-    # send a MIDI message of an indeterminant type
+    # Send a MIDI message of an indeterminant type
     def puts(*a)
   	  case a.first
         when Array then puts_bytes(*a.first)
@@ -59,7 +48,7 @@ module CoreMIDI
     end
     alias_method :write, :puts
 
-    # enable this device
+    # Enable this device
     def enable(options = {}, &block)
       @enabled = true
       if block_given?
@@ -75,29 +64,28 @@ module CoreMIDI
     alias_method :open, :enable
     alias_method :start, :enable
 
-    # shortcut to the first output endpoint available
+    # Shortcut to the first output endpoint available
     def self.first
       Endpoint.first(:destination)
     end
     
-    # shortcut to the last output endpoint available
+    # Shortcut to the last output endpoint available
     def self.last
       Endpoint.last(:destination)
     end
 
-    # all output endpoints
+    # All output endpoints
     def self.all
       Endpoint.all_by_type[:destination]
     end
     
     protected
 
-    # base initialization for this endpoint -- done whether or not the endpoint is enabled to
+    # Base initialization for this endpoint -- done whether or not the endpoint is enabled to
     # check whether it is truly available for use
     def connect
       client_error = enable_client
       port_error = initialize_port
-
       @resource = Map.MIDIEntityGetDestination( @entity.resource, @resource_id )
       !@resource.address.zero? && client_error.zero? && port_error.zero?
     end
@@ -105,24 +93,21 @@ module CoreMIDI
 
     private
 
-    # output a short MIDI message
+    # Output a short MIDI message
     def puts_small(bytes, size)
       packet_list = FFI::MemoryPointer.new(256)
       packet_ptr = Map.MIDIPacketListInit(packet_list)
-
       if Map::SnowLeopard
         packet_ptr = Map.MIDIPacketListAdd(packet_list, 256, packet_ptr, 0, size, bytes)
       else
         # Pass in two 32-bit 0s for the 64 bit time
         packet_ptr = Map.MIDIPacketListAdd(packet_list, 256, packet_ptr, 0, 0, size, bytes)
       end
-
       Map.MIDISend( @handle, @resource, packet_list )
     end
 
-    # output a System Exclusive MIDI message
+    # Output a System Exclusive MIDI message
     def puts_sysex(bytes, size)
-
       request = Map::MIDISysexSendRequest.new
       request[:destination] = @resource
       request[:data] = bytes
@@ -130,17 +115,15 @@ module CoreMIDI
       request[:complete] = 0
       request[:completion_proc] = SysexCompletionCallback
       request[:completion_ref_con] = request
-
       Map.MIDISendSysex(request)
     end
 
     SysexCompletionCallback =
       FFI::Function.new(:void, [:pointer]) do |sysex_request_ptr|
-        # this isn't working for some reason
-        # as of now, we don't need it though
+        # this isn't working for some reason. as of now, it's not needed though
       end
       
-    # initialize a coremidi port for this endpoint
+    # Initialize a coremidi port for this endpoint
     def initialize_port
       port_name = Map::CF.CFStringCreateWithCString(nil, "Port #{@resource_id}: #{name}", 0)
       outport_ptr = FFI::MemoryPointer.new(:pointer)

data/lib/coremidi/device.rb

@@ -1,36 +1,44 @@
-#!/usr/bin/env ruby
-
 module CoreMIDI
 
   class Device
 
     attr_reader :entities,
-                # unique Numeric id
-                :id,
-                # device name from coremidi
-                :name
+                :id, # Unique Numeric id
+                :name # Device name from coremidi
 
     def initialize(id, device_pointer, options = {})
-      include_if_offline = options[:include_offline] || false
+      include_if_offline = options.fetch(:include_offline, false)
       @id = id
       @resource = device_pointer
       @entities = []
-      
-      prop = Map::CF.CFStringCreateWithCString( nil, "name", 0 )
-      name = Map::CF.CFStringCreateWithCString( nil, id.to_s, 0 )
-      Map::MIDIObjectGetStringProperty(@resource, prop, name)
-
-      @name = Map::CF.CFStringGetCStringPtr(name.read_pointer, 0).read_string
+      populate_name
       populate_entities(:include_offline => include_if_offline)
     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
+      end
+      endpoints
+    end
     
-    # returns all devices which are cached in an instance variable @devices on the Device class
-    #
-    # options:
-    # 
-    # * <b>cache</b>: if false, the device list will never be cached. this would be useful if one needs to alter the device list (e.g. plug in a USB MIDI interface) while their program is running.
-    # * <b>include_offline</b>: if true, devices marked offline by coremidi will be included in the list
-    #
+    # Assign all of this Device's endpoints an consecutive local id
+    # @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
+    end
+
+    # All cached devices
+    # @param [Hash] options The options to select devices with
+    # @option options [Boolean] :cache If false, the device list will never be cached. This would be useful if one needs to alter the device list (e.g. plug in a USB MIDI interface) while their program is running.
+    # @option options [Boolean] :include_offline If true, devices marked offline by coremidi will be included in the list
+    # @return [Array<Device>] All cached devices
     def self.all(options = {})
       use_cache = options[:cache] || true
       include_offline = options[:include_offline] || false
@@ -46,38 +54,42 @@ module CoreMIDI
       end
       @devices
     end
-    
-    # Refresh the Device cash.  You'll need to do this if, for instance, you plug in
-    # a USB MIDI device while the program is running 
+
+    # Refresh the Device cache. This is needed if, for example a USB MIDI device is plugged in while the program is running
+    # @return [Array<Device>] The Device cache
     def self.refresh
       @devices.clear
-    end
-    
-    # returns all of the Endpoints for this device
-    def endpoints
-      endpoints = { :source => [], :destination => [] }
-      endpoints.keys.each do |k|
-        endpoints[k] += entities.map { |entity| entity.endpoints[k] }.flatten
-      end
-      endpoints
-    end
-    
-    # assign all of this Device's endpoints an consecutive local id
-    def populate_endpoint_ids(starting_id)
-      i = 0
-      entities.each { |entity| i += entity.populate_endpoint_ids(i + starting_id) }
-      i
+      @devices
     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
+    end
     
-    # gives all of the endpoints for all devices a consecutive local id
+    # 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) }
     end
 
-    # populates the entities for this device. these are in turn used to gather the endpoints
+    # Populates the entities for this device. These entities are in turn used to gather the endpoints.
+    #
     def populate_entities(options = {})
       include_if_offline = options[:include_offline] || false
       i = 0

data/lib/coremidi/endpoint.rb

@@ -1,18 +1,13 @@
-#!/usr/bin/env ruby
-
 module CoreMIDI
 
   module Endpoint
     
     extend Forwardable
 
-                # has the endpoint been initialized?
-    attr_reader :enabled,
-                :entity,
-                # unique local Numeric id of the endpoint
+    attr_reader :enabled, # has the endpoint been initialized?
+                :entity, # unique local Numeric id of the endpoint
                 :id,
-                :resource_id,
-                # :input or :output
+                :resource_id, # :input or :output
                 :type
                 
     def_delegators :entity, :manufacturer, :model, :name
@@ -26,27 +21,27 @@ module CoreMIDI
       @enabled = false
     end
     
-    # is this endpoint online?
+    # Is this endpoint online?
     def online?
       @entity.online? && connect?
     end
     
-    # sets the id for this endpoint (the id is immutable once its set)
+    # Set the id for this endpoint (the id is immutable once its set)
     def id=(val)
       @id ||= val
     end
 
-    # select the first endpoint of type <em>type</em>
+    # Select the first endpoint of the specified type
     def self.first(type)
       all_by_type[type].first
     end
 
-    # select the last endpoint of type <em>type</em>
+    # Select the last endpoint of the specified type
     def self.last(type)
       all_by_type[type].last
     end
 
-    # a Hash of :source and :destination endpoints
+    # A Hash of :source and :destination endpoints
     def self.all_by_type
       {
         :source => Device.all.map { |d| d.endpoints[:source] }.flatten,
@@ -54,14 +49,14 @@ module CoreMIDI
       }
     end
 
-    # all endpoints of both types
+    # All endpoints of both types
     def self.all
       Device.all.map { |d| d.endpoints }.flatten
     end
     
     protected
     
-    # enables the coremidi MIDI client that will go with this endpoint
+    # 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_ptr = FFI::MemoryPointer.new(:pointer)

data/lib/coremidi/entity.rb

@@ -1,5 +1,3 @@
-#!/usr/bin/env ruby
-
 module CoreMIDI
 
   class Entity
@@ -23,7 +21,7 @@ module CoreMIDI
       @endpoints.keys.each { |type| populate_endpoints(type) }
     end
     
-    # assign all of this Entity's endpoints an consecutive local id
+    # Assign all of this Entity's endpoints an consecutive local id
     def populate_endpoint_ids(starting_id)
       i = 0
       @endpoints.values.flatten.each do |e|  
@@ -35,7 +33,7 @@ module CoreMIDI
     
     private
     
-    # populate endpoints of <em>type</em> for this entity
+    # 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
@@ -50,7 +48,7 @@ module CoreMIDI
       @endpoints[type].size   
     end
     
-    # gets the number of endpoints for this entity
+    # The number of endpoints for this entity
     def number_of_endpoints(type)
       case type
         when :source then Map.MIDIEntityGetNumberOfSources(@resource)
@@ -58,7 +56,7 @@ module CoreMIDI
       end
     end
     
-    # gets a CFString property
+    # 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
@@ -66,7 +64,7 @@ module CoreMIDI
       Map::CF.CFStringGetCStringPtr(val.read_pointer, 0).read_string rescue nil
     end
     
-    # gets an Integer property
+    # An Integer property
     def get_int(name, pointer)
       prop = Map::CF.CFStringCreateWithCString( nil, name.to_s, 0 )
       val = FFI::MemoryPointer.new(:pointer, 32)
@@ -74,7 +72,7 @@ module CoreMIDI
       val.read_int
     end        
 
-    # gets a CString or Integer property from this Endpoint's entity
+    # A CString or Integer property from this Endpoint's entity
     def get_property(name, options = {})
       from = options[:from] || @resource
       type = options[:type] || :string

data/lib/coremidi/map.rb

@@ -1,11 +1,6 @@
-#!/usr/bin/env ruby
-
 module CoreMIDI
 
-  #
-  # coremidi binding
-  #
-  #
+  # Coremidi C binding
   module Map
 
     extend FFI::Library
@@ -122,11 +117,23 @@ module CoreMIDI
       extend FFI::Library
       ffi_lib '/System/Library/Frameworks/CoreFoundation.framework/Versions/Current/CoreFoundation'
 
+      typedef :pointer, :CFStringRef
+      typedef :long, :CFIndex
+      enum :CFStringEncoding, [ :kCFStringEncodingUTF8, 0x08000100 ]
+
       # CFString* CFStringCreateWithCString( ?, CString, encoding)
       attach_function :CFStringCreateWithCString, [:pointer, :string, :int], :pointer
       # CString* CFStringGetCStringPtr(CFString*, encoding)
       attach_function :CFStringGetCStringPtr, [:pointer, :int], :pointer
 
+      attach_function :CFStringGetLength, [ :CFStringRef ], :CFIndex
+
+      attach_function :CFStringGetMaximumSizeForEncoding, [ :CFIndex, :CFStringEncoding ], :long
+
+      attach_function :CFStringGetCString, [ :CFStringRef, :pointer, :CFIndex, :CFStringEncoding ], :bool
+
+      attach_function :CFRelease, [ :pointer ], :void
+
     end
 
     module HostTime

data/lib/coremidi/source.rb

@@ -1,10 +1,6 @@
-#!/usr/bin/env ruby
-
 module CoreMIDI
 
-  #
   # Input/Source endpoint class
-  #
   class Source
 
     include Endpoint
@@ -63,7 +59,7 @@ module CoreMIDI
     alias_method :open, :enable
     alias_method :start, :enable
 
-    # close this input
+    # Close this input
     def close
       #error = Map.MIDIPortDisconnectSource( @handle, @resource )
       #raise "MIDIPortDisconnectSource returned error code #{error}" unless error.zero?
@@ -76,25 +72,25 @@ module CoreMIDI
       @enabled = false
     end
 
-    # shortcut to the first available input endpoint
+    # Shortcut to the first available input endpoint
     def self.first
       Endpoint.first(:source)
     end
 
-    # shortcut to the last available input endpoint
+    # Shortcut to the last available input endpoint
     def self.last
       Endpoint.last(:source)
     end
 
-    # all input endpoints
+    # All input endpoints
     def self.all
       Endpoint.all_by_type[:source]
     end
     
     protected
     
-    # base initialization for this endpoint -- done whether or not the endpoint is enabled to
-    # check whether it is truly available for use
+    # Base initialization for this endpoint -- done whether or not the endpoint is enabled to check whether 
+    # it is truly available for use
     def connect   
       enable_client
       initialize_port
@@ -110,17 +106,17 @@ module CoreMIDI
 
     private
 
-    # returns new MIDI messages from the queue
+    # New MIDI messages from the queue
     def queued_messages
       @buffer.slice(@pointer, @buffer.length - @pointer)
     end
 
-    # are there new MIDI messages in the queue?
+    # Are there new MIDI messages in the queue?
     def queued_messages?
       @pointer < @buffer.length
     end
 
-    # the callback which is called by coremidi when new MIDI messages are in the buffer
+    # The callback fired by coremidi when new MIDI messages are in the buffer
     def get_event_callback
       Proc.new do | new_packets, refCon_ptr, connRefCon_ptr |
         time = Time.now.to_f
@@ -142,17 +138,17 @@ module CoreMIDI
       end
     end
 
-    # timestamp
+    # Timestamp for a received MIDI message
     def timestamp(now)
       ((now - @start_time) * 1000)
     end
 
-    # give a message its timestamp and package it in a Hash
+    # Give a message its timestamp and package it in a Hash
     def get_message_formatted(raw, time)
       { :data => raw, :timestamp => timestamp(time) }
     end
 
-    # initialize a coremidi port for this endpoint
+    # Initialize a coremidi port for this endpoint
     def initialize_port
       port_name = Map::CF.CFStringCreateWithCString(nil, "Port #{@resource_id}: #{name}", 0)
       handle_ptr = FFI::MemoryPointer.new(:pointer)
@@ -162,7 +158,7 @@ module CoreMIDI
       raise "MIDIInputPortCreate returned error code #{error}" unless error.zero?
     end
     
-    # initialize the MIDI message buffer
+    # Initialize the MIDI message buffer
     def initialize_buffer
       @pointer = 0
       @buffer = []
@@ -172,9 +168,7 @@ module CoreMIDI
       end     
     end
     
-    # convert an array of numeric byes to a hex string
-    # e.g.
-    # [0x90, 0x40, 0x40] -> "904040"
+    # Convert an array of numeric byes to a hex string (e.g. [0x90, 0x40, 0x40] becomes "904040")
     def numeric_bytes_to_hex_string(bytes)
       bytes.map { |b| s = b.to_s(16).upcase; b < 16 ? s = "0" + s : s; s }.join
     end 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ffi-coremidi
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-21 00:00:00.000000000 Z
+date: 2013-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -45,7 +45,7 @@ files:
 - test/test_input_buffer.rb
 - test/test_io.rb
 - LICENSE
-- README.rdoc
+- README.md
 homepage: http://github.com/arirusso/ffi-coremidi
 licenses: []
 post_install_message: 
@@ -66,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: ffi-coremidi
-rubygems_version: 1.8.23
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Realtime MIDI IO with Ruby for OSX

data/README.rdoc

@@ -1,48 +0,0 @@
-= ffi-coremidi
-
-== Summary
-
-Realtime MIDI IO with Ruby for OSX
-
-Note that in the interest of allowing people on other platforms to utilize your code, you should consider using {unimidi}[http://github.com/arirusso/unimidi].  Unimidi is a platform independent wrapper that implements this library and has a similar API.
-
-== Features
-
-* Simplified API
-* Input and output on multiple devices concurrently
-* Agnostically handle different MIDI Message types (including SysEx)
-* Timestamped input events
-* Internally patch MIDI to other programs using IAC (and {MIDI Patch Bay}[http://notahat.com/midi_patchbay] if you're using OSX Snow Leopard or earlier)
-== Requirements
-
-* {ffi}[http://github.com/ffi/ffi] (gem install ffi)
-
-== Install
-
-  gem install ffi-coremidi
-  
-== Documentation
-
-* {rdoc}[http://rubydoc.info/github/arirusso/ffi-coremidi]
-
-== Author
-
-* {Ari Russo}[http://github.com/arirusso] <ari.russo at gmail.com>
-
-== Credits
-
-This library began with some coremidi/ffi binding code for MIDI output by
-
-* Colin Harris -- http://github.com/aberant
-
-contained in {his fork of MIDIator}[http://github.com/aberant/midiator] and a {blog post}[http://aberant.tumblr.com/post/694878119/sending-midi-sysex-with-core-midi-and-ruby-ffi]
-
-{MIDIator}[http://github.com/bleything/midiator] is (c)2008 by Ben Bleything and Topher Cyll and released under the MIT license (see LICENSE.midiator and LICENSE.prp)
-
-Also thank you to {Jeremy Voorhis}[http://github.com/jvoorhis] for some useful debugging
-
-== License
-
-Apache 2.0, See the file LICENSE
-
-Copyright (c) 2011 Ari Russo