Sequencer event <-> MIDI byte stream coder

Collaboration diagram for Sequencer event <-> MIDI byte stream coder:

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

Detailed Description

Sequencer event <-> MIDI byte stream coder

Typedef Documentation

snd_midi_event_t

typedef struct snd_midi_event snd_midi_event_t

container for sequencer midi event parsers

Function Documentation

snd_midi_event_decode()

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]	dev	MIDI event parser.
[out]	buf	Buffer for the resulting MIDI byte stream.
[in]	count	Number of bytes in buf.
[in]	ev	The 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:

• SND_SEQ_EVENT_NOTEOFF
• SND_SEQ_EVENT_NOTEON
• SND_SEQ_EVENT_KEYPRESS
• SND_SEQ_EVENT_CONTROLLER
• SND_SEQ_EVENT_PGMCHANGE
• SND_SEQ_EVENT_CHANPRESS
• SND_SEQ_EVENT_PITCHBEND
• SND_SEQ_EVENT_SYSEX
• SND_SEQ_EVENT_QFRAME
• SND_SEQ_EVENT_SONGPOS
• SND_SEQ_EVENT_SONGSEL
• SND_SEQ_EVENT_TUNE_REQUEST
• SND_SEQ_EVENT_CLOCK
• SND_SEQ_EVENT_START
• SND_SEQ_EVENT_CONTINUE
• SND_SEQ_EVENT_STOP
• SND_SEQ_EVENT_SENSING
• SND_SEQ_EVENT_RESET
• SND_SEQ_EVENT_CONTROL14
• SND_SEQ_EVENT_NONREGPARAM
• SND_SEQ_EVENT_REGPARAM

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

snd_midi_event_encode()

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]	dev	MIDI event parser.
[in]	buf	Buffer containing bytes of a raw MIDI stream.
[in]	count	Number of bytes in buf.
[out]	ev	Sequencer 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.:

• SND_SEQ_EVENT_NOTEOFF
• SND_SEQ_EVENT_NOTEON
• SND_SEQ_EVENT_KEYPRESS
• SND_SEQ_EVENT_CONTROLLER
• SND_SEQ_EVENT_PGMCHANGE
• SND_SEQ_EVENT_CHANPRESS
• SND_SEQ_EVENT_PITCHBEND
• SND_SEQ_EVENT_SYSEX
• SND_SEQ_EVENT_QFRAME
• SND_SEQ_EVENT_SONGPOS
• SND_SEQ_EVENT_SONGSEL
• SND_SEQ_EVENT_TUNE_REQUEST
• SND_SEQ_EVENT_CLOCK
• SND_SEQ_EVENT_START
• SND_SEQ_EVENT_CONTINUE
• SND_SEQ_EVENT_STOP
• SND_SEQ_EVENT_SENSING
• SND_SEQ_EVENT_RESET

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

• SND_SEQ_EVENT_CONTROL14
• SND_SEQ_EVENT_NONREGPARAM
• SND_SEQ_EVENT_REGPARAM

Conforming to:

LSB 3.2

See also

snd_midi_event_new, snd_midi_event_reset_encode, snd_midi_event_encode_byte

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]	dev	MIDI event parser.
[in]	c	A byte of a raw MIDI stream.
[out]	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.

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

snd_midi_event_free()

void snd_midi_event_free

(

snd_midi_event_t *

dev

)

Frees a MIDI event parser.

Parameters

dev	MIDI event parser.

Frees a MIDI event parser.

Conforming to:

LSB 3.2

snd_midi_event_init()

void snd_midi_event_init

(

snd_midi_event_t *

dev

)

Resets MIDI encode/decode parsers.

Parameters

dev	MIDI 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

snd_midi_event_new()

int snd_midi_event_new	(	size_t	bufsize,
		snd_midi_event_t **	rdev
	)

Creates a MIDI event parser.

Parameters

[in]	bufsize	Size of the buffer used for encoding; this should be large enough to hold the largest MIDI message to be encoded.
[out]	rdev	The 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

snd_midi_event_no_status()

void snd_midi_event_no_status	(	snd_midi_event_t *	dev,
		int	on
	)

Enables/disables MIDI command merging.

Parameters

dev	MIDI event parser.
on	0 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.

snd_midi_event_reset_decode()

void snd_midi_event_reset_decode

(

snd_midi_event_t *

dev

)

Resets MIDI decode parser.

Parameters

dev	MIDI 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

snd_midi_event_reset_encode()

void snd_midi_event_reset_encode

(

snd_midi_event_t *

dev

)

Resets MIDI encode parser.

Parameters

dev	MIDI 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

snd_midi_event_resize_buffer()

int snd_midi_event_resize_buffer	(	snd_midi_event_t *	dev,
		size_t	bufsize
	)

Resizes the MIDI message encoding buffer.

Parameters

dev	MIDI event parser.
bufsize	The 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