RtMidi.h

Go to the documentation of this file.

/**********************************************************************/
/**********************************************************************/
 
#ifndef RTMIDI_H
#define RTMIDI_H
 
#if defined _WIN32 || defined __CYGWIN__
  #if defined(RTMIDI_EXPORT)
    #define RTMIDI_DLL_PUBLIC __declspec(dllexport)
  #else
    #define RTMIDI_DLL_PUBLIC
  #endif
#else
  #if __GNUC__ >= 4
    #define RTMIDI_DLL_PUBLIC __attribute__( (visibility( "default" )) )
  #else
    #define RTMIDI_DLL_PUBLIC
  #endif
#endif
 
#define RTMIDI_VERSION_MAJOR 6
#define RTMIDI_VERSION_MINOR 1
#define RTMIDI_VERSION_PATCH 0
#define RTMIDI_VERSION_BETA  0
 
#define RTMIDI_TOSTRING2(n) #n
#define RTMIDI_TOSTRING(n) RTMIDI_TOSTRING2(n)
 
#if RTMIDI_VERSION_BETA > 0
    #define RTMIDI_VERSION RTMIDI_TOSTRING(RTMIDI_VERSION_MAJOR) \
                        "." RTMIDI_TOSTRING(RTMIDI_VERSION_MINOR) \
                        "." RTMIDI_TOSTRING(RTMIDI_VERSION_PATCH) \
                     "beta" RTMIDI_TOSTRING(RTMIDI_VERSION_BETA)
#else
    #define RTMIDI_VERSION RTMIDI_TOSTRING(RTMIDI_VERSION_MAJOR) \
                        "." RTMIDI_TOSTRING(RTMIDI_VERSION_MINOR) \
                        "." RTMIDI_TOSTRING(RTMIDI_VERSION_PATCH)
#endif
 
#include <atomic>
#include <exception>
#include <iostream>
#include <string>
#include <vector>
 
namespace rt {
namespace midi {
 
/************************************************************************/
/************************************************************************/
 
class RTMIDI_DLL_PUBLIC 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,        
    DRIVER_NOT_INSTALLED 
  };
 
  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_DLL_PUBLIC RtMidi
{
 public:
 
     RtMidi(RtMidi&& other) noexcept;
  enum Api {
    UNSPECIFIED,    
    MACOSX_CORE,    
    LINUX_ALSA,     
    UNIX_JACK,      
    WINDOWS_MM,     
    RTMIDI_DUMMY,   
    WEB_MIDI_API,   
    WINDOWS_UWP,    
    ANDROID_AMIDI,  
    WINDOWS_MIDI_SERVICES, 
    NUM_APIS        
  };
 
  struct RtMidiApiAvailability {
    bool available = true;      
    std::string message;        
    std::string installUrl;     
  };
 
 
  static RtMidiApiAvailability checkApiAvailability( RtMidi::Api api );
 
  static std::string getVersion( void ) throw();
 
 
  static void getCompiledApi( std::vector<RtMidi::Api> &apis ) throw();
 
 
  static std::string getApiName( RtMidi::Api api );
 
 
  static std::string getApiDisplayName( RtMidi::Api api );
 
 
  static RtMidi::Api getCompiledApiByName( const std::string &name );
 
  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;
 
  void setClientName( const std::string &clientName );
  void setPortName( const std::string &portName );
 
 
  virtual bool isPortOpen( void ) const = 0;
 
 
  bool supportsAutoReconnect( void ) const;
 
 
  void setAutoReconnect( bool enabled );
  bool isAutoReconnectEnabled( void ) const;
 
 
  virtual void setErrorCallback( RtMidiErrorCallback errorCallback = NULL, void *userData = 0 ) = 0;
 
 protected:
  RtMidi();
  virtual ~RtMidi();
  MidiApi *rtapi_;
 
  /* Make the class non-copyable */
  RtMidi(RtMidi& other) = delete;
  RtMidi& operator=(RtMidi& other) = delete;
};
 
/**********************************************************************/
/**********************************************************************/
 
// **************************************************************** //
//
// 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 RTMIDI_DLL_PUBLIC 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(RtMidiIn&& other) noexcept : RtMidi(std::move(other)) { }
 
  ~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 );
 
 
  virtual void setBufferSize( unsigned int size, unsigned int count );
 
 protected:
  void openMidiApi( RtMidi::Api api, const std::string &clientName, unsigned int queueSizeLimit );
};
 
/**********************************************************************/
/**********************************************************************/
 
class RTMIDI_DLL_PUBLIC RtMidiOut : public RtMidi
{
 public:
 
  RtMidiOut( RtMidi::Api api=UNSPECIFIED,
             const std::string& clientName = "RtMidi Output Client" );
 
  RtMidiOut(RtMidiOut&& other) noexcept : RtMidi(std::move(other)) { }
 
