1 /************************************************************************/ 2 /*! \defgroup C-interface 3 @{ 4 5 \brief C interface to realtime MIDI input/output C++ classes. 6 7 RtMidi offers a C-style interface, principally for use in binding 8 RtMidi to other programming languages. All structs, enums, and 9 functions listed here have direct analogs (and simply call to) 10 items in the C++ RtMidi class and its supporting classes and 11 types 12 */ 13 /************************************************************************/ 14 15 /*! 16 \file rtmidi_c.h 17 */ 18 19 #include <stdbool.h> 20 #include <stddef.h> 21 #ifndef RTMIDI_C_H 22 #define RTMIDI_C_H 23 24 #if defined(RTMIDI_EXPORT) 25 #if defined _WIN32 || defined __CYGWIN__ 26 #define RTMIDIAPI __declspec(dllexport) 27 #else 28 #define RTMIDIAPI __attribute__((visibility("default"))) 29 #endif 30 #else 31 #define RTMIDIAPI //__declspec(dllimport) 32 #endif 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 //! \brief Wraps an RtMidi object for C function return statuses. 39 struct RtMidiWrapper { 40 //! The wrapped RtMidi object. 41 void* ptr; 42 void* data; 43 44 //! True when the last function call was OK. 45 bool ok; 46 47 //! If an error occured (ok != true), set to an error message. 48 const char* msg; 49 }; 50 51 //! \brief Typedef for a generic RtMidi pointer. 52 typedef struct RtMidiWrapper* RtMidiPtr; 53 54 //! \brief Typedef for a generic RtMidiIn pointer. 55 typedef struct RtMidiWrapper* RtMidiInPtr; 56 57 //! \brief Typedef for a generic RtMidiOut pointer. 58 typedef struct RtMidiWrapper* RtMidiOutPtr; 59 60 //! \brief MIDI API specifier arguments. See \ref RtMidi::Api. 61 enum RtMidiApi { 62 RTMIDI_API_UNSPECIFIED, /*!< Search for a working compiled API. */ 63 RTMIDI_API_MACOSX_CORE, /*!< Macintosh OS-X CoreMIDI API. */ 64 RTMIDI_API_LINUX_ALSA, /*!< The Advanced Linux Sound Architecture API. */ 65 RTMIDI_API_UNIX_JACK, /*!< The Jack Low-Latency MIDI Server API. */ 66 RTMIDI_API_WINDOWS_MM, /*!< The Microsoft Multimedia MIDI API. */ 67 RTMIDI_API_RTMIDI_DUMMY, /*!< A compilable but non-functional API. */ 68 RTMIDI_API_NUM /*!< Number of values in this enum. */ 69 }; 70 71 //! \brief Defined RtMidiError types. See \ref RtMidiError::Type. 72 enum RtMidiErrorType { 73 RTMIDI_ERROR_WARNING, /*!< A non-critical error. */ 74 RTMIDI_ERROR_DEBUG_WARNING, /*!< A non-critical error which might be useful for debugging. */ 75 RTMIDI_ERROR_UNSPECIFIED, /*!< The default, unspecified error type. */ 76 RTMIDI_ERROR_NO_DEVICES_FOUND, /*!< No devices found on system. */ 77 RTMIDI_ERROR_INVALID_DEVICE, /*!< An invalid device ID was specified. */ 78 RTMIDI_ERROR_MEMORY_ERROR, /*!< An error occured during memory allocation. */ 79 RTMIDI_ERROR_INVALID_PARAMETER, /*!< An invalid parameter was specified to a function. */ 80 RTMIDI_ERROR_INVALID_USE, /*!< The function was called incorrectly. */ 81 RTMIDI_ERROR_DRIVER_ERROR, /*!< A system driver error occured. */ 82 RTMIDI_ERROR_SYSTEM_ERROR, /*!< A system error occured. */ 83 RTMIDI_ERROR_THREAD_ERROR /*!< A thread error occured. */ 84 }; 85 86 /*! \brief The type of a RtMidi callback function. 87 * 88 * \param timeStamp The time at which the message has been received. 89 * \param message The midi message. 90 * \param userData Additional user data for the callback. 91 * 92 * See \ref RtMidiIn::RtMidiCallback. 93 */ 94 typedef void(* RtMidiCCallback) (double timeStamp, const unsigned char* message, 95 size_t messageSize, void *userData); 96 97 98 /* RtMidi API */ 99 100 /*! \brief Determine the available compiled MIDI APIs. 101 * 102 * If the given `apis` parameter is null, returns the number of available APIs. 103 * Otherwise, fill the given apis array with the RtMidi::Api values. 104 * 105 * \param apis An array or a null value. 106 * \param apis_size Number of elements pointed to by apis 107 * \return number of items needed for apis array if apis==NULL, or 108 * number of items written to apis array otherwise. A negative 109 * return value indicates an error. 110 * 111 * See \ref RtMidi::getCompiledApi(). 112 */ 113 RTMIDIAPI int rtmidi_get_compiled_api (enum RtMidiApi *apis, unsigned int apis_size); 114 115 //! \brief Return the name of a specified compiled MIDI API. 116 //! See \ref RtMidi::getApiName(). 117 RTMIDIAPI const char *rtmidi_api_name(enum RtMidiApi api); 118 119 //! \brief Return the display name of a specified compiled MIDI API. 120 //! See \ref RtMidi::getApiDisplayName(). 121 RTMIDIAPI const char *rtmidi_api_display_name(enum RtMidiApi api); 122 123 //! \brief Return the compiled MIDI API having the given name. 124 //! See \ref RtMidi::getCompiledApiByName(). 125 RTMIDIAPI enum RtMidiApi rtmidi_compiled_api_by_name(const char *name); 126 127 //! \internal Report an error. 128 RTMIDIAPI void rtmidi_error (enum RtMidiErrorType type, const char* errorString); 129 130 /*! \brief Open a MIDI port. 131 * 132 * \param port Must be greater than 0 133 * \param portName Name for the application port. 134 * 135 * See RtMidi::openPort(). 136 */ 137 RTMIDIAPI void rtmidi_open_port (RtMidiPtr device, unsigned int portNumber, const char *portName); 138 139 /*! \brief Creates a virtual MIDI port to which other software applications can 140 * connect. 141 * 142 * \param portName Name for the application port. 143 * 144 * See RtMidi::openVirtualPort(). 145 */ 146 RTMIDIAPI void rtmidi_open_virtual_port (RtMidiPtr device, const char *portName); 147 148 /*! \brief Close a MIDI connection. 149 * See RtMidi::closePort(). 150 */ 151 RTMIDIAPI void rtmidi_close_port (RtMidiPtr device); 152 153 /*! \brief Return the number of available MIDI ports. 154 * See RtMidi::getPortCount(). 155 */ 156 RTMIDIAPI unsigned int rtmidi_get_port_count (RtMidiPtr device); 157 158 /*! \brief Return a string identifier for the specified MIDI input port number. 159 * See RtMidi::getPortName(). 160 */ 161 RTMIDIAPI const char* rtmidi_get_port_name (RtMidiPtr device, unsigned int portNumber); 162 163 /* RtMidiIn API */ 164 165 //! \brief Create a default RtMidiInPtr value, with no initialization. 166 RTMIDIAPI RtMidiInPtr rtmidi_in_create_default (void); 167 168 /*! \brief Create a RtMidiInPtr value, with given api, clientName and queueSizeLimit. 169 * 170 * \param api An optional API id can be specified. 171 * \param clientName An optional client name can be specified. This 172 * will be used to group the ports that are created 173 * by the application. 174 * \param queueSizeLimit An optional size of the MIDI input queue can be 175 * specified. 176 * 177 * See RtMidiIn::RtMidiIn(). 178 */ 179 RTMIDIAPI RtMidiInPtr rtmidi_in_create (enum RtMidiApi api, const char *clientName, unsigned int queueSizeLimit); 180 181 //! \brief Free the given RtMidiInPtr. 182 RTMIDIAPI void rtmidi_in_free (RtMidiInPtr device); 183 184 //! \brief Returns the MIDI API specifier for the given instance of RtMidiIn. 185 //! See \ref RtMidiIn::getCurrentApi(). 186 RTMIDIAPI enum RtMidiApi rtmidi_in_get_current_api (RtMidiPtr device); 187 188 //! \brief Set a callback function to be invoked for incoming MIDI messages. 189 //! See \ref RtMidiIn::setCallback(). 190 RTMIDIAPI void rtmidi_in_set_callback (RtMidiInPtr device, RtMidiCCallback callback, void *userData); 191 192 //! \brief Cancel use of the current callback function (if one exists). 193 //! See \ref RtMidiIn::cancelCallback(). 194 RTMIDIAPI void rtmidi_in_cancel_callback (RtMidiInPtr device); 195 196 //! \brief Specify whether certain MIDI message types should be queued or ignored during input. 197 //! See \ref RtMidiIn::ignoreTypes(). 198 RTMIDIAPI void rtmidi_in_ignore_types (RtMidiInPtr device, bool midiSysex, bool midiTime, bool midiSense); 199 200 /*! Fill the user-provided array with the data bytes for the next available 201 * MIDI message in the input queue and return the event delta-time in seconds. 202 * 203 * \param message Must point to a char* that is already allocated. 204 * SYSEX messages maximum size being 1024, a statically 205 * allocated array could 206 * be sufficient. 207 * \param size Is used to return the size of the message obtained. 208 * 209 * See RtMidiIn::getMessage(). 210 */ 211 RTMIDIAPI double rtmidi_in_get_message (RtMidiInPtr device, unsigned char *message, size_t *size); 212 213 /* RtMidiOut API */ 214 215 //! \brief Create a default RtMidiInPtr value, with no initialization. 216 RTMIDIAPI RtMidiOutPtr rtmidi_out_create_default (void); 217 218 /*! \brief Create a RtMidiOutPtr value, with given and clientName. 219 * 220 * \param api An optional API id can be specified. 221 * \param clientName An optional client name can be specified. This 222 * will be used to group the ports that are created 223 * by the application. 224 * 225 * See RtMidiOut::RtMidiOut(). 226 */ 227 RTMIDIAPI RtMidiOutPtr rtmidi_out_create (enum RtMidiApi api, const char *clientName); 228 229 //! \brief Free the given RtMidiOutPtr. 230 RTMIDIAPI void rtmidi_out_free (RtMidiOutPtr device); 231 232 //! \brief Returns the MIDI API specifier for the given instance of RtMidiOut. 233 //! See \ref RtMidiOut::getCurrentApi(). 234 RTMIDIAPI enum RtMidiApi rtmidi_out_get_current_api (RtMidiPtr device); 235 236 //! \brief Immediately send a single message out an open MIDI output port. 237 //! See \ref RtMidiOut::sendMessage(). 238 RTMIDIAPI int rtmidi_out_send_message (RtMidiOutPtr device, const unsigned char *message, int length); 239 240 241 #ifdef __cplusplus 242 } 243 #endif 244 #endif 245 246 /*! }@ */ 247