RtMidi.h

Go to the documentation of this file.

/**********************************************************************/
/**********************************************************************/
 
#ifndef RTMIDI_H
#define RTMIDI_H
 
#define RTMIDI_VERSION "3.0.0"
 
#include <exception>
#include <iostream>
#include <string>
#include <vector>
 
/************************************************************************/
/************************************************************************/
 
class RtMidiError : public std::exception
{
 public:
  enum Type {
    WARNING,           
    DEBUG_WARNING,     
    UNSPECIFIED,       
    NO_DEVICES_FOUND,  
    INVALID_DEVICE,    
    MEMORY_ERROR,      
    INVALID_PARAMETER, 
    INVALID_USE,       
    DRIVER_ERROR,      
    SYSTEM_ERROR,      
    THREAD_ERROR       
  };
 
  RtMidiError( const std::string& message, Type type = RtMidiError::UNSPECIFIED ) throw() : message_(message), type_(type) {}
 
  virtual ~RtMidiError( void ) throw() {}
 
  virtual void printMessage( void ) const throw() { std::cerr << '\n' << message_ << "\n\n"; }
 
  virtual const Type& getType(void) const throw() { return type_; }
 
  virtual const std::string& getMessage(void) const throw() { return message_; }
 
  virtual const char* what( void ) const throw() { return message_.c_str(); }
 
 protected:
  std::string message_;
  Type type_;
};
 
 
typedef void (*RtMidiErrorCallback)( RtMidiError::Type type, const std::string &errorText, void *userData );
 
class MidiApi;
 
class RtMidi
{
 public:
 
  enum Api {
    UNSPECIFIED,    
    MACOSX_CORE,    
    LINUX_ALSA,     
    UNIX_JACK,      
    WINDOWS_MM,     
    RTMIDI_DUMMY    
  };
 
  static std::string getVersion( void ) throw();
 
 
  static void getCompiledApi( std::vector<RtMidi::Api> &apis ) throw();
 
  virtual void openPort( unsigned int portNumber = 0, const std::string &portName = std::string( "RtMidi" ) ) = 0;
 
  virtual void openVirtualPort( const std::string &portName = std::string( "RtMidi" ) ) = 0;
 
  virtual unsigned int getPortCount() = 0;
 
  virtual std::string getPortName( unsigned int portNumber = 0 ) = 0;
 
  virtual void closePort( void ) = 0;
 
 
  virtual bool isPortOpen( void ) const = 0;
 
 
  virtual void setErrorCallback( RtMidiErrorCallback errorCallback = NULL, void *userData = 0 ) = 0;
 
 protected:
 
  RtMidi();
  virtual ~RtMidi();
 
  MidiApi *rtapi_;
};
 
/**********************************************************************/
/**********************************************************************/
 
// **************************************************************** //
//
// RtMidiIn and RtMidiOut class declarations.
//
// RtMidiIn / RtMidiOut are "controllers" used to select an available
// MIDI input or output interface.  They present common APIs for the
// user to call but all functionality is implemented by the classes
// MidiInApi, MidiOutApi and their subclasses.  RtMidiIn and RtMidiOut
// each create an instance of a MidiInApi or MidiOutApi subclass based
// on the user's API choice.  If no choice is made, they attempt to
// make a "logical" API selection.
//
// **************************************************************** //
 
class RtMidiIn : public RtMidi
{
 public:
 
  typedef void (*RtMidiCallback)( double timeStamp, std::vector<unsigned char> *message, void *userData);
 
 
  RtMidiIn( RtMidi::Api api=UNSPECIFIED,
            const std::string& clientName = "RtMidi Input Client",
            unsigned int queueSizeLimit = 100 );
 
  ~RtMidiIn ( void ) throw();
 
  RtMidi::Api getCurrentApi( void ) throw();
 
 
  void openPort( unsigned int portNumber = 0, const std::string &portName = std::string( "RtMidi Input" ) );
 
 
  void openVirtualPort( const std::string &portName = std::string( "RtMidi Input" ) );
 
 
  void setCallback( RtMidiCallback callback, void *userData = 0 );
 
 
  void cancelCallback();
 
