RawMidi Interface

Overview

The RawMidi Interface. More…

// typedefs

typedef struct _snd_rawmidi_info snd_rawmidi_info_t;
typedef struct _snd_rawmidi_params snd_rawmidi_params_t;
typedef struct _snd_rawmidi_status snd_rawmidi_status_t;
typedef struct _snd_rawmidi snd_rawmidi_t;

// enums

enum snd_rawmidi_stream_t;
enum snd_rawmidi_type_t;

// global functions

int
snd_rawmidi_open(
    snd_rawmidi_t** in_rmidi,
    snd_rawmidi_t** out_rmidi,
    const char* name,
    int mode
);

int
snd_rawmidi_open_lconf(
    snd_rawmidi_t** in_rmidi,
    snd_rawmidi_t** out_rmidi,
    const char* name,
    int mode,
    snd_config_t* lconf
);

int
snd_rawmidi_close(snd_rawmidi_t* rmidi);

int
snd_rawmidi_poll_descriptors_count(snd_rawmidi_t* rmidi);

int
snd_rawmidi_poll_descriptors(
    snd_rawmidi_t* rmidi,
    struct pollfd* pfds,
    unsigned int space
);

int
snd_rawmidi_poll_descriptors_revents(
    snd_rawmidi_t* rawmidi,
    struct pollfd* pfds,
    unsigned int nfds,
    unsigned short* revent
);

int
snd_rawmidi_nonblock(
    snd_rawmidi_t* rmidi,
    int nonblock
);

size_t
snd_rawmidi_info_sizeof(void);

int
snd_rawmidi_info_malloc(snd_rawmidi_info_t** ptr);

void
snd_rawmidi_info_free(snd_rawmidi_info_t* obj);

void
snd_rawmidi_info_copy(
    snd_rawmidi_info_t* dst,
    const snd_rawmidi_info_t* src
);

unsigned int
snd_rawmidi_info_get_device(const snd_rawmidi_info_t* obj);

unsigned int
snd_rawmidi_info_get_subdevice(const snd_rawmidi_info_t* obj);

snd_rawmidi_stream_t
snd_rawmidi_info_get_stream(const snd_rawmidi_info_t* obj);

int
snd_rawmidi_info_get_card(const snd_rawmidi_info_t* obj);

unsigned int
snd_rawmidi_info_get_flags(const snd_rawmidi_info_t* obj);

const char*
snd_rawmidi_info_get_id(const snd_rawmidi_info_t* obj);

const char*
snd_rawmidi_info_get_name(const snd_rawmidi_info_t* obj);

const char*
snd_rawmidi_info_get_subdevice_name(const snd_rawmidi_info_t* obj);

unsigned int
snd_rawmidi_info_get_subdevices_count(const snd_rawmidi_info_t* obj);

unsigned int
snd_rawmidi_info_get_subdevices_avail(const snd_rawmidi_info_t* obj);

void
snd_rawmidi_info_set_device(
    snd_rawmidi_info_t* obj,
    unsigned int val
);

void
snd_rawmidi_info_set_subdevice(
    snd_rawmidi_info_t* obj,
    unsigned int val
);

void
snd_rawmidi_info_set_stream(
    snd_rawmidi_info_t* obj,
    snd_rawmidi_stream_t val
);

int
snd_rawmidi_info(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_info_t* info
);

size_t
snd_rawmidi_params_sizeof(void);

int
snd_rawmidi_params_malloc(snd_rawmidi_params_t** ptr);

void
snd_rawmidi_params_free(snd_rawmidi_params_t* obj);

void
snd_rawmidi_params_copy(
    snd_rawmidi_params_t* dst,
    const snd_rawmidi_params_t* src
);

int
snd_rawmidi_params_set_buffer_size(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params,
    size_t val
);

size_t
snd_rawmidi_params_get_buffer_size(const snd_rawmidi_params_t* params);

int
snd_rawmidi_params_set_avail_min(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params,
    size_t val
);

size_t
snd_rawmidi_params_get_avail_min(const snd_rawmidi_params_t* params);

int
snd_rawmidi_params_set_no_active_sensing(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params,
    int val
);

int
snd_rawmidi_params_get_no_active_sensing(const snd_rawmidi_params_t* params);

int
snd_rawmidi_params(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params
);

