MIDI Sequencer

Overview

MIDI Sequencer Interface. More…

// typedefs

typedef struct _snd_seq snd_seq_t;
typedef struct _snd_seq_system_info snd_seq_system_info_t;

// enums

enum snd_seq_type_t;

// global functions

int
snd_seq_open(
    snd_seq_t** handle,
    const char* name,
    int streams,
    int mode
);

int
snd_seq_open_lconf(
    snd_seq_t** handle,
    const char* name,
    int streams,
    int mode,
    snd_config_t* lconf
);

const char*
snd_seq_name(snd_seq_t* seq);

snd_seq_type_t
snd_seq_type(snd_seq_t* seq);

int
snd_seq_close(snd_seq_t* handle);

int
snd_seq_poll_descriptors_count(
    snd_seq_t* handle,
    short events
);

int
snd_seq_poll_descriptors(
    snd_seq_t* handle,
    struct pollfd* pfds,
    unsigned int space,
    short events
);

int
snd_seq_poll_descriptors_revents(
    snd_seq_t* seq,
    struct pollfd* pfds,
    unsigned int nfds,
    unsigned short* revents
);

int
snd_seq_nonblock(
    snd_seq_t* handle,
    int nonblock
);

int
snd_seq_client_id(snd_seq_t* handle);

size_t
snd_seq_get_output_buffer_size(snd_seq_t* handle);

size_t
snd_seq_get_input_buffer_size(snd_seq_t* handle);

int
snd_seq_set_output_buffer_size(
    snd_seq_t* handle,
    size_t size
);

int
snd_seq_set_input_buffer_size(
    snd_seq_t* handle,
    size_t size
);

size_t
snd_seq_system_info_sizeof(void);

int
snd_seq_system_info_malloc(snd_seq_system_info_t** ptr);

void
snd_seq_system_info_free(snd_seq_system_info_t* ptr);

void
snd_seq_system_info_copy(
    snd_seq_system_info_t* dst,
    const snd_seq_system_info_t* src
);

int
snd_seq_system_info_get_queues(const snd_seq_system_info_t* info);

int
snd_seq_system_info_get_clients(const snd_seq_system_info_t* info);

int
snd_seq_system_info_get_ports(const snd_seq_system_info_t* info);

int
snd_seq_system_info_get_channels(const snd_seq_system_info_t* info);

int
snd_seq_system_info_get_cur_clients(const snd_seq_system_info_t* info);

int
snd_seq_system_info_get_cur_queues(const snd_seq_system_info_t* info);

int
snd_seq_system_info(
    snd_seq_t* handle,
    snd_seq_system_info_t* info
);

// macros

#define SND_SEQ_ADDRESS_BROADCAST
#define SND_SEQ_ADDRESS_SUBSCRIBERS
#define SND_SEQ_ADDRESS_UNKNOWN
#define SND_SEQ_CLIENT_SYSTEM
#define SND_SEQ_DLSYM_VERSION
#define SND_SEQ_NONBLOCK
#define SND_SEQ_OPEN_DUPLEX
#define SND_SEQ_OPEN_INPUT
#define SND_SEQ_OPEN_OUTPUT
#define snd_seq_system_info_alloca(ptr)

Detailed Documentation

MIDI Sequencer Interface. See Sequencer interface page for more details.

Typedefs

typedef struct _snd_seq snd_seq_t

Sequencer handle

typedef struct _snd_seq_system_info snd_seq_system_info_t

system information container

Global Functions

int
snd_seq_open(
    snd_seq_t** handle,
    const char* name,
    int streams,
    int mode
)

Open the ALSA sequencer.

Note

Internally, these are translated to O_WRONLY, O_RDONLY and O_RDWR respectively and used as the second argument to the C library open() call.

Creates a new handle and opens a connection to the kernel sequencer interface. After a client is created successfully, an event with SND_SEQ_EVENT_CLIENT_START is broadcast to announce port.

Parameters:

seqp Pointer to a snd_seq_t pointer. This pointer must be kept and passed to most of the other sequencer functions.
name The sequencer’s “name”. This is not a name you make up for your own purposes; it has special significance to the ALSA library. Usually you need to pass "default" here.
streams

The read/write mode of the sequencer. Can be one of three values:

mode Optional modifier. Can be either 0, or SND_SEQ_NONBLOCK, which will make read/write operations non-blocking. This can also be set later using snd_seq_nonblock().

Returns:

