C interface

C interface to realtime MIDI input/output C++ classes. More...

Files
file	rtmidi_c.h

Classes
struct	RtMidiOutPtr
	Wraps an RtMidi object for C function return statuses. More...

Typedefs
typedef void(*	RtMidiCCallback) (double timeStamp, const unsigned char *message, size_t messageSize, void *userData)
	The type of a RtMidi callback function.
typedef void(*	RtMidiErrorCCallback) (enum RtMidiErrorType type, const char *errorText, void *userData)
	The type of a RtMidi error callback function.

Enumerations
enum	RtMidiApi {   RTMIDI_API_UNSPECIFIED , RTMIDI_API_MACOSX_CORE , RTMIDI_API_LINUX_ALSA , RTMIDI_API_UNIX_JACK ,   RTMIDI_API_WINDOWS_MM , RTMIDI_API_RTMIDI_DUMMY , RTMIDI_API_WEB_MIDI_API , RTMIDI_API_WINDOWS_UWP ,   RTMIDI_API_ANDROID , RTMIDI_API_WINDOWS_MIDI_SERVICES , RTMIDI_API_NUM }
	MIDI API specifier arguments. See rt::midi::RtMidi::Api. More...
enum	RtMidiErrorType {   RTMIDI_ERROR_WARNING , RTMIDI_ERROR_DEBUG_WARNING , RTMIDI_ERROR_UNSPECIFIED , RTMIDI_ERROR_NO_DEVICES_FOUND ,   RTMIDI_ERROR_INVALID_DEVICE , RTMIDI_ERROR_MEMORY_ERROR , RTMIDI_ERROR_INVALID_PARAMETER , RTMIDI_ERROR_INVALID_USE ,   RTMIDI_ERROR_DRIVER_ERROR , RTMIDI_ERROR_SYSTEM_ERROR , RTMIDI_ERROR_THREAD_ERROR , RTMIDI_ERROR_DRIVER_NOT_INSTALLED }
	Defined RtMidiError types. See rt::midi::RtMidiError::Type. More...

Functions
RTMIDIAPI const char *	rtmidi_get_version ()
	Return the current RtMidi version. ! See rt::midi::RtMidi::getVersion().
RTMIDIAPI int	rtmidi_get_compiled_api (enum RtMidiApi *apis, unsigned int apis_size)
	Determine the available compiled MIDI APIs.
RTMIDIAPI const char *	rtmidi_api_name (enum RtMidiApi api)
	Return the name of a specified compiled MIDI API. See rt::midi::RtMidi::getApiName().
RTMIDIAPI const char *	rtmidi_api_display_name (enum RtMidiApi api)
	Return the display name of a specified compiled MIDI API. See rt::midi::RtMidi::getApiDisplayName().
RTMIDIAPI enum RtMidiApi	rtmidi_compiled_api_by_name (const char *name)
	Return the compiled MIDI API having the given name. See rt::midi::RtMidi::getCompiledApiByName().
RTMIDIAPI void	rtmidi_open_port (RtMidiPtr device, unsigned int portNumber, const char *portName)
	Open a MIDI port.
RTMIDIAPI void	rtmidi_open_virtual_port (RtMidiPtr device, const char *portName)
	Creates a virtual MIDI port to which other software applications can connect.
RTMIDIAPI void	rtmidi_close_port (RtMidiPtr device)
	Close a MIDI connection. See RtMidi::closePort().
RTMIDIAPI unsigned int	rtmidi_get_port_count (RtMidiPtr device)
	Return the number of available MIDI ports. See RtMidi::getPortCount().
RTMIDIAPI int	rtmidi_get_port_name (RtMidiPtr device, unsigned int portNumber, char *bufOut, int *bufLen)
	Access a string identifier for the specified MIDI input port number.
RTMIDIAPI RtMidiInPtr	rtmidi_in_create_default (void)
	Create a default RtMidiInPtr value, with no initialization.
RTMIDIAPI RtMidiInPtr	rtmidi_in_create (enum RtMidiApi api, const char *clientName, unsigned int queueSizeLimit)
	Create a RtMidiInPtr value, with given api, clientName and queueSizeLimit.