  void closePort( void );
 
 
  virtual bool isPortOpen() const;
 
 
  unsigned int getPortCount();
 
 
  std::string getPortName( unsigned int portNumber = 0 );
 
 
  void ignoreTypes( bool midiSysex = true, bool midiTime = true, bool midiSense = true );
 
 
  double getMessage( std::vector<unsigned char> *message );
 
 
  virtual void setErrorCallback( RtMidiErrorCallback errorCallback = NULL, void *userData = 0 );
 
 protected:
  void openMidiApi( RtMidi::Api api, const std::string &clientName, unsigned int queueSizeLimit );
 
};
 
/**********************************************************************/
/**********************************************************************/
 
class RtMidiOut : public RtMidi
{
 public:
 
 
  RtMidiOut( RtMidi::Api api=UNSPECIFIED,
             const std::string& clientName = "RtMidi Output Client" );
 
  ~RtMidiOut( void ) throw();
 
  RtMidi::Api getCurrentApi( void ) throw();
 
 
  void openPort( unsigned int portNumber = 0, const std::string &portName = std::string( "RtMidi Output" ) );
 
  void closePort( void );
 
 
  virtual bool isPortOpen() const;
 
 
  void openVirtualPort( const std::string &portName = std::string( "RtMidi Output" ) );
 
  unsigned int getPortCount( void );
 
 
  std::string getPortName( unsigned int portNumber = 0 );
 
 
  void sendMessage( const std::vector<unsigned char> *message );
 
 
  void sendMessage( const unsigned char *message, size_t size );
 
 
  virtual void setErrorCallback( RtMidiErrorCallback errorCallback = NULL, void *userData = 0 );
 
 protected:
  void openMidiApi( RtMidi::Api api, const std::string &clientName );
};
 
 
// **************************************************************** //
//
// MidiInApi / MidiOutApi class declarations.
//
// Subclasses of MidiInApi and MidiOutApi contain all API- and
// OS-specific code necessary to fully implement the RtMidi API.
//
// Note that MidiInApi and MidiOutApi are abstract base classes and
// cannot be explicitly instantiated.  RtMidiIn and RtMidiOut will
// create instances of a MidiInApi or MidiOutApi subclass.
//
// **************************************************************** //
 
class MidiApi
{
 public:
 
  MidiApi();
  virtual ~MidiApi();
  virtual RtMidi::Api getCurrentApi( void ) = 0;
  virtual void openPort( unsigned int portNumber, const std::string &portName ) = 0;
  virtual void openVirtualPort( const std::string &portName ) = 0;
  virtual void closePort( void ) = 0;
 
  virtual unsigned int getPortCount( void ) = 0;
  virtual std::string getPortName( unsigned int portNumber ) = 0;
 
  inline bool isPortOpen() const { return connected_; }
  void setErrorCallback( RtMidiErrorCallback errorCallback, void *userData );
 
  void error( RtMidiError::Type type, std::string errorString );
 
protected:
  virtual void initialize( const std::string& clientName ) = 0;
 
  void *apiData_;
  bool connected_;
  std::string errorString_;
  RtMidiErrorCallback errorCallback_;
  bool firstErrorOccurred_;
  void *errorCallbackUserData_;
};
 
class MidiInApi : public MidiApi
{
 public:
 
  MidiInApi( unsigned int queueSizeLimit );
  virtual ~MidiInApi( void );
  void setCallback( RtMidiIn::RtMidiCallback callback, void *userData );
  void cancelCallback( void );
  virtual void ignoreTypes( bool midiSysex, bool midiTime, bool midiSense );
  double getMessage( std::vector<unsigned char> *message );
 
  // A MIDI structure used internally by the class to store incoming
  // messages.  Each message represents one and only one MIDI message.
  struct MidiMessage { 
    std::vector<unsigned char> bytes; 
 
