File: rtmidi_c.h

package info (click to toggle)
rtmidi 4.0.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye
  • size: 604 kB
  • sloc: cpp: 3,827; sh: 104; makefile: 88
file content (246 lines) | stat: -rw-r--r-- 9,194 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
/************************************************************************/
/*! \defgroup C-interface
    @{

    \brief C interface to realtime MIDI input/output C++ classes.

    RtMidi offers a C-style interface, principally for use in binding
    RtMidi to other programming languages.  All structs, enums, and
    functions listed here have direct analogs (and simply call to)
    items in the C++ RtMidi class and its supporting classes and
    types
*/
/************************************************************************/

/*!
  \file rtmidi_c.h
 */

#include <stdbool.h>
#include <stddef.h>
#ifndef RTMIDI_C_H
#define RTMIDI_C_H

#if defined(RTMIDI_EXPORT)
#if defined _WIN32 || defined __CYGWIN__
#define RTMIDIAPI __declspec(dllexport)
#else
#define RTMIDIAPI __attribute__((visibility("default")))
#endif
#else
#define RTMIDIAPI //__declspec(dllimport)
#endif

#ifdef __cplusplus
extern "C" {
#endif

//! \brief Wraps an RtMidi object for C function return statuses.
struct RtMidiWrapper {
    //! The wrapped RtMidi object.
    void* ptr;
    void* data;

    //! True when the last function call was OK. 
    bool  ok;

    //! If an error occured (ok != true), set to an error message.
    const char* msg;
};

//! \brief Typedef for a generic RtMidi pointer.
typedef struct RtMidiWrapper* RtMidiPtr;

//! \brief Typedef for a generic RtMidiIn pointer.
typedef struct RtMidiWrapper* RtMidiInPtr;

//! \brief Typedef for a generic RtMidiOut pointer.
typedef struct RtMidiWrapper* RtMidiOutPtr;

//! \brief MIDI API specifier arguments.  See \ref RtMidi::Api.
enum RtMidiApi {
    RTMIDI_API_UNSPECIFIED,    /*!< Search for a working compiled API. */
    RTMIDI_API_MACOSX_CORE,    /*!< Macintosh OS-X CoreMIDI API. */
    RTMIDI_API_LINUX_ALSA,     /*!< The Advanced Linux Sound Architecture API. */
    RTMIDI_API_UNIX_JACK,      /*!< The Jack Low-Latency MIDI Server API. */
    RTMIDI_API_WINDOWS_MM,     /*!< The Microsoft Multimedia MIDI API. */
    RTMIDI_API_RTMIDI_DUMMY,   /*!< A compilable but non-functional API. */
    RTMIDI_API_NUM             /*!< Number of values in this enum. */
};

//! \brief Defined RtMidiError types. See \ref RtMidiError::Type.
enum RtMidiErrorType {
  RTMIDI_ERROR_WARNING,           /*!< A non-critical error. */
  RTMIDI_ERROR_DEBUG_WARNING,     /*!< A non-critical error which might be useful for debugging. */
  RTMIDI_ERROR_UNSPECIFIED,       /*!< The default, unspecified error type. */
  RTMIDI_ERROR_NO_DEVICES_FOUND,  /*!< No devices found on system. */
  RTMIDI_ERROR_INVALID_DEVICE,    /*!< An invalid device ID was specified. */
  RTMIDI_ERROR_MEMORY_ERROR,      /*!< An error occured during memory allocation. */
  RTMIDI_ERROR_INVALID_PARAMETER, /*!< An invalid parameter was specified to a function. */
  RTMIDI_ERROR_INVALID_USE,       /*!< The function was called incorrectly. */
  RTMIDI_ERROR_DRIVER_ERROR,      /*!< A system driver error occured. */
  RTMIDI_ERROR_SYSTEM_ERROR,      /*!< A system error occured. */
  RTMIDI_ERROR_THREAD_ERROR       /*!< A thread error occured. */
};

/*! \brief The type of a RtMidi callback function.
 *
 * \param timeStamp   The time at which the message has been received.
 * \param message     The midi message.
 * \param userData    Additional user data for the callback.
 *
 * See \ref RtMidiIn::RtMidiCallback.
 */
typedef void(* RtMidiCCallback) (double timeStamp, const unsigned char* message,
                                 size_t messageSize, void *userData);


/* RtMidi API */

/*! \brief Determine the available compiled MIDI APIs.
 *
 * If the given `apis` parameter is null, returns the number of available APIs.
 * Otherwise, fill the given apis array with the RtMidi::Api values.
 *
 * \param apis  An array or a null value.
 * \param apis_size  Number of elements pointed to by apis
 * \return number of items needed for apis array if apis==NULL, or
 *         number of items written to apis array otherwise.  A negative
 *         return value indicates an error.
 *
 * See \ref RtMidi::getCompiledApi().
*/
RTMIDIAPI int rtmidi_get_compiled_api (enum RtMidiApi *apis, unsigned int apis_size);

//! \brief Return the name of a specified compiled MIDI API.
//! See \ref RtMidi::getApiName().
RTMIDIAPI const char *rtmidi_api_name(enum RtMidiApi api);

//! \brief Return the display name of a specified compiled MIDI API.
//! See \ref RtMidi::getApiDisplayName().
RTMIDIAPI const char *rtmidi_api_display_name(enum RtMidiApi api);

//! \brief Return the compiled MIDI API having the given name.
//! See \ref RtMidi::getCompiledApiByName().
RTMIDIAPI enum RtMidiApi rtmidi_compiled_api_by_name(const char *name);

//! \internal Report an error.
RTMIDIAPI void rtmidi_error (enum RtMidiErrorType type, const char* errorString);

/*! \brief Open a MIDI port.
 *
 * \param port      Must be greater than 0
 * \param portName  Name for the application port.
 *
 * See RtMidi::openPort().
 */
RTMIDIAPI void rtmidi_open_port (RtMidiPtr device, unsigned int portNumber, const char *portName);

/*! \brief Creates a virtual MIDI port to which other software applications can 
 * connect.  
 *
 * \param portName  Name for the application port.
 *
 * See RtMidi::openVirtualPort().
 */
RTMIDIAPI void rtmidi_open_virtual_port (RtMidiPtr device, const char *portName);

/*! \brief Close a MIDI connection.
 * See RtMidi::closePort().
 */
RTMIDIAPI void rtmidi_close_port (RtMidiPtr device);

/*! \brief Return the number of available MIDI ports.
 * See RtMidi::getPortCount().
 */
RTMIDIAPI unsigned int rtmidi_get_port_count (RtMidiPtr device);

/*! \brief Return a string identifier for the specified MIDI input port number.
 * See RtMidi::getPortName().
 */
RTMIDIAPI const char* rtmidi_get_port_name (RtMidiPtr device, unsigned int portNumber);

/* RtMidiIn API */

//! \brief Create a default RtMidiInPtr value, with no initialization.
RTMIDIAPI RtMidiInPtr rtmidi_in_create_default (void);

/*! \brief Create a  RtMidiInPtr value, with given api, clientName and queueSizeLimit.
 *
 *  \param api            An optional API id can be specified.
 *  \param clientName     An optional client name can be specified. This
 *                        will be used to group the ports that are created
 *                        by the application.
 *  \param queueSizeLimit An optional size of the MIDI input queue can be
 *                        specified.
 *
 * See RtMidiIn::RtMidiIn().
 */
RTMIDIAPI RtMidiInPtr rtmidi_in_create (enum RtMidiApi api, const char *clientName, unsigned int queueSizeLimit);

//! \brief Free the given RtMidiInPtr.
RTMIDIAPI void rtmidi_in_free (RtMidiInPtr device);

//! \brief Returns the MIDI API specifier for the given instance of RtMidiIn.
//! See \ref RtMidiIn::getCurrentApi().
RTMIDIAPI enum RtMidiApi rtmidi_in_get_current_api (RtMidiPtr device);

//! \brief Set a callback function to be invoked for incoming MIDI messages.
//! See \ref RtMidiIn::setCallback().
RTMIDIAPI void rtmidi_in_set_callback (RtMidiInPtr device, RtMidiCCallback callback, void *userData);

//! \brief Cancel use of the current callback function (if one exists).
//! See \ref RtMidiIn::cancelCallback().
RTMIDIAPI void rtmidi_in_cancel_callback (RtMidiInPtr device);

//! \brief Specify whether certain MIDI message types should be queued or ignored during input.
//! See \ref RtMidiIn::ignoreTypes().
RTMIDIAPI void rtmidi_in_ignore_types (RtMidiInPtr device, bool midiSysex, bool midiTime, bool midiSense);

/*! Fill the user-provided array with the data bytes for the next available
 * MIDI message in the input queue and return the event delta-time in seconds.
 *
 * \param message   Must point to a char* that is already allocated.
 *                  SYSEX messages maximum size being 1024, a statically
 *                  allocated array could
 *                  be sufficient. 
 * \param size      Is used to return the size of the message obtained. 
 *
 * See RtMidiIn::getMessage().
 */
RTMIDIAPI double rtmidi_in_get_message (RtMidiInPtr device, unsigned char *message, size_t *size);

/* RtMidiOut API */

//! \brief Create a default RtMidiInPtr value, with no initialization.
RTMIDIAPI RtMidiOutPtr rtmidi_out_create_default (void);

/*! \brief Create a RtMidiOutPtr value, with given and clientName.
 *
 *  \param api            An optional API id can be specified.
 *  \param clientName     An optional client name can be specified. This
 *                        will be used to group the ports that are created
 *                        by the application.
 *
 * See RtMidiOut::RtMidiOut().
 */
RTMIDIAPI RtMidiOutPtr rtmidi_out_create (enum RtMidiApi api, const char *clientName);

//! \brief Free the given RtMidiOutPtr.
RTMIDIAPI void rtmidi_out_free (RtMidiOutPtr device);

//! \brief Returns the MIDI API specifier for the given instance of RtMidiOut.
//! See \ref RtMidiOut::getCurrentApi().
RTMIDIAPI enum RtMidiApi rtmidi_out_get_current_api (RtMidiPtr device);

//! \brief Immediately send a single message out an open MIDI output port.
//! See \ref RtMidiOut::sendMessage().
RTMIDIAPI int rtmidi_out_send_message (RtMidiOutPtr device, const unsigned char *message, int length);


#ifdef __cplusplus
}
#endif
#endif

/*! }@ */