int
snd_rawmidi_params_current(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params
);

size_t
snd_rawmidi_status_sizeof(void);

int
snd_rawmidi_status_malloc(snd_rawmidi_status_t** ptr);

void
snd_rawmidi_status_free(snd_rawmidi_status_t* obj);

void
snd_rawmidi_status_copy(
    snd_rawmidi_status_t* dst,
    const snd_rawmidi_status_t* src
);

void
snd_rawmidi_status_get_tstamp(
    const snd_rawmidi_status_t* obj,
    snd_htimestamp_t* ptr
);

size_t
snd_rawmidi_status_get_avail(const snd_rawmidi_status_t* obj);

size_t
snd_rawmidi_status_get_xruns(const snd_rawmidi_status_t* obj);

int
snd_rawmidi_status(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_status_t* status
);

int
snd_rawmidi_drain(snd_rawmidi_t* rmidi);

int
snd_rawmidi_drop(snd_rawmidi_t* rmidi);

ssize_t
snd_rawmidi_write(
    snd_rawmidi_t* rmidi,
    const void* buffer,
    size_t size
);

ssize_t
snd_rawmidi_read(
    snd_rawmidi_t* rmidi,
    void* buffer,
    size_t size
);

const char*
snd_rawmidi_name(snd_rawmidi_t* rmidi);

snd_rawmidi_type_t
snd_rawmidi_type(snd_rawmidi_t* rmidi);

snd_rawmidi_stream_t
snd_rawmidi_stream(snd_rawmidi_t* rawmidi);

// macros

#define SND_RAWMIDI_APPEND
#define SND_RAWMIDI_DLSYM_VERSION
#define SND_RAWMIDI_NONBLOCK
#define SND_RAWMIDI_SYNC
#define snd_rawmidi_info_alloca(ptr)
#define snd_rawmidi_params_alloca(ptr)
#define snd_rawmidi_status_alloca(ptr)

Detailed Documentation

The RawMidi Interface. See RawMidi interface page for more details.

Typedefs

typedef struct _snd_rawmidi_info snd_rawmidi_info_t

RawMidi information container

typedef struct _snd_rawmidi_params snd_rawmidi_params_t

RawMidi settings container

typedef struct _snd_rawmidi_status snd_rawmidi_status_t

RawMidi status container

typedef struct _snd_rawmidi snd_rawmidi_t

RawMidi handle

Global Functions

int
snd_rawmidi_open(
    snd_rawmidi_t** in_rmidi,
    snd_rawmidi_t** out_rmidi,
    const char* name,
    int mode
)

Opens a new connection to the RawMidi interface.

Opens a new connection to the RawMidi interface specified with an ASCII identifier and mode.

Parameters:

inputp	Returned input handle (NULL if not wanted)
outputp	Returned output handle (NULL if not wanted)
name	ASCII identifier of the RawMidi handle
mode	Open mode

Returns:

0 on success otherwise a negative error code

int
snd_rawmidi_open_lconf(
    snd_rawmidi_t** in_rmidi,
    snd_rawmidi_t** out_rmidi,
    const char* name,
    int mode,
    snd_config_t* lconf
)

Opens a new connection to the RawMidi interface using local configuration.

Opens a new connection to the RawMidi interface specified with an ASCII identifier and mode.

Parameters:

inputp	Returned input handle (NULL if not wanted)
outputp	Returned output handle (NULL if not wanted)
name	ASCII identifier of the RawMidi handle
mode	Open mode
lconf	Local configuration

Returns:

0 on success otherwise a negative error code

int
snd_rawmidi_close(snd_rawmidi_t* rmidi)

close RawMidi handle

Closes the specified RawMidi handle and frees all associated resources.

Parameters:

rawmidi

RawMidi handle

Returns:

0 on success otherwise a negative error code

int
snd_rawmidi_poll_descriptors_count(snd_rawmidi_t* rmidi)

get count of poll descriptors for RawMidi handle

Parameters:

rawmidi

RawMidi handle

Returns:

count of poll descriptors

int
snd_rawmidi_poll_descriptors(
    snd_rawmidi_t* rmidi,
    struct pollfd* pfds,
    unsigned int space
)

get poll descriptors

Parameters:

rawmidi	RawMidi handle
pfds	array of poll descriptors
space	space in the poll descriptor array