    double timeStamp;
 
    // Default constructor.
  MidiMessage()
  :bytes(0), timeStamp(0.0) {}
  };
 
  struct MidiQueue {
    unsigned int front;
    unsigned int back;
    unsigned int ringSize;
    MidiMessage *ring;
 
    // Default constructor.
  MidiQueue()
  :front(0), back(0), ringSize(0), ring(0) {}
    bool push(const MidiMessage&);
    bool pop(std::vector<unsigned char>*, double*);
    unsigned int size(unsigned int *back=0,
                      unsigned int *front=0);
  };
 
  // The RtMidiInData structure is used to pass private class data to
  // the MIDI input handling function or thread.
  struct RtMidiInData {
    MidiQueue queue;
    MidiMessage message;
    unsigned char ignoreFlags;
    bool doInput;
    bool firstMessage;
    void *apiData;
    bool usingCallback;
    RtMidiIn::RtMidiCallback userCallback;
    void *userData;
    bool continueSysex;
 
    // Default constructor.
  RtMidiInData()
  : ignoreFlags(7), doInput(false), firstMessage(true),
      apiData(0), usingCallback(false), userCallback(0), userData(0),
      continueSysex(false) {}
  };
 
 protected:
  RtMidiInData inputData_;
};
 
class MidiOutApi : public MidiApi
{
 public:
 
  MidiOutApi( void );
  virtual ~MidiOutApi( void );
  virtual void sendMessage( const unsigned char *message, size_t size ) = 0;
};
 
// **************************************************************** //
//
// Inline RtMidiIn and RtMidiOut definitions.
//
// **************************************************************** //
 
inline RtMidi::Api RtMidiIn :: getCurrentApi( void ) throw() { return rtapi_->getCurrentApi(); }
inline void RtMidiIn :: openPort( unsigned int portNumber, const std::string &portName ) { rtapi_->openPort( portNumber, portName ); }
inline void RtMidiIn :: openVirtualPort( const std::string &portName ) { rtapi_->openVirtualPort( portName ); }
inline void RtMidiIn :: closePort( void ) { rtapi_->closePort(); }
inline bool RtMidiIn :: isPortOpen() const { return rtapi_->isPortOpen(); }
inline void RtMidiIn :: setCallback( RtMidiCallback callback, void *userData ) { ((MidiInApi *)rtapi_)->setCallback( callback, userData ); }
inline void RtMidiIn :: cancelCallback( void ) { ((MidiInApi *)rtapi_)->cancelCallback(); }
inline unsigned int RtMidiIn :: getPortCount( void ) { return rtapi_->getPortCount(); }
inline std::string RtMidiIn :: getPortName( unsigned int portNumber ) { return rtapi_->getPortName( portNumber ); }
inline void RtMidiIn :: ignoreTypes( bool midiSysex, bool midiTime, bool midiSense ) { ((MidiInApi *)rtapi_)->ignoreTypes( midiSysex, midiTime, midiSense ); }
inline double RtMidiIn :: getMessage( std::vector<unsigned char> *message ) { return ((MidiInApi *)rtapi_)->getMessage( message ); }
inline void RtMidiIn :: setErrorCallback( RtMidiErrorCallback errorCallback, void *userData ) { rtapi_->setErrorCallback(errorCallback, userData); }
 
