ALSA project - the C library reference: MIDI Sequencer

ALSA project - the C library reference

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Modules | Macros | Typedefs | Enumerations | Functions
MIDI Sequencer

## Modules
| Sequencer Client Interface
| Sequencer Port Interface
| Sequencer Port Subscription
| Sequencer Queue Interface
| Sequencer Event API
| Sequencer Miscellaneous
| Sequencer Event Type Checks
| Sequencer Event Definitions
| Sequencer Middle Level Interface
| Sequencer event <-> MIDI byte stream coder

## Macros
#define | SND_SEQ_DLSYM_VERSION _dlsym_seq_001
#define | SND_SEQ_OPEN_OUTPUT 1
#define | SND_SEQ_OPEN_INPUT 2
#define | SND_SEQ_OPEN_DUPLEX (SND_SEQ_OPEN_OUTPUT|SND_SEQ_OPEN_INPUT)
#define | SND_SEQ_NONBLOCK 0x0001
#define | SND_SEQ_ADDRESS_UNKNOWN 253
#define | SND_SEQ_ADDRESS_SUBSCRIBERS 254
#define | SND_SEQ_ADDRESS_BROADCAST 255
#define | SND_SEQ_CLIENT_SYSTEM 0
#define | snd_seq_system_info_alloca(ptr) __snd_alloca(ptr, snd_seq_system_info)

## Typedefs
typedef struct _snd_seq | snd_seq_t
typedef struct _snd_seq_system_info | snd_seq_system_info_t

## Enumerations
enum | snd_seq_type_t { SND_SEQ_TYPE_HW, SND_SEQ_TYPE_SHM, SND_SEQ_TYPE_INET }

## Functions
int | snd_seq_open (snd_seq_t **handle, const char *name, int streams, int mode)
| Open the ALSA sequencer. More...
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. More...
const char * | snd_seq_name (snd_seq_t *seq)
| get identifier of sequencer handle More...
snd_seq_type_t | snd_seq_type (snd_seq_t *seq)
| get type of sequencer handle More...
int | snd_seq_close (snd_seq_t *handle)
| Close the sequencer. More...
int | snd_seq_poll_descriptors_count (snd_seq_t *handle, short events)
| Returns the number of poll descriptors. More...
int | snd_seq_poll_descriptors (snd_seq_t *handle, struct pollfd *pfds, unsigned int space, short events)
| Get poll descriptors. More...
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 More...
int | snd_seq_nonblock (snd_seq_t *handle, int nonblock)
| Set nonblock mode. More...
int | snd_seq_client_id (snd_seq_t *handle)
| Get the client id. More...
size_t | snd_seq_get_output_buffer_size (snd_seq_t *handle)
| Return the size of output buffer. More...
size_t | snd_seq_get_input_buffer_size (snd_seq_t *handle)
| Return the size of input buffer. More...
int | snd_seq_set_output_buffer_size (snd_seq_t *handle, size_t size)
| Change the size of output buffer. More...
int | snd_seq_set_input_buffer_size (snd_seq_t *handle, size_t size)
| Resize the input buffer. More...
size_t | snd_seq_system_info_sizeof (void)
| Get size of snd_seq_system_info_t. More...
int | snd_seq_system_info_malloc (snd_seq_system_info_t **ptr)
| Allocate an empty snd_seq_system_info_t using standard malloc. More...
void | snd_seq_system_info_free (snd_seq_system_info_t *ptr)
| Frees a previously allocated snd_seq_system_info_t. More...
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. More...
int | snd_seq_system_info_get_queues (const snd_seq_system_info_t *info)
| Get maximum number of queues. More...
int | snd_seq_system_info_get_clients (const snd_seq_system_info_t *info)
| Get maximum number of clients. More...
int | snd_seq_system_info_get_ports (const snd_seq_system_info_t *info)
| Get maximum number of ports. More...
int | snd_seq_system_info_get_channels (const snd_seq_system_info_t *info)
| Get maximum number of channels. More...
int | snd_seq_system_info_get_cur_clients (const snd_seq_system_info_t *info)
| Get the current number of clients. More...
int | snd_seq_system_info_get_cur_queues (const snd_seq_system_info_t *info)
| Get the current number of queues. More...
int | snd_seq_system_info (snd_seq_t *handle, snd_seq_system_info_t *info)
| obtain the sequencer system information More...

## Detailed Description

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

## Macro Definition Documentation

#define SND_SEQ_ADDRESS_BROADCAST 255

send event to all queues/clients/ports/channels

#define SND_SEQ_ADDRESS_SUBSCRIBERS 254

send event to all subscribed ports

#define SND_SEQ_ADDRESS_UNKNOWN 253

special client (port) ids unknown source

#define SND_SEQ_CLIENT_SYSTEM 0

known client numbers system client

#define SND_SEQ_DLSYM_VERSION _dlsym_seq_001

dlsym version for interface entry callback