Returns:

count of filled descriptors

int
snd_rawmidi_poll_descriptors_revents(
    snd_rawmidi_t* rawmidi,
    struct pollfd* pfds,
    unsigned int nfds,
    unsigned short* revent
)

get returned events from poll descriptors

Parameters:

rawmidi	rawmidi RawMidi handle
pfds	array of poll descriptors
nfds	count of poll descriptors
revents	returned events

Returns:

zero if success, otherwise a negative error code

int
snd_rawmidi_nonblock(
    snd_rawmidi_t* rmidi,
    int nonblock
)

set nonblock mode

The nonblock mode cannot be used when the stream is in SND_RAWMIDI_APPEND state.

Parameters:

rawmidi	RawMidi handle
nonblock	0 = block, 1 = nonblock mode

Returns:

0 on success otherwise a negative error code

size_t
snd_rawmidi_info_sizeof(void)

get size of the snd_rawmidi_info_t structure in bytes

Returns:

size of the snd_rawmidi_info_t structure in bytes

int
snd_rawmidi_info_malloc(snd_rawmidi_info_t** ptr)

allocate a new snd_rawmidi_info_t structure

Allocates a new snd_rawmidi_params_t structure using the standard malloc C library function.

Parameters:

info	returned pointer

Returns:

0 on success otherwise a negative error code if fails

void
snd_rawmidi_info_free(snd_rawmidi_info_t* obj)

frees the snd_rawmidi_info_t structure

Frees the given snd_rawmidi_params_t structure using the standard free C library function.

Parameters:

info	pointer to the snd_rawmidi_info_t structure to free

void
snd_rawmidi_info_copy(
    snd_rawmidi_info_t* dst,
    const snd_rawmidi_info_t* src
)

copy one snd_rawmidi_info_t structure to another

Parameters:

dst	destination snd_rawmidi_info_t structure
src	source snd_rawmidi_info_t structure

unsigned int
snd_rawmidi_info_get_device(const snd_rawmidi_info_t* obj)

get rawmidi device number

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi device number

unsigned int
snd_rawmidi_info_get_subdevice(const snd_rawmidi_info_t* obj)

get rawmidi subdevice number

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi subdevice number

snd_rawmidi_stream_t
snd_rawmidi_info_get_stream(const snd_rawmidi_info_t* obj)

get rawmidi stream identification

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi stream identification

int
snd_rawmidi_info_get_card(const snd_rawmidi_info_t* obj)

get rawmidi card number

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi card number

unsigned int
snd_rawmidi_info_get_flags(const snd_rawmidi_info_t* obj)

get rawmidi flags

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi flags

const char*
snd_rawmidi_info_get_id(const snd_rawmidi_info_t* obj)

get rawmidi hardware driver identifier

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi hardware driver identifier

const char*
snd_rawmidi_info_get_name(const snd_rawmidi_info_t* obj)

get rawmidi hardware driver name

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi hardware driver name

const char*
snd_rawmidi_info_get_subdevice_name(const snd_rawmidi_info_t* obj)

get rawmidi subdevice name

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi subdevice name

unsigned int
snd_rawmidi_info_get_subdevices_count(const snd_rawmidi_info_t* obj)

get rawmidi count of subdevices

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi count of subdevices

unsigned int
snd_rawmidi_info_get_subdevices_avail(const snd_rawmidi_info_t* obj)

get rawmidi available count of subdevices

Parameters:

info	pointer to a snd_rawmidi_info_t structure

Returns:

rawmidi available count of subdevices

void
snd_rawmidi_info_set_device(
    snd_rawmidi_info_t* obj,
    unsigned int val
)

set rawmidi device number

Parameters:

info	pointer to a snd_rawmidi_info_t structure
val	device number

void
snd_rawmidi_info_set_subdevice(
    snd_rawmidi_info_t* obj,
    unsigned int val
)

set rawmidi subdevice number

Parameters:

info	pointer to a snd_rawmidi_info_t structure
val	subdevice number

void
snd_rawmidi_info_set_stream(
    snd_rawmidi_info_t* obj,
    snd_rawmidi_stream_t val
)

set rawmidi stream identifier

Parameters:

info	pointer to a snd_rawmidi_info_t structure
val	rawmidi stream identifier

int
snd_rawmidi_info(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_info_t* info
)