inline RtMidi::Api RtMidiOut :: getCurrentApi( void ) throw() { return rtapi_->getCurrentApi(); }
inline void RtMidiOut :: openPort( unsigned int portNumber, const std::string &portName ) { rtapi_->openPort( portNumber, portName ); }
inline void RtMidiOut :: openVirtualPort( const std::string &portName ) { rtapi_->openVirtualPort( portName ); }
inline void RtMidiOut :: closePort( void ) { rtapi_->closePort(); }
inline bool RtMidiOut :: isPortOpen() const { return rtapi_->isPortOpen(); }
inline unsigned int RtMidiOut :: getPortCount( void ) { return rtapi_->getPortCount(); }
inline std::string RtMidiOut :: getPortName( unsigned int portNumber ) { return rtapi_->getPortName( portNumber ); }
inline void RtMidiOut :: sendMessage( const std::vector<unsigned char> *message ) { ((MidiOutApi *)rtapi_)->sendMessage( &message->at(0), message->size() ); }
inline void RtMidiOut :: sendMessage( const unsigned char *message, size_t size ) { ((MidiOutApi *)rtapi_)->sendMessage( message, size ); }
inline void RtMidiOut :: setErrorCallback( RtMidiErrorCallback errorCallback, void *userData ) { rtapi_->setErrorCallback(errorCallback, userData); }
 
// **************************************************************** //
//
// MidiInApi and MidiOutApi subclass prototypes.
//
// **************************************************************** //
 
#if !defined(__LINUX_ALSA__) && !defined(__UNIX_JACK__) && !defined(__MACOSX_CORE__) && !defined(__WINDOWS_MM__)
  #define __RTMIDI_DUMMY__
#endif
 
#if defined(__MACOSX_CORE__)
 
class MidiInCore: public MidiInApi
{
 public:
  MidiInCore( const std::string &clientName, unsigned int queueSizeLimit );
  ~MidiInCore( void );
  RtMidi::Api getCurrentApi( void ) { return RtMidi::MACOSX_CORE; };
  void openPort( unsigned int portNumber, const std::string &portName );
  void openVirtualPort( const std::string &portName );
  void closePort( void );
  unsigned int getPortCount( void );
  std::string getPortName( unsigned int portNumber );
 
 protected:
  void initialize( const std::string& clientName );
};
 
class MidiOutCore: public MidiOutApi
{
 public:
  MidiOutCore( const std::string &clientName );
  ~MidiOutCore( void );
  RtMidi::Api getCurrentApi( void ) { return RtMidi::MACOSX_CORE; };
  void openPort( unsigned int portNumber, const std::string &portName );
  void openVirtualPort( const std::string &portName );
  void closePort( void );
  unsigned int getPortCount( void );
  std::string getPortName( unsigned int portNumber );
  void sendMessage( const unsigned char *message, size_t size );
 
 protected:
  void initialize( const std::string& clientName );
};
 
#endif
 
#if defined(__UNIX_JACK__)
 
class MidiInJack: public MidiInApi
{
 public:
  MidiInJack( const std::string &clientName, unsigned int queueSizeLimit );
  ~MidiInJack( void );
  RtMidi::Api getCurrentApi( void ) { return RtMidi::UNIX_JACK; };
  void openPort( unsigned int portNumber, const std::string &portName );
  void openVirtualPort( const std::string &portName );
  void closePort( void );
  unsigned int getPortCount( void );
  std::string getPortName( unsigned int portNumber );
 
 protected:
  std::string clientName;
 
  void connect( void );
  void initialize( const std::string& clientName );
};
 
class MidiOutJack: public MidiOutApi
{
 public:
  MidiOutJack( const std::string &clientName );
  ~MidiOutJack( void );
  RtMidi::Api getCurrentApi( void ) { return RtMidi::UNIX_JACK; };
  void openPort( unsigned int portNumber, const std::string &portName );
  void openVirtualPort( const std::string &portName );
  void closePort( void );
  unsigned int getPortCount( void );
  std::string getPortName( unsigned int portNumber );
  void sendMessage( const unsigned char *message, size_t size );
 
 protected:
  std::string clientName;
 
  void connect( void );
  void initialize( const std::string& clientName );
};
 
#endif
 
#if defined(__LINUX_ALSA__)
 
class MidiInAlsa: public MidiInApi
{
 public:
  MidiInAlsa( const std::string &clientName, unsigned int queueSizeLimit );
  ~MidiInAlsa( void );
  RtMidi::Api getCurrentApi( void ) { return RtMidi::LINUX_ALSA; };
  void openPort( unsigned int portNumber, const std::string &portName );
  void openVirtualPort( const std::string &portName );
  void closePort( void );
  unsigned int getPortCount( void );
  std::string getPortName( unsigned int portNumber );
 
