v2/rtmidi.h

   1 /**********************************************************************/
   2 /*! \class RtMidi
   3     \brief An abstract base class for realtime MIDI input/output.
   4
   5     This class implements some common functionality for the realtime
   6     MIDI input/output subclasses RtMidiIn and RtMidiOut.
   7
   8     RtMidi WWW site: http://music.mcgill.ca/~gary/rtmidi/
   9
  10     RtMidi: realtime MIDI i/o C++ classes
  11     Copyright (c) 2003-2005 Gary P. Scavone
  12
  13     Permission is hereby granted, free of charge, to any person
  14     obtaining a copy of this software and associated documentation files
  15     (the "Software"), to deal in the Software without restriction,
  16     including without limitation the rights to use, copy, modify, merge,
  17     publish, distribute, sublicense, and/or sell copies of the Software,
  18     and to permit persons to whom the Software is furnished to do so,
  19     subject to the following conditions:
  20
  21     The above copyright notice and this permission notice shall be
  22     included in all copies or substantial portions of the Software.
  23
  24     Any person wishing to distribute modifications to the Software is
  25     requested to send the modifications to the original developer so that
  26     they can be incorporated into the canonical version.
  27
  28     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  29     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  30     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  31     IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
  32     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  33     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  34     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  35 */
  36 /**********************************************************************/
  37
  38 // RtMidi: Version 1.0.4, 14 October 2005
  39
  40 #ifndef RTMIDI_H
  41 #define RTMIDI_H
  42
  43 #include "rterror.h"
  44 #include <string>
  45
  46 class RtMidi
  47 {
  48  public:
  49
  50   //! Pure virtual openPort() function.
  51   virtual void openPort( unsigned int portNumber = 0 ) = 0;
  52
  53   //! Pure virtual openVirtualPort() function.
  54   virtual void openVirtualPort() = 0;
  55
  56   //! Pure virtual getPortCount() function.
  57   virtual unsigned int getPortCount() = 0;
  58
  59   //! Pure virtual getPortName() function.
  60   virtual std::string getPortName( unsigned int portNumber = 0 ) = 0;
  61
  62   //! Pure virtual closePort() function.
  63   virtual void closePort( void ) = 0;
  64
  65  protected:
  66
  67   RtMidi();
  68   virtual ~RtMidi() {};
  69
  70   // A basic error reporting function for internal use in the RtMidi
  71   // subclasses.  The behavior of this function can be modified to
  72   // suit specific needs.
  73   void error( RtError::Type type );
  74
  75   void *apiData_;
  76   bool connected_;
  77   std::string errorString_;
  78 };
  79
  80 /**********************************************************************/
  81 /*! \class RtMidiIn
  82     \brief A realtime MIDI input class.
  83
  84     This class provides a common, platform-independent API for
  85     realtime MIDI input.  It allows access to a single MIDI input
  86     port.  Incoming MIDI messages are either saved to a queue for
  87     retrieval using the getMessage() function or immediately passed to
  88     a user-specified callback function.  Create multiple instances of
  89     this class to connect to more than one MIDI device at the same
  90     time.  With the OS-X and Linux ALSA MIDI APIs, it is also possible
  91     to open a virtual input port to which other MIDI software clients
  92     can connect.
  93
  94     by Gary P. Scavone, 2003-2004.
  95 */
  96 /**********************************************************************/
  97
  98 #include <vector>
  99 #include <queue>
 100
 101 class RtMidiIn : public RtMidi
 102 {
 103  public:
 104
 105   //! User callback function type definition.
 106   typedef void (*RtMidiCallback)( double timeStamp, std::vector<unsigned char> *message, void *userData);
 107
 108   //! Default constructor.
 109   /*!
 110       An exception will be thrown if a MIDI system initialization error occurs.
 111   */
 112   RtMidiIn();
 113
 114   //! If a MIDI connection is still open, it will be closed by the destructor.
 115   ~RtMidiIn();
 116
 117   //! Open a MIDI input connection.
 118   /*!
 119       An optional port number greater than 0 can be specified.
 120       Otherwise, the default or first port found is opened.
 121   */
 122   void openPort( unsigned int portNumber = 0 );
 123
 124   //! Create a virtual input port to allow software connections (OS X and ALSA only).
 125   /*!
 126       This function creates a virtual MIDI input port to which other
 127       software applications can connect.  This type of functionality
 128       is currently only supported by the Macintosh OS-X and Linux ALSA
 129       APIs (the function does nothing for the other APIs).
 130   */
 131   void openVirtualPort();
 132
 133   //! Set a callback function to be invoked for incoming MIDI messages.
 134   /*!
 135       The callback function will be called whenever an incoming MIDI
 136       message is received.  While not absolutely necessary, it is best
 137       to set the callback function before opening a MIDI port to avoid
 138       leaving some messages in the queue.
 139   */
 140   void setCallback( RtMidiCallback callback, void *userData = 0 );
 141
 142   //! Cancel use of the current callback function (if one exists).
 143   /*!
 144       Subsequent incoming MIDI messages will be written to the queue
 145       and can be retrieved with the \e getMessage function.
 146   */
 147   void cancelCallback();
 148
 149   //! Close an open MIDI connection (if one exists).
 150   void closePort( void );
 151
 152   //! Return the number of available MIDI input ports.
 153   unsigned int getPortCount();
 154
 155   //! Return a string identifier for the specified MIDI input port number.
 156   /*!
 157       An exception is thrown if an invalid port specifier is provided.
 158   */
 159   std::string getPortName( unsigned int portNumber = 0 );
 160
 161   //! Set the maximum number of MIDI messages to be saved in the queue.
 162   /*!
 163       If the queue size limit is reached, incoming messages will be
 164       ignored.  The default limit is 1024.
 165   */
 166   void setQueueSizeLimit( unsigned int queueSize );
 167
 168   //! Specify whether certain MIDI message types should be queued or ignored during input.
 169   /*!
 170       By default, MIDI timing and active sensing messages are ignored
 171       during message input because of their relative high data rates.
 172       MIDI sysex messages are ignored by default as well.  Variable
 173       values of "true" imply that the respective message type will be
 174       ignored.
 175   */
 176   void ignoreTypes( bool midiSysex = true, bool midiTime = true, bool midiSense = true );
 177
 178   //! Fill the user-provided vector with the data bytes for the next available MIDI message in the input queue and return the event delta-time in seconds.
 179   /*!
 180       This function returns immediately whether a new message is
 181       available or not.  A valid message is indicated by a non-zero
 182       vector size.  An exception is thrown if an error occurs during
 183       message retrieval or an input connection was not previously
 184       established.
 185   */
 186   double getMessage( std::vector<unsigned char> *message );
 187
 188   // A MIDI structure used internally by the class to store incoming
 189   // messages.  Each message represents one and only one MIDI message.
 190   struct MidiMessage {
 191     std::vector<unsigned char> bytes;
 192     double timeStamp;
 193
 194     // Default constructor.
 195     MidiMessage()
 196       :bytes(3), timeStamp(0.0) {}
 197   };
 198
 199   // The RtMidiInData structure is used to pass private class data to
 200   // the MIDI input handling function or thread.
 201   struct RtMidiInData {
 202     std::queue<MidiMessage> queue;
 203     unsigned int queueLimit;
 204     unsigned char ignoreFlags;
 205     bool doInput;
 206     bool firstMessage;
 207     void *apiData;
 208     bool usingCallback;
 209     void *userCallback;
 210     void *userData;
 211
 212     // Default constructor.
 213     RtMidiInData()
 214       : queueLimit(1024), ignoreFlags(7), doInput(false), firstMessage(true),
 215         apiData(0), usingCallback(false), userCallback(0), userData(0) {}
 216   };
 217
 218  private:
 219
 220   void initialize( void );
 221   RtMidiInData inputData_;
 222
 223 };
 224
 225 /**********************************************************************/
 226 /*! \class RtMidiOut
 227     \brief A realtime MIDI output class.
 228
 229     This class provides a common, platform-independent API for MIDI
 230     output.  It allows one to probe available MIDI output ports, to
 231     connect to one such port, and to send MIDI bytes immediately over
 232     the connection.  Create multiple instances of this class to
 233     connect to more than one MIDI device at the same time.
 234
 235     by Gary P. Scavone, 2003-2004.
 236 */
 237 /**********************************************************************/
 238
 239 class RtMidiOut : public RtMidi
 240 {
 241  public:
 242
 243   //! Default constructor.
 244   /*!
 245       An exception will be thrown if a MIDI system initialization error occurs.
 246   */
 247   RtMidiOut();
 248
 249   //! The destructor closes any open MIDI connections.
 250   ~RtMidiOut();
 251
 252   //! Open a MIDI output connection.
 253   /*!
 254       An optional port number greater than 0 can be specified.
 255       Otherwise, the default or first port found is opened.  An
 256       exception is thrown if an error occurs while attempting to make
 257       the port connection.
 258   */
 259   void openPort( unsigned int portNumber = 0 );
 260
 261   //! Close an open MIDI connection (if one exists).
 262   void closePort();
 263
 264   //! Create a virtual output port to allow software connections (OS X and ALSA only).
 265   /*!
 266       This function creates a virtual MIDI output port to which other
 267       software applications can connect.  This type of functionality
 268       is currently only supported by the Macintosh OS-X and Linux ALSA
 269       APIs (the function does nothing with the other APIs).  An
 270       exception is thrown if an error occurs while attempting to create
 271       the virtual port.
 272   */
 273   void openVirtualPort();
 274
 275   //! Return the number of available MIDI output ports.
 276   unsigned int getPortCount();
 277
 278   //! Return a string identifier for the specified MIDI port type and number.
 279   /*!
 280       An exception is thrown if an invalid port specifier is provided.
 281   */
 282   std::string getPortName( unsigned int portNumber );
 283
 284   //! Immediately send a single message out an open MIDI output port.
 285   /*!
 286       An exception is thrown if an error occurs during output or an
 287       output connection was not previously established.
 288   */
 289   void sendMessage( std::vector<unsigned char> *message );
 290
 291  private:
 292
 293   void initialize( void );
 294 };
 295
 296 #endif