get information about RawMidi handle

Parameters:

rawmidi	RawMidi handle
info	pointer to a snd_rawmidi_info_t structure to be filled

Returns:

0 on success otherwise a negative error code

size_t
snd_rawmidi_params_sizeof(void)

get size of the snd_rawmidi_params_t structure in bytes

Returns:

size of the snd_rawmidi_params_t structure in bytes

int
snd_rawmidi_params_malloc(snd_rawmidi_params_t** ptr)

allocate the snd_rawmidi_params_t structure

Allocates a new snd_rawmidi_params_t structure using the standard malloc C library function.

Parameters:

params

returned pointer

Returns:

0 on success otherwise a negative error code if fails

void
snd_rawmidi_params_free(snd_rawmidi_params_t* obj)

frees the snd_rawmidi_params_t structure

Frees the given snd_rawmidi_params_t structure using the standard free C library function.

Parameters:

params

pointer to the snd_rawmidi_params_t structure to free

void
snd_rawmidi_params_copy(
    snd_rawmidi_params_t* dst,
    const snd_rawmidi_params_t* src
)

copy one snd_rawmidi_params_t structure to another

Parameters:

dst	destination snd_rawmidi_params_t structure
src	source snd_rawmidi_params_t structure

int
snd_rawmidi_params_set_buffer_size(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params,
    size_t val
)

set rawmidi I/O ring buffer size

Parameters:

rawmidi	RawMidi handle
params	pointer to a snd_rawmidi_params_t structure
val	size in bytes

Returns:

0 on success otherwise a negative error code

size_t
snd_rawmidi_params_get_buffer_size(const snd_rawmidi_params_t* params)

get rawmidi I/O ring buffer size

Parameters:

params

pointer to a snd_rawmidi_params_t structure

Returns:

size of rawmidi I/O ring buffer in bytes

int
snd_rawmidi_params_set_avail_min(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params,
    size_t val
)

set minimum available bytes in rawmidi I/O ring buffer for wakeup

Parameters:

rawmidi	RawMidi handle
params	pointer to a snd_rawmidi_params_t structure
val	desired value

size_t
snd_rawmidi_params_get_avail_min(const snd_rawmidi_params_t* params)

get minimum available bytes in rawmidi I/O ring buffer for wakeup

Parameters:

params

pointer to snd_rawmidi_params_t structure

Returns:

minimum available bytes

int
snd_rawmidi_params_set_no_active_sensing(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params,
    int val
)

set no-active-sensing action on snd_rawmidi_close()

Parameters:

rawmidi	RawMidi handle
params	pointer to snd_rawmidi_params_t structure
val	value: 0 = enable to send the active sensing message, 1 = disable

Returns:

0 on success otherwise a negative error code

int
snd_rawmidi_params_get_no_active_sensing(const snd_rawmidi_params_t* params)

get no-active-sensing action status

Parameters:

params

pointer to snd_rawmidi_params_t structure

Returns:

the current status (0 = enable, 1 = disable the active sensing message)

int
snd_rawmidi_params(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params
)

set parameters about rawmidi stream

Parameters:

rawmidi	RawMidi handle
params	pointer to a snd_rawmidi_params_t structure to be filled

Returns:

0 on success otherwise a negative error code

int
snd_rawmidi_params_current(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_params_t* params
)

get current parameters about rawmidi stream

Parameters:

rawmidi	RawMidi handle
params	pointer to a snd_rawmidi_params_t structure to be filled

Returns:

0 on success otherwise a negative error code

size_t
snd_rawmidi_status_sizeof(void)

get size of the snd_rawmidi_status_t structure in bytes

Returns:

size of the snd_rawmidi_status_t structure in bytes

int
snd_rawmidi_status_malloc(snd_rawmidi_status_t** ptr)

allocate the snd_rawmidi_status_t structure

Allocates a new snd_rawmidi_status_t structure using the standard malloc C library function.

Parameters:

ptr	returned pointer

Returns:

0 on success otherwise a negative error code if fails

void
snd_rawmidi_status_free(snd_rawmidi_status_t* obj)

frees the snd_rawmidi_status_t structure

Frees the given snd_rawmidi_status_t structure using the standard free C library function.

Parameters:

status

pointer to the snd_rawmidi_status_t structure to free