RTMIDIAPI void	rtmidi_in_free (RtMidiInPtr device)
	Free the given RtMidiInPtr.
RTMIDIAPI enum RtMidiApi	rtmidi_in_get_current_api (RtMidiPtr device)
	Returns the MIDI API specifier for the given instance of RtMidiIn. See rt::midi::RtMidiIn::getCurrentApi().
RTMIDIAPI void	rtmidi_in_set_callback (RtMidiInPtr device, RtMidiCCallback callback, void *userData)
	Set a callback function to be invoked for incoming MIDI messages. See rt::midi::RtMidiIn::setCallback().
RTMIDIAPI void	rtmidi_in_cancel_callback (RtMidiInPtr device)
	Cancel use of the current callback function (if one exists). See rt::midi::RtMidiIn::cancelCallback().
RTMIDIAPI void	rtmidi_in_ignore_types (RtMidiInPtr device, bool midiSysex, bool midiTime, bool midiSense)
	Specify whether certain MIDI message types should be queued or ignored during input. See rt::midi::RtMidiIn::ignoreTypes().
RTMIDIAPI double	rtmidi_in_get_message (RtMidiInPtr device, unsigned char *message, size_t *size)
RTMIDIAPI RtMidiOutPtr	rtmidi_out_create_default (void)
	Create a default RtMidiInPtr value, with no initialization.
RTMIDIAPI RtMidiOutPtr	rtmidi_out_create (enum RtMidiApi api, const char *clientName)
	Create a RtMidiOutPtr value, with given and clientName.
RTMIDIAPI void	rtmidi_out_free (RtMidiOutPtr device)
	Free the given RtMidiOutPtr.
RTMIDIAPI enum RtMidiApi	rtmidi_out_get_current_api (RtMidiPtr device)
	Returns the MIDI API specifier for the given instance of RtMidiOut. See rt::midi::RtMidiOut::getCurrentApi().
RTMIDIAPI int	rtmidi_out_send_message (RtMidiOutPtr device, const unsigned char *message, int length)
	Immediately send a single message out an open MIDI output port. See rt::midi::RtMidiOut::sendMessage().
RTMIDIAPI void	rtmidi_set_error_callback (RtMidiPtr device, RtMidiErrorCCallback callback, void *userData)
	Set error callback function on a RtMidiPtr. See rt::midi::RtMidi::setErrorCallback().

Detailed Description

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

---

Class Documentation

RtMidiWrapper

struct RtMidiWrapper

Wraps an RtMidi object for C function return statuses.

Typedef for a generic RtMidiOut pointer.

Typedef for a generic RtMidiIn pointer.

Typedef for a generic RtMidi pointer.

Every function taking a device clears ok and msg on entry, so they describe that call alone. Read them before calling anything else on the same device. An error delivered to a callback set with rtmidi_set_error_callback() is not cleared this way.

Clearing frees the previous message, so a device belongs to one thread.

Class Members
void *	ptr	The wrapped RtMidi object.
void *	callback_proxy
void *	error_callback_proxy
bool	ok	True when the last function call was OK.
char *	msg	If an error occurred (ok != true), set to an error message.

Typedef Documentation

RtMidiCCallback

typedef void(* RtMidiCCallback) (double timeStamp, const unsigned char *message, size_t messageSize, void *userData)

The type of a RtMidi callback function.

Parameters

timeStamp	The time at which the message has been received.
message	The midi message.
userData	Additional user data for the callback.

See rt::midi::RtMidiIn::RtMidiCallback.

RtMidiErrorCCallback

typedef void(* RtMidiErrorCCallback) (enum RtMidiErrorType type, const char *errorText, void *userData)

The type of a RtMidi error callback function.

Parameters

type	Type of error
errorText	Error description
userData	Additional user data for the callback.

See rt::midi::RtMidi::setErrorCallback.

Enumeration Type Documentation

RtMidiApi

enum RtMidiApi

MIDI API specifier arguments. See rt::midi::RtMidi::Api.

