The RtMidi Tutorial

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

  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.

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