juce/source/src/audio/midi/juce_MidiInput.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_MIDIINPUT_JUCEHEADER__
  27 #define __JUCE_MIDIINPUT_JUCEHEADER__
  28
  29 #include "../midi/juce_MidiMessage.h"
  30 #include "../../text/juce_StringArray.h"
  31 class MidiInput;
  32
  33
  34 //==============================================================================
  35 /**
  36     Receives incoming messages from a physical MIDI input device.
  37
  38     This class is overridden to handle incoming midi messages. See the MidiInput
  39     class for more details.
  40
  41     @see MidiInput
  42 */
  43 class JUCE_API  MidiInputCallback
  44 {
  45 public:
  46     /** Destructor. */
  47     virtual ~MidiInputCallback()  {}
  48
  49
  50     /** Receives an incoming message.
  51
  52         A MidiInput object will call this method when a midi event arrives. It'll be
  53         called on a high-priority system thread, so avoid doing anything time-consuming
  54         in here, and avoid making any UI calls. You might find the MidiBuffer class helpful
  55         for queueing incoming messages for use later.
  56
  57         @param source   the MidiInput object that generated the message
  58         @param message  the incoming message. The message's timestamp is set to a value
  59                         equivalent to (Time::getMillisecondCounter() / 1000.0) to specify the
  60                         time when the message arrived.
  61     */
  62     virtual void handleIncomingMidiMessage (MidiInput* source,
  63                                             const MidiMessage& message) = 0;
  64
  65     /** Notification sent each time a packet of a multi-packet sysex message arrives.
  66
  67         If a long sysex message is broken up into multiple packets, this callback is made
  68         for each packet that arrives until the message is finished, at which point
  69         the normal handleIncomingMidiMessage() callback will be made with the entire
  70         message.
  71
  72         The message passed in will contain the start of a sysex, but won't be finished
  73         with the terminating 0xf7 byte.
  74     */
  75     virtual void handlePartialSysexMessage (MidiInput* source,
  76                                             const uint8* messageData,
  77                                             const int numBytesSoFar,
  78                                             const double timestamp)
  79     {
  80         // (this bit is just to avoid compiler warnings about unused variables)
  81         (void) source; (void) messageData; (void) numBytesSoFar; (void) timestamp;
  82     }
  83 };
  84
  85 //==============================================================================
  86 /**
  87     Represents a midi input device.
  88
  89     To create one of these, use the static getDevices() method to find out what inputs are
  90     available, and then use the openDevice() method to try to open one.
  91
  92     @see MidiOutput
  93 */
  94 class JUCE_API  MidiInput
  95 {
  96 public:
  97     //==============================================================================
  98     /** Returns a list of the available midi input devices.
  99
 100         You can open one of the devices by passing its index into the
 101         openDevice() method.
 102
 103         @see getDefaultDeviceIndex, openDevice
 104     */
 105     static StringArray getDevices();
 106
 107     /** Returns the index of the default midi input device to use.
 108
 109         This refers to the index in the list returned by getDevices().
 110     */
 111     static int getDefaultDeviceIndex();
 112
 113     /** Tries to open one of the midi input devices.
 114
 115         This will return a MidiInput object if it manages to open it. You can then
 116         call start() and stop() on this device, and delete it when no longer needed.
 117
 118         If the device can't be opened, this will return a null pointer.
 119
 120         @param deviceIndex  the index of a device from the list returned by getDevices()
 121         @param callback     the object that will receive the midi messages from this device.
 122
 123         @see MidiInputCallback, getDevices
 124     */
 125     static MidiInput* openDevice (int deviceIndex,
 126                                   MidiInputCallback* callback);
 127
 128    #if JUCE_LINUX || JUCE_MAC || DOXYGEN
 129     /** This will try to create a new midi input device (Not available on Windows).
 130
 131         This will attempt to create a new midi input device with the specified name,
 132         for other apps to connect to.
 133
 134         Returns 0 if a device can't be created.
 135
 136         @param deviceName   the name to use for the new device
 137         @param callback     the object that will receive the midi messages from this device.
 138     */
 139     static MidiInput* createNewDevice (const String& deviceName,
 140                                        MidiInputCallback* callback);
 141    #endif
 142
 143     //==============================================================================
 144     /** Destructor. */
 145     virtual ~MidiInput();
 146
 147     /** Returns the name of this device. */
 148     const String& getName() const noexcept                      { return name; }
 149
 150     /** Allows you to set a custom name for the device, in case you don't like the name
 151         it was given when created.
 152     */
 153     void setName (const String& newName) noexcept               { name = newName; }
 154
 155     //==============================================================================
 156     /** Starts the device running.
 157
 158         After calling this, the device will start sending midi messages to the
 159         MidiInputCallback object that was specified when the openDevice() method
 160         was called.
 161
 162         @see stop
 163     */
 164     virtual void start();
 165
 166     /** Stops the device running.
 167
 168         @see start
 169     */
 170     virtual void stop();
 171
 172 protected:
 173     //==============================================================================
 174     String name;
 175     void* internal;
 176
 177     explicit MidiInput (const String& name);
 178
 179 private:
 180     //==============================================================================
 181     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (MidiInput);
 182 };
 183
 184
 185 #endif   // __JUCE_MIDIINPUT_JUCEHEADER__