ALSA project - the C library reference
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Typedefs | Functions
Sequencer event <-> MIDI byte stream coder
MIDI Sequencer

Typedefs

typedef struct snd_midi_event snd_midi_event_t

Functions

int snd_midi_event_new (size_t bufsize, snd_midi_event_t **rdev)
 Creates a MIDI event parser.
int snd_midi_event_resize_buffer (snd_midi_event_t *dev, size_t bufsize)
 Resizes the MIDI message encoding buffer.
void snd_midi_event_free (snd_midi_event_t *dev)
 Frees a MIDI event parser.
void snd_midi_event_init (snd_midi_event_t *dev)
 Resets MIDI encode/decode parsers.
void snd_midi_event_reset_encode (snd_midi_event_t *dev)
 Resets MIDI encode parser.
void snd_midi_event_reset_decode (snd_midi_event_t *dev)
 Resets MIDI decode parser.
void snd_midi_event_no_status (snd_midi_event_t *dev, int on)
 Enables/disables MIDI command merging.
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.
int snd_midi_event_encode_byte (snd_midi_event_t *dev, int c, snd_seq_event_t *ev)
 Encodes byte to sequencer event.
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.

Detailed Description

Sequencer event <-> MIDI byte stream coder


Typedef Documentation

typedef struct snd_midi_event snd_midi_event_t

container for sequencer midi event parsers


Function Documentation

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.

Parameters:
[in]devMIDI event parser.
[out]bufBuffer for the resulting MIDI byte stream.
[in]countNumber of bytes in buf.
[in]evThe sequencer event to decode.
Returns:
The number of bytes written to buf, or a negative error code.

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:

Errors:
-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.

Conforming to:
LSB 3.2
See also:
snd_midi_event_reset_decode, snd_midi_event_no_status
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.

Parameters:
[in]devMIDI event parser.
[in]bufBuffer containing bytes of a raw MIDI stream.
[in]countNumber of bytes in buf.
[out]evSequencer event.
Returns:
The number of bytes consumed, or a negative error code.

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:

Conforming to:
LSB 3.2
See also:
snd_midi_event_new, snd_midi_event_reset_encode, snd_midi_event_encode_byte
int snd_midi_event_encode_byte ( snd_midi_event_t dev,
int  c,
snd_seq_event_t ev 
)

Encodes byte to sequencer event.

Parameters:
[in]devMIDI event parser.
[in]cA byte of a raw MIDI stream.
[out]evSequencer 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.

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.

Conforming to:
LSB 3.2
See also:
snd_midi_event_new, snd_midi_event_reset_encode, snd_midi_event_encode
void snd_midi_event_free ( snd_midi_event_t dev)

Frees a MIDI event parser.

Parameters:
devMIDI event parser.

Frees a MIDI event parser.

Conforming to:
LSB 3.2
void snd_midi_event_init ( snd_midi_event_t dev)

Resets MIDI encode/decode parsers.

Parameters:
devMIDI event parser.

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

See also:
snd_midi_event_reset_encode, snd_midi_event_reset_decode
Conforming to:
LSB 3.2
int snd_midi_event_new ( size_t  bufsize,
snd_midi_event_t **  rdev 
)

Creates a MIDI event parser.

Parameters:
[in]bufsizeSize of the buffer used for encoding; this should be large enough to hold the largest MIDI message to be encoded.
[out]rdevThe new MIDI event parser.
Returns:
Zero on success, otherwise a negative error code.

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

Errors:
-ENOMEM

Out of memory.

Conforming to:
LSB 3.2
void snd_midi_event_no_status ( snd_midi_event_t dev,
int  on 
)

Enables/disables MIDI command merging.

Parameters:
devMIDI event parser.
on0 to enable MIDI command merging, 1 to always write the command byte.

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.

void snd_midi_event_reset_decode ( snd_midi_event_t dev)

Resets MIDI decode parser.

Parameters:
devMIDI event 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.

Conforming to:
LSB 3.2
void snd_midi_event_reset_encode ( snd_midi_event_t dev)

Resets MIDI encode parser.

Parameters:
devMIDI event parser.

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

Conforming to:
LSB 3.2
int snd_midi_event_resize_buffer ( snd_midi_event_t dev,
size_t  bufsize 
)

Resizes the MIDI message encoding buffer.

Parameters:
devMIDI event parser.
bufsizeThe new buffer size.
Returns:
Zero on success, otherwise a negative error code.

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.

Errors:
-ENOMEM

Out of memory.

See also:
snd_midi_event_encode, snd_midi_event_reset_encode