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.

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_NUM }
	MIDI API specifier arguments. See 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 }
	Defined RtMidiError types. See RtMidiError::Type. More...

Functions
RTMIDIAPI const char *	rtmidi_get_version ()
	Return the current RtMidi version. ! See 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 RtMidi::getApiName().
RTMIDIAPI const char *	rtmidi_api_display_name (enum RtMidiApi api)
	Return the display name of a specified compiled MIDI API. See RtMidi::getApiDisplayName().
RTMIDIAPI enum RtMidiApi	rtmidi_compiled_api_by_name (const char *name)
	Return the compiled MIDI API having the given name. See 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 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 RtMidiIn::setCallback().
RTMIDIAPI void	rtmidi_in_cancel_callback (RtMidiInPtr device)
	Cancel use of the current callback function (if one exists). See 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 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 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 RtMidiOut::sendMessage().

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

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.

Class Members
void *	ptr	The wrapped RtMidi object.
void *	data
bool	ok	True when the last function call was OK.
const 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 RtMidiIn::RtMidiCallback.

Enumeration Type Documentation

RtMidiApi

enum RtMidiApi

MIDI API specifier arguments. See 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_NUM	Number of values in this enum.

RtMidiErrorType

enum RtMidiErrorType

Defined RtMidiError types. See 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.

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

rtmidi_open_port()

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

Open a MIDI port.

Parameters

port	Must be greater than 0
portName	Name for the application port.

See 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

portName

Name for the application port.

See 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

message	Must point to a char* that is already allocated. SYSEX messages maximum size being 1024, a statically allocated array could be sufficient.
size	Is used to return the size of the message obtained. Must be set to the size of message when calling.

See 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().

Variable Documentation

ptr

void* RtMidiOutPtr::ptr

The wrapped RtMidi object.

ok

bool RtMidiOutPtr::ok

True when the last function call was OK.

msg

const char* RtMidiOutPtr::msg

If an error occurred (ok != true), set to an error message.