void
snd_rawmidi_status_copy(
    snd_rawmidi_status_t* dst,
    const snd_rawmidi_status_t* src
)

copy one snd_rawmidi_status_t structure to another

Parameters:

dst	destination snd_rawmidi_status_t structure
src	source snd_rawmidi_status_t structure

void
snd_rawmidi_status_get_tstamp(
    const snd_rawmidi_status_t* obj,
    snd_htimestamp_t* ptr
)

get the start timestamp

Parameters:

status	pointer to a snd_rawmidi_status_t structure
tstamp	returned timestamp value

size_t
snd_rawmidi_status_get_avail(const snd_rawmidi_status_t* obj)

get current available bytes in the rawmidi I/O ring buffer

Parameters:

status

pointer to a snd_rawmidi_status_t structure

Returns:

current available bytes in the rawmidi I/O ring buffer

size_t
snd_rawmidi_status_get_xruns(const snd_rawmidi_status_t* obj)

get count of xruns

Parameters:

status

pointer to a snd_rawmidi_status_t structure

Returns:

count of xruns

int
snd_rawmidi_status(
    snd_rawmidi_t* rmidi,
    snd_rawmidi_status_t* status
)

get status of rawmidi stream

Parameters:

rawmidi	RawMidi handle
status	pointer to a snd_rawmidi_status_t structure to be filled

Returns:

0 on success otherwise a negative error code

int
snd_rawmidi_drain(snd_rawmidi_t* rmidi)

drain all bytes in the rawmidi I/O ring buffer

Waits until all MIDI bytes are not drained (sent) to the hardware device.

Parameters:

rawmidi

RawMidi handle

Returns:

0 on success otherwise a negative error code

int
snd_rawmidi_drop(snd_rawmidi_t* rmidi)

drop all bytes in the rawmidi I/O ring buffer immediately

Parameters:

rawmidi

RawMidi handle

Returns:

0 on success otherwise a negative error code

ssize_t
snd_rawmidi_write(
    snd_rawmidi_t* rmidi,
    const void* buffer,
    size_t size
)

write MIDI bytes to MIDI stream

Parameters:

rawmidi	RawMidi handle
buffer	buffer containing MIDI bytes
size	output buffer size in bytes

ssize_t
snd_rawmidi_read(
    snd_rawmidi_t* rmidi,
    void* buffer,
    size_t size
)

read MIDI bytes from MIDI stream

Parameters:

rawmidi	RawMidi handle
buffer	buffer to store the input MIDI bytes
size	input buffer size in bytes

const char*
snd_rawmidi_name(snd_rawmidi_t* rmidi)

get identifier of RawMidi handle

Returns the ASCII identifier of given RawMidi handle. It’s the same identifier specified in snd_rawmidi_open().

Parameters:

rawmidi

a RawMidi handle

Returns:

ascii identifier of RawMidi handle

snd_rawmidi_type_t
snd_rawmidi_type(snd_rawmidi_t* rmidi)

get type of RawMidi handle

Returns the type snd_rawmidi_type_t of given RawMidi handle.

Parameters:

rawmidi

a RawMidi handle

Returns:

type of RawMidi handle

snd_rawmidi_stream_t
snd_rawmidi_stream(snd_rawmidi_t* rawmidi)

get stream (direction) of RawMidi handle

Returns the stream snd_rawmidi_stream_t of given RawMidi handle.

Parameters:

rawmidi

a RawMidi handle

Returns:

stream of RawMidi handle

Macros

#define SND_RAWMIDI_APPEND

Append (flag to open mode)

#define SND_RAWMIDI_DLSYM_VERSION

dlsym version for interface entry callback

#define SND_RAWMIDI_NONBLOCK

Non blocking mode (flag to open mode)

#define SND_RAWMIDI_SYNC

Write sync mode (Flag to open mode)

#define snd_rawmidi_info_alloca(ptr)

allocate an invalid snd_rawmidi_info_t using standard alloca

Parameters:

ptr	returned pointer

#define snd_rawmidi_params_alloca(ptr)

allocate an invalid snd_rawmidi_params_t using standard alloca

Parameters:

ptr	returned pointer

#define snd_rawmidi_status_alloca(ptr)

allocate an invalid snd_rawmidi_status_t using standard alloca

Parameters:

ptr	returned pointer