#define SND_SEQ_NONBLOCK 0x0001

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

#define SND_SEQ_OPEN_DUPLEX (SND_SEQ_OPEN_OUTPUT|SND_SEQ_OPEN_INPUT)

open for both input and output (read/write)

#define SND_SEQ_OPEN_INPUT 2

open for input (read)

#define SND_SEQ_OPEN_OUTPUT 1

sequencer opening stream typesopen for output (write)

#define snd_seq_system_info_alloca | ( |  | ptr | ) | __snd_alloca(ptr, snd_seq_system_info)

allocate a snd_seq_system_info_t container on stack

## Typedef Documentation

typedef struct _snd_seq_system_info snd_seq_system_info_t

system information container

typedef struct _snd_seq snd_seq_t

Sequencer handle

## Enumeration Type Documentation

enum snd_seq_type_t

sequencer handle type

Enumerator
SND_SEQ_TYPE_HW | hardware
SND_SEQ_TYPE_SHM | shared memory (NYI)
SND_SEQ_TYPE_INET | network (NYI)

## Function Documentation

int snd_seq_client_id | ( | snd_seq_t * | seq | ) |

Get the client id.

Parameters

  seq | sequencer handle

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

See Also
  snd_seq_open()

int snd_seq_close | ( | snd_seq_t * | seq | ) |

Close the sequencer.

Parameters

  seq | Handle returned from snd_seq_open()

Returns
  0 on success otherwise a negative error code

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.

See Also
  snd_seq_close()

size_t snd_seq_get_input_buffer_size | ( | snd_seq_t * | seq | ) |

Return the size of input buffer.

Parameters

  seq | sequencer handle

Returns
  the size of input buffer in bytes

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

See Also
  snd_seq_set_input_buffer_size()

size_t snd_seq_get_output_buffer_size | ( | snd_seq_t * | seq | ) |

Return the size of output buffer.

Parameters

  seq | sequencer handle

Returns
  the size of output buffer in bytes

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

See Also
  snd_seq_set_output_buffer_size()

const char* snd_seq_name | ( | snd_seq_t * | seq | ) |

get identifier of sequencer handle

Parameters

  seq | sequencer handle

Returns
  ASCII identifier of sequencer handle

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

See Also
  snd_seq_open()

int snd_seq_nonblock | ( | snd_seq_t * | seq,
|  | int | nonblock
| ) |  |

Set nonblock mode.

Parameters

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

Returns
  0 on success otherwise a negative error code

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.

See Also
  snd_seq_open()

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

Open the ALSA sequencer.

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: SND_SEQ_OPEN_OUTPUT - open the sequencer for output only SND_SEQ_OPEN_INPUT - open the sequencer for input only SND_SEQ_OPEN_DUPLEX - open the sequencer for output and input

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.

Parameters

  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

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.

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 ** | seqp,
|  | const char * | name,
|  | int | streams,
|  | int | mode,
|  | snd_config_t * | lconf
| ) |  |

Open the ALSA sequencer using local configuration.

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 the snd_seq_open() function for further details. The extension is that the given configuration is used to resolve abstract name.

See Also
  snd_seq_open()

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

Get poll descriptors.

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

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.

See Also
  snd_seq_poll_descriptors_count(), snd_seq_poll_descriptors_revents()

int snd_seq_poll_descriptors_count | ( | snd_seq_t * | seq,
|  | short | events
| ) |  |

Returns the number of poll descriptors.

Parameters

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

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`

See Also
  snd_seq_poll_descriptors()

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_set_input_buffer_size | ( | snd_seq_t * | seq,
|  | size_t | size
| ) |  |

Resize the 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

Changes the size of input buffer.

See Also
  snd_seq_get_input_buffer_size()

int snd_seq_set_output_buffer_size | ( | snd_seq_t * | seq,
|  | size_t | size
| ) |  |

Change 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

Changes the size of output buffer.

See Also
  snd_seq_get_output_buffer_size()

int snd_seq_system_info | ( | snd_seq_t * | seq,
|  | snd_seq_system_info_t * | info
| ) |  |

obtain the sequencer system information

Parameters

  seq | sequencer handle
  info | the pointer to be stored

Returns
  0 on success otherwise a negative error code

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

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

void snd_seq_system_info_free | ( | snd_seq_system_info_t * | obj | ) |

Frees a previously allocated snd_seq_system_info_t.

Parameters

  obj | pointer to object to free

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_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_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_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_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_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

size_t snd_seq_system_info_sizeof | ( | void |  | ) |

Get size of snd_seq_system_info_t.

Returns
  size in bytes

snd_seq_type_t snd_seq_type | ( | snd_seq_t * | seq | ) |

get type of sequencer handle

Parameters

  seq | sequencer handle

Returns
  type of sequencer handle

Returns the type snd_seq_type_t of the given sequencer handle.

See Also
  snd_seq_open()