Enumerator
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_WEB_MIDI_API	W3C Web MIDI API.
RTMIDI_API_WINDOWS_UWP	The Microsoft Universal Windows Platform MIDI API.
RTMIDI_API_ANDROID	The Android MIDI API.
RTMIDI_API_WINDOWS_MIDI_SERVICES	Windows MIDI Services.
RTMIDI_API_NUM	Number of values in this enum.

RtMidiErrorType

enum RtMidiErrorType

Defined RtMidiError types. See rt::midi::RtMidiError::Type.

Enumerator
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 occurred 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 occurred.
RTMIDI_ERROR_SYSTEM_ERROR	A system error occurred.
RTMIDI_ERROR_THREAD_ERROR	A thread error occurred.
RTMIDI_ERROR_DRIVER_NOT_INSTALLED	A required driver or runtime is not installed.

Function Documentation

rtmidi_get_compiled_api()

RTMIDIAPI int rtmidi_get_compiled_api	(	enum RtMidiApi *	apis,
		unsigned int	apis_size
	)

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.

Parameters

apis	An array or a null value.
apis_size	Number of elements pointed to by apis

Returns

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 rt::midi::RtMidi::getCompiledApi().

rtmidi_open_port()

RTMIDIAPI void rtmidi_open_port	(	RtMidiPtr	device,
		unsigned int	portNumber,
		const char *	portName
	)

Open a MIDI port.

Parameters

device	The RtMidiIn or RtMidiOut to open it on.
portNumber	The port to open, from 0 to rtmidi_get_port_count() - 1.
portName	Name for the application port.

See rt::midi::RtMidi::openPort().

rtmidi_open_virtual_port()

RTMIDIAPI void rtmidi_open_virtual_port	(	RtMidiPtr	device,
		const char *	portName
	)

Creates a virtual MIDI port to which other software applications can connect.

Parameters

device	The RtMidiIn or RtMidiOut to create it on.
portName	Name for the application port.

See rt::midi::RtMidi::openVirtualPort().

rtmidi_get_port_name()

RTMIDIAPI int rtmidi_get_port_name	(	RtMidiPtr	device,
		unsigned int	portNumber,
		char *	bufOut,
		int *	bufLen
	)

Access a string identifier for the specified MIDI input port number.

To prevent memory leaks a char buffer must be passed to this function. NULL can be passed as bufOut parameter, and that will write the required buffer length in the bufLen.

See RtMidi::getPortName().

rtmidi_in_create()

RTMIDIAPI RtMidiInPtr rtmidi_in_create	(	enum RtMidiApi	api,
		const char *	clientName,
		unsigned int	queueSizeLimit
	)

Create a RtMidiInPtr value, with given api, clientName and queueSizeLimit.

Parameters

api	An optional API id can be specified.
clientName	An optional client name can be specified. This will be used to group the ports that are created by the application.
queueSizeLimit	An optional size of the MIDI input queue can be specified.

See RtMidiIn::RtMidiIn().

rtmidi_in_get_message()

RTMIDIAPI double rtmidi_in_get_message	(	RtMidiInPtr	device,
		unsigned char *	message,
		size_t *	size
	)

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.

Parameters

device	The RtMidiIn to read from.
message	A buffer of at least *size bytes, or NULL to ask for the length of the next message without taking it (the call then returns 0).
size	In: the size of message in bytes. Out: the length of the message, or 0 if the queue was empty. Set it again before every call.

A message longer than *size is not lost: it stays as the next message. RtMidiWrapper::ok is set to false, RtMidiWrapper::msg says so, *size is set to the message's length and -1 is returned, so the caller can call again with a buffer of at least that size. SysEx messages can be much longer than 1024 bytes.

See rt::midi::RtMidiIn::getMessage().

rtmidi_out_create()

RTMIDIAPI RtMidiOutPtr rtmidi_out_create	(	enum RtMidiApi	api,
		const char *	clientName
	)

Create a RtMidiOutPtr value, with given and clientName.

Parameters

api	An optional API id can be specified.
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().