  ~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 RTMIDI_DLL_PUBLIC 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 void setClientName( const std::string &clientName ) = 0;
  virtual void setPortName( const std::string &portName ) = 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 );
 
 
  static void setDefaultErrorCallback( RtMidiErrorCallback errorCallback = NULL,
                                       void *userData = 0 );
 
  void error( RtMidiError::Type type, std::string errorString );
 
  // Non-virtual extensions leave existing backend vtable layouts unchanged.
  bool supportsAutoReconnect( void ) const;
  void setAutoReconnect( bool enabled );
  bool isAutoReconnectEnabled( void ) const;
 
protected:
  virtual void initialize( const std::string& clientName ) = 0;
 
  void *apiData_;
  bool connected_;
  std::string errorString_;
  RtMidiErrorCallback errorCallback_;
  bool firstErrorOccurred_;
  void *errorCallbackUserData_;
 
  // Static, so they add nothing to any object's layout.
  static RtMidiErrorCallback defaultErrorCallback_;
  static void *defaultErrorCallbackUserData_;
 
};
 
class RTMIDI_DLL_PUBLIC 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 );
  virtual double getMessage( std::vector<unsigned char> *message );
  virtual void setBufferSize( unsigned int size, unsigned int count );
 
  // 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) {}
  };
 
  // A single-producer, single-consumer ring buffer: the backend's input
  // thread is the only writer of \c back, and the thread calling
  // RtMidiIn::getMessage() is the only writer of \c front.  The indices are
  // atomic so that each side sees the other's completed writes: push()
  // releases \c back after the message is stored, pop() acquires it before
  // reading, and the same pairing applies to \c front.  Without that the
  // reader may observe a published index before the message it refers to.
  struct MidiQueue {
    std::atomic<unsigned int> front;
    std::atomic<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;
    // Read by the input thread while the user may change them; see
    // callUserCallback(), MidiInApi::setCallback() and cancelCallback().
    std::atomic<bool> usingCallback;
    std::atomic<RtMidiIn::RtMidiCallback> userCallback;
    std::atomic<void *> userData;
    bool continueSysex;
    unsigned int bufferSize;
    unsigned int bufferCount;
 
    // Default constructor.
    RtMidiInData()
      : ignoreFlags(7), doInput(false), firstMessage(true), apiData(0), usingCallback(false),
        userCallback(0), userData(0), continueSysex(false), bufferSize(1024), bufferCount(4) {}
 
    // Called by the backends' input threads: passes the message to the user
    // callback and returns true, or returns false if none is set (the message
    // then belongs in the queue). cancelCallback() only clears usingCallback,
    // so a thread that has just seen it set still reads a valid callback.
    bool callUserCallback( double timeStamp, std::vector<unsigned char> *bytes )
    {
      if ( !usingCallback.load( std::memory_order_acquire ) ) return false;
      RtMidiIn::RtMidiCallback callback = userCallback.load( std::memory_order_relaxed );
      callback( timeStamp, bytes, userData.load( std::memory_order_relaxed ) );
      return true;
    }
  };
 
 protected:
  RtMidiInData inputData_;
};
 
class RTMIDI_DLL_PUBLIC 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 bool RtMidi :: supportsAutoReconnect( void ) const { return rtapi_->supportsAutoReconnect(); }
inline void RtMidi :: setAutoReconnect( bool enabled ) { rtapi_->setAutoReconnect( enabled ); }
inline bool RtMidi :: isAutoReconnectEnabled( void ) const { return rtapi_->isAutoReconnectEnabled(); }
 
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 ) { static_cast<MidiInApi *>(rtapi_)->setCallback( callback, userData ); }
inline void RtMidiIn :: cancelCallback( void ) { static_cast<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 ) { static_cast<MidiInApi *>(rtapi_)->ignoreTypes( midiSysex, midiTime, midiSense ); }
inline double RtMidiIn :: getMessage( std::vector<unsigned char> *message ) { return static_cast<MidiInApi *>(rtapi_)->getMessage( message ); }
inline void RtMidiIn :: setErrorCallback( RtMidiErrorCallback errorCallback, void *userData ) { rtapi_->setErrorCallback(errorCallback, userData); }
inline void RtMidiIn :: setBufferSize( unsigned int size, unsigned int count ) { static_cast<MidiInApi *>(rtapi_)->setBufferSize(size, count); }
 
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 ) { static_cast<MidiOutApi *>(rtapi_)->sendMessage( &message->at(0), message->size() ); }
inline void RtMidiOut :: sendMessage( const unsigned char *message, size_t size ) { static_cast<MidiOutApi *>(rtapi_)->sendMessage( message, size ); }
inline void RtMidiOut :: setErrorCallback( RtMidiErrorCallback errorCallback, void *userData ) { rtapi_->setErrorCallback(errorCallback, userData); }
 
} // namespace midi
} // namespace rt
 
#endif
 
#ifndef RTMIDI_USE_NAMESPACE
using namespace rt::midi;
#endif