 protected:
  void initialize( const std::string& clientName );
};
 
class MidiOutAlsa: public MidiOutApi
{
 public:
  MidiOutAlsa( const std::string &clientName );
  ~MidiOutAlsa( void );
  RtMidi::Api getCurrentApi( void ) { return RtMidi::LINUX_ALSA; };
  void openPort( unsigned int portNumber, const std::string &portName );
  void openVirtualPort( const std::string &portName );
  void closePort( void );
  unsigned int getPortCount( void );
  std::string getPortName( unsigned int portNumber );
  void sendMessage( const unsigned char *message, size_t size );
 
 protected:
  void initialize( const std::string& clientName );
};
 
#endif
 
#if defined(__WINDOWS_MM__)
 
class MidiInWinMM: public MidiInApi
{
 public:
  MidiInWinMM( const std::string &clientName, unsigned int queueSizeLimit );
  ~MidiInWinMM( void );
  RtMidi::Api getCurrentApi( void ) { return RtMidi::WINDOWS_MM; };
  void openPort( unsigned int portNumber, const std::string &portName );
  void openVirtualPort( const std::string &portName );
  void closePort( void );
  unsigned int getPortCount( void );
  std::string getPortName( unsigned int portNumber );
 
 protected:
  void initialize( const std::string& clientName );
};
 
class MidiOutWinMM: public MidiOutApi
{
 public:
  MidiOutWinMM( const std::string &clientName );
  ~MidiOutWinMM( void );
  RtMidi::Api getCurrentApi( void ) { return RtMidi::WINDOWS_MM; };
  void openPort( unsigned int portNumber, const std::string &portName );
  void openVirtualPort( const std::string &portName );
  void closePort( void );
  unsigned int getPortCount( void );
  std::string getPortName( unsigned int portNumber );
  void sendMessage( const unsigned char *message, size_t size );
 
 protected:
  void initialize( const std::string& clientName );
};
 
#endif
 
#if defined(__RTMIDI_DUMMY__)
 
class MidiInDummy: public MidiInApi
{
 public:
 MidiInDummy( const std::string &/*clientName*/, unsigned int queueSizeLimit ) : MidiInApi( queueSizeLimit ) { errorString_ = "MidiInDummy: This class provides no functionality."; error( RtMidiError::WARNING, errorString_ ); }
  RtMidi::Api getCurrentApi( void ) { return RtMidi::RTMIDI_DUMMY; }
  void openPort( unsigned int /*portNumber*/, const std::string &/*portName*/ ) {}
  void openVirtualPort( const std::string &/*portName*/ ) {}
  void closePort( void ) {}
  unsigned int getPortCount( void ) { return 0; }
  std::string getPortName( unsigned int /*portNumber*/ ) { return ""; }
 
 protected:
  void initialize( const std::string& /*clientName*/ ) {}
};
 
class MidiOutDummy: public MidiOutApi
{
 public:
  MidiOutDummy( const std::string &/*clientName*/ ) { errorString_ = "MidiOutDummy: This class provides no functionality."; error( RtMidiError::WARNING, errorString_ ); }
  RtMidi::Api getCurrentApi( void ) { return RtMidi::RTMIDI_DUMMY; }
  void openPort( unsigned int /*portNumber*/, const std::string &/*portName*/ ) {}
  void openVirtualPort( const std::string &/*portName*/ ) {}
  void closePort( void ) {}
  unsigned int getPortCount( void ) { return 0; }
  std::string getPortName( unsigned int /*portNumber*/ ) { return ""; }
  void sendMessage( const unsigned char * /*message*/, size_t /*size*/ ) {}
 
 protected:
  void initialize( const std::string& /*clientName*/ ) {}
};
 
#endif
 
#endif