0 on success otherwise a negative error code

See also:

snd_seq_open_lconf(), snd_seq_close(), snd_seq_type(), snd_seq_name(), snd_seq_nonblock(), snd_seq_client_id()

int
snd_seq_open_lconf(
    snd_seq_t** handle,
    const char* name,
    int streams,
    int mode,
    snd_config_t* lconf
)

Open the ALSA sequencer using local configuration.

See the snd_seq_open() function for further details. The extension is that the given configuration is used to resolve abstract name.

Parameters:

seqp Pointer to a snd_seq_t pointer.
name The name to open
streams The read/write mode of the sequencer.
mode Optional modifier
lconf Local configuration

Returns:

0 on success otherwise a negative error code

See also:

snd_seq_open()

const char*
snd_seq_name(snd_seq_t* seq)

get identifier of sequencer handle

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

Parameters:

seq sequencer handle

Returns:

ASCII identifier of sequencer handle

See also:

snd_seq_open()

snd_seq_type_t
snd_seq_type(snd_seq_t* seq)

get type of sequencer handle

Returns the type snd_seq_type_t of the given sequencer handle.

Parameters:

seq sequencer handle

Returns:

type of sequencer handle

See also:

snd_seq_open()

int
snd_seq_close(snd_seq_t* handle)

Close the sequencer.

Closes the sequencer client and releases its resources. After a client is closed, an event with SND_SEQ_EVENT_CLIENT_EXIT is broadcast to announce port. The connection between other clients are disconnected. Call this just before exiting your program.

Parameters:

seq Handle returned from snd_seq_open()

Returns:

0 on success otherwise a negative error code

See also:

snd_seq_close()

int
snd_seq_poll_descriptors_count(
    snd_seq_t* handle,
    short events
)

Returns the number of poll descriptors.

Get the number of poll descriptors. The polling events to be checked can be specified by the second argument. When both input and output are checked, pass POLLIN|POLLOUT

Parameters:

seq sequencer handle
events the poll events to be checked (POLLIN and POLLOUT)

Returns:

the number of poll descriptors.

See also:

snd_seq_poll_descriptors()

int
snd_seq_poll_descriptors(
    snd_seq_t* handle,
    struct pollfd* pfds,
    unsigned int space,
    short events
)

Get poll descriptors.

Get poll descriptors assigned to the sequencer handle. Since a sequencer handle can duplex streams, you need to set which direction(s) is/are polled in events argument. When POLLIN bit is specified, the incoming events to the ports are checked.

To check the returned poll-events, call snd_seq_poll_descriptors_revents() instead of reading the pollfd structs directly.

Parameters:

seq sequencer handle
pfds array of poll descriptors
space space in the poll descriptor array
events polling events to be checked (POLLIN and POLLOUT)

Returns:

count of filled descriptors

See also:

snd_seq_poll_descriptors_count(), snd_seq_poll_descriptors_revents()

int
snd_seq_poll_descriptors_revents(
    snd_seq_t* seq,
    struct pollfd* pfds,
    unsigned int nfds,
    unsigned short* revents
)

get returned events from poll descriptors

Parameters:

seq sequencer handle
pfds array of poll descriptors
nfds count of poll descriptors
revents returned events

Returns:

zero if success, otherwise a negative error code

See also:

snd_seq_poll_descriptors()

int
snd_seq_nonblock(
    snd_seq_t* handle,
    int nonblock
)

Set nonblock mode.

Change the blocking mode of the given client. In block mode, the client falls into sleep when it fills the output memory pool with full events. The client will be woken up after a certain amount of free space becomes available.

Parameters:

seq sequencer handle
nonblock 0 = block, 1 = nonblock mode

Returns:

0 on success otherwise a negative error code

See also:

snd_seq_open()

int
snd_seq_client_id(snd_seq_t* handle)

Get the client id.

Returns the id of the specified client. If an error occurs, function returns the negative error code. A client id is necessary to inquiry or to set the client information. A user client is assigned from 128 to 191.

Parameters:

seq sequencer handle

Returns:

the client id

See also:

snd_seq_open()

size_t
snd_seq_get_output_buffer_size(snd_seq_t* handle)

Return the size of output buffer.

Obtains the size of output buffer. This buffer is used to store decoded byte-stream of output events before transferring to sequencer.

Parameters:

seq sequencer handle

Returns:

the size of output buffer in bytes

See also:

snd_seq_set_output_buffer_size()

