Tutorial   Class/Enum List   File List   Compound Members   C interface  

Files | Classes | Typedefs | Enumerations | Enumerator | Functions | Variables
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
timeStampThe time at which the message has been received.
messageThe midi message.
userDataAdditional 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

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
apisAn array or a null value.
apis_sizeNumber 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
portMust be greater than 0
portNameName 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
portNameName 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
apiAn optional API id can be specified.
clientNameAn optional client name can be specified. This will be used to group the ports that are created by the application.
queueSizeLimitAn 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
messageMust point to a char* that is already allocated. SYSEX messages maximum size being 1024, a statically allocated array could be sufficient.
sizeIs 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
apiAn optional API id can be specified.
clientNameAn 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.


©2003-2023 Gary P. Scavone, McGill University. All Rights Reserved.
Maintained by Gary P. Scavone, gary at music.mcgill.ca