Sequencer event <-> MIDI byte stream coder

Overview

Sequencer event <-> MIDI byte stream coder More…

// typedefs

typedef struct snd_midi_event snd_midi_event_t;

// global functions

int
snd_midi_event_new(
    size_t bufsize,
    snd_midi_event_t** rdev
);

int
snd_midi_event_resize_buffer(
    snd_midi_event_t* dev,
    size_t bufsize
);

void
snd_midi_event_free(snd_midi_event_t* dev);

void
snd_midi_event_init(snd_midi_event_t* dev);

void
snd_midi_event_reset_encode(snd_midi_event_t* dev);

void
snd_midi_event_reset_decode(snd_midi_event_t* dev);

void
snd_midi_event_no_status(
    snd_midi_event_t* dev,
    int on
);

long
snd_midi_event_encode(
    snd_midi_event_t* dev,
    const unsigned char* buf,
    long count,
    snd_seq_event_t* ev
);

int
snd_midi_event_encode_byte(
    snd_midi_event_t* dev,
    int c,
    snd_seq_event_t* ev
);

long
snd_midi_event_decode(
    snd_midi_event_t* dev,
    unsigned char* buf,
    long count,
    const snd_seq_event_t* ev
);

Detailed Documentation

Typedefs

typedef struct snd_midi_event snd_midi_event_t

container for sequencer midi event parsers

Global Functions

int
snd_midi_event_new(
    size_t bufsize,
    snd_midi_event_t** rdev
)

Creates a MIDI event parser.

This function creates and initializes a MIDI parser object that can be used to convert a MIDI byte stream to sequencer events (encoding) and/or to convert sequencer events to a MIDI byte stream (decoding).

-ENOMEM

Out of memory.

LSB 3.2

Parameters:

bufsize	Size of the buffer used for encoding; this should be large enough to hold the largest MIDI message to be encoded.
rdev	The new MIDI event parser.

Returns:

Zero on success, otherwise a negative error code.

int
snd_midi_event_resize_buffer(
    snd_midi_event_t* dev,
    size_t bufsize
)

Resizes the MIDI message encoding buffer.

This function resizes the buffer that is used to hold partially encoded MIDI messages.

If there is a partially encoded message in the buffer, it is dropped.

-ENOMEM

Out of memory.

Parameters:

dev	MIDI event parser.
bufsize	The new buffer size.

Returns:

Zero on success, otherwise a negative error code.

void
snd_midi_event_free(snd_midi_event_t* dev)

Frees a MIDI event parser.

LSB 3.2

Parameters:

dev	MIDI event parser.

void
snd_midi_event_init(snd_midi_event_t* dev)

Resets MIDI encode/decode parsers.

This function resets both encoder and decoder of the MIDI event parser. LSB 3.2

Parameters:

dev	MIDI event parser.

void
snd_midi_event_reset_encode(snd_midi_event_t* dev)

Resets MIDI encode parser.

This function resets the MIDI encoder of the parser dev. Any partially encoded MIDI message is dropped, and running status state is cleared.

LSB 3.2

Parameters:

dev	MIDI event parser.

void
snd_midi_event_reset_decode(snd_midi_event_t* dev)

Resets MIDI decode parser.

This function resets the MIDI decoder of the parser dev. The next decoded message does not use running status from before the call to snd_midi_event_reset_decode.

LSB 3.2

Parameters:

dev	MIDI event parser.

void
snd_midi_event_no_status(
    snd_midi_event_t* dev,
    int on
)

Enables/disables MIDI command merging.

This function enables or disables MIDI command merging (running status).

When MIDI command merging is not disabled, snd_midi_event_decode is allowed to omit any status byte that is identical to the previous status byte.

Parameters:

dev	MIDI event parser.
on	0 to enable MIDI command merging, 1 to always write the command byte.

long
snd_midi_event_encode(
    snd_midi_event_t* dev,
    const unsigned char* buf,
    long count,
    snd_seq_event_t* ev
)

Encodes bytes to sequencer event.

This function tries to use up to count bytes from the beginning of the buffer to encode a sequencer event. If a complete MIDI message has been encoded, the sequencer event is written to ev; otherwise, ev->type is set to SND_SEQ_EVENT_NONE, and further bytes are required to complete a message.

The buffer in dev is used to hold any bytes of a not-yet-complete MIDI message. If a System Exclusive message is larger than the buffer, the message is split into multiple parts, and a sequencer event is returned at the end of each part.

Any bytes that are not part of a valid MIDI message are silently ignored, i.e., they are consumed without signaling an error.

When this function returns a system exclusive sequencer event (ev->type is SND_SEQ_EVENT_SYSEX), the data pointer (ev->data.ext.ptr) points into the MIDI event parser’s buffer. Therefore, the sequencer event can only be used as long as that buffer remains valid, i.e., until the next call to snd_midi_event_encode, snd_midi_event_encode_byte, snd_midi_event_resize_buffer, snd_midi_event_init, snd_midi_event_reset_encode, or snd_midi_event_free for that MIDI event parser.

This function can generate any sequencer event that corresponds to a MIDI message, i.e.:

Some implementations may also be able to generate the following events for a sequence of controller change messages:

LSB 3.2

Parameters:

dev	MIDI event parser.
buf	Buffer containing bytes of a raw MIDI stream.
count	Number of bytes in buf.
ev	Sequencer event.

Returns:

The number of bytes consumed, or a negative error code.

int
snd_midi_event_encode_byte(
    snd_midi_event_t* dev,
    int c,
    snd_seq_event_t* ev
)

Encodes byte to sequencer event.

This function tries to use the byte c to encode a sequencer event. If a complete MIDI message has been encoded, the sequencer event is written to ev; otherwise, further bytes are required to complete a message.

See also the description of snd_midi_event_encode.

LSB 3.2

Parameters:

dev	MIDI event parser.
c	A byte of a raw MIDI stream.
ev	Sequencer event.

Returns:

1 if a sequenver event has been completed, 0 if more bytes are required to complete an event, or a negative error code.

long
snd_midi_event_decode(
    snd_midi_event_t* dev,
    unsigned char* buf,
    long count,
    const snd_seq_event_t* ev
)

Decodes sequencer event to MIDI byte stream.

This function tries to decode the sequencer event into one or more MIDI messages, and writes the raw MIDI byte(s) into buf.

The generated MIDI messages may use running status, unless disabled with snd_midi_event_no_status.

The required buffer size for a sequencer event it as most 12 bytes, except for System Exclusive events (ev->type == SND_SEQ_EVENT_SYSEX) which can have any length (as specified by ev->data.ext.len).

The following sequencer events correspond to MIDI messages:

-EINVAL	ev is not a valid sequencer event.
-ENOENT	The sequencer event does not correspond to one or more MIDI messages.
-ENOMEM	The MIDI message(s) would not fit into count bytes.

LSB 3.2

Parameters:

dev	MIDI event parser.
buf	Buffer for the resulting MIDI byte stream.
count	Number of bytes in buf.
ev	The sequencer event to decode.

Returns:

The number of bytes written to buf, or a negative error code.