size_t
snd_seq_get_input_buffer_size(snd_seq_t* handle)

Return the size of input buffer.

Obtains the size of input buffer. This buffer is used to read byte-stream of input events from sequencer.

Parameters:

seq sequencer handle

Returns:

the size of input buffer in bytes

See also:

snd_seq_set_input_buffer_size()

int
snd_seq_set_output_buffer_size(
    snd_seq_t* handle,
    size_t size
)

Change the size of output buffer.

Changes the size of output buffer.

Parameters:

seq sequencer handle
size the size of output buffer to be changed in bytes

Returns:

0 on success otherwise a negative error code

See also:

snd_seq_get_output_buffer_size()

int
snd_seq_set_input_buffer_size(
    snd_seq_t* handle,
    size_t size
)

Resize the input buffer.

Changes the size of input buffer.

Parameters:

seq sequencer handle
size the size of input buffer to be changed in bytes

Returns:

0 on success otherwise a negative error code

See also:

snd_seq_get_input_buffer_size()

size_t
snd_seq_system_info_sizeof(void)

Get size of snd_seq_system_info_t.

Returns:

size in bytes

int
snd_seq_system_info_malloc(snd_seq_system_info_t** ptr)

Allocate an empty snd_seq_system_info_t using standard malloc.

Parameters:

ptr returned pointer

Returns:

0 on success otherwise negative error code

void
snd_seq_system_info_free(snd_seq_system_info_t* ptr)

Frees a previously allocated snd_seq_system_info_t.

Parameters:

obj pointer to object to free
void
snd_seq_system_info_copy(
    snd_seq_system_info_t* dst,
    const snd_seq_system_info_t* src
)

Copy one snd_seq_system_info_t to another.

Parameters:

dst pointer to destination
src pointer to source
int
snd_seq_system_info_get_queues(const snd_seq_system_info_t* info)

Get maximum number of queues.

Parameters:

info snd_seq_system_info_t container

Returns:

maximum number of queues

See also:

snd_seq_system_info()

int
snd_seq_system_info_get_clients(const snd_seq_system_info_t* info)

Get maximum number of clients.

Parameters:

info snd_seq_system_info_t container

Returns:

maximum number of clients

See also:

snd_seq_system_info()

int
snd_seq_system_info_get_ports(const snd_seq_system_info_t* info)

Get maximum number of ports.

Parameters:

info snd_seq_system_info_t container

Returns:

maximum number of ports

See also:

snd_seq_system_info()

int
snd_seq_system_info_get_channels(const snd_seq_system_info_t* info)

Get maximum number of channels.

Parameters:

info snd_seq_system_info_t container

Returns:

maximum number of channels

See also:

snd_seq_system_info()

int
snd_seq_system_info_get_cur_clients(const snd_seq_system_info_t* info)

Get the current number of clients.

Parameters:

info snd_seq_system_info_t container

Returns:

current number of clients

See also:

snd_seq_system_info()

int
snd_seq_system_info_get_cur_queues(const snd_seq_system_info_t* info)

Get the current number of queues.

Parameters:

info snd_seq_system_info_t container

Returns:

current number of queues

See also:

snd_seq_system_info()

int
snd_seq_system_info(
    snd_seq_t* handle,
    snd_seq_system_info_t* info
)

obtain the sequencer system information

Stores the global system information of ALSA sequencer system. The returned data contains the maximum available numbers of queues, clients, ports and channels.

Parameters:

seq sequencer handle
info the pointer to be stored

Returns:

0 on success otherwise a negative error code

Macros

#define SND_SEQ_ADDRESS_BROADCAST

send event to all queues/clients/ports/channels

#define SND_SEQ_ADDRESS_SUBSCRIBERS

send event to all subscribed ports

#define SND_SEQ_ADDRESS_UNKNOWN

special client (port) ids unknown source

#define SND_SEQ_CLIENT_SYSTEM

known client numbers system client

#define SND_SEQ_DLSYM_VERSION

dlsym version for interface entry callback

#define SND_SEQ_NONBLOCK

sequencer opening modenon-blocking mode (flag to open mode)

#define SND_SEQ_OPEN_DUPLEX

open for both input and output (read/write)

#define SND_SEQ_OPEN_INPUT

open for input (read)

#define SND_SEQ_OPEN_OUTPUT

sequencer opening stream typesopen for output (write)

#define snd_seq_system_info_alloca(ptr)

allocate a snd_seq_system_info_t container on stack