Class: CoreMIDI::Device

Inherits:
Object
  • Object
show all
Defined in:
lib/coremidi/device.rb

Overview

A MIDI device may have multiple logically distinct sub-components. For example, one device may encompass a MIDI synthesizer and a pair of MIDI ports, both addressable via a USB port. Each such element of a device is called a MIDI entity.

developer.apple.com/library/ios/documentation/CoreMidi/Reference/MIDIServices_Reference/Reference/reference.html

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id, device_pointer, options = {}) ⇒ Device

Returns a new instance of Device.

Parameters:

  • id (Integer) —

    The ID for the device

  • device_pointer (Object) —

    The underlying device pointer

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :include_offline (Boolean) —

    Whether to include offline entities (default: false)



18
19
20
21
22
23
 
# File 'lib/coremidi/device.rb', line 18

def initialize(id, device_pointer, options = {})
  @id = id
  @resource = device_pointer
  @entities = []
  populate(options)
end

Instance Attribute Details

#entities ⇒ Object (readonly)

Returns the value of attribute entities.



10
11
12
 
# File 'lib/coremidi/device.rb', line 10

def entities
  @entities
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



10
11
12
 
# File 'lib/coremidi/device.rb', line 10

def id
  @id
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



10
11
12
 
# File 'lib/coremidi/device.rb', line 10

def name
  @name
end

Class Method Details

.all(options = {}) ⇒ Array<Device>

All cached devices

Parameters:

  • options (Hash) (defaults to: {}) —

    The options to select devices with

Options Hash (options):

  • :cache (Boolean) —

    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.

  • :include_offline (Boolean) —

    If true, devices marked offline by coremidi will be included in the list

Returns:

  • (Array<Device>) —

    All cached devices



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/coremidi/device.rb', line 50

def self.all(options = {})
  use_cache = options[:cache] || true
  include_offline = options[:include_offline] || false
  if !populated? || !use_cache
    @devices = []
    counter = 0
    until (device_pointer = API.MIDIGetDevice(counter)).null?
      device = new(counter, device_pointer, include_offline: include_offline)
      @devices << device
      counter += 1
    end
    populate_endpoint_ids
  end
  @devices
end

.populated? ⇒ Boolean

Has the device list been populated?

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/coremidi/device.rb', line 74

def self.populated?
  !@devices.nil? && !@devices.empty?
end

.refresh ⇒ Array<Device>

Refresh the Device cache. This is needed if, for example a USB MIDI device is plugged in while the program is running

Returns:

  • (Array<Device>) —

    The Device cache



68
69
70
71
 
# File 'lib/coremidi/device.rb', line 68

def self.refresh
  @devices.clear
  @devices
end

Instance Method Details

#endpoints ⇒ Array<Endpoint>

Endpoints for this device

Returns:



27
28
29
30
31
32
33
34
 
# File 'lib/coremidi/device.rb', line 27

def endpoints
  endpoints = { source: [], destination: [] }
  endpoints.each_key do |key|
    endpoint_group = entities.map { |entity| entity.endpoints[key] }.flatten
    endpoints[key] += endpoint_group
  end
  endpoints
end

#populate_endpoint_ids(last_id) ⇒ Integer

Assign all of this Device’s endpoints an consecutive local id

Parameters:

  • last_id (Integer) —

    The highest already used endpoint ID

Returns:

  • (Integer) —

    The highest used endpoint ID after populating this device’s endpoints



39
40
41
42
43
 
# File 'lib/coremidi/device.rb', line 39

def populate_endpoint_ids(last_id)
  id = 0
  entities.each { |entity| id += entity.populate_endpoint_ids(id + last_id) }
  id
end