ALSA project - the C library reference: Sequencer Port Interface

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
Macros | Typedefs | Functions
Sequencer Port Interface
MIDI Sequencer

## Macros
#define | SND_SEQ_PORT_SYSTEM_TIMER 0
#define | SND_SEQ_PORT_SYSTEM_ANNOUNCE 1
#define | SND_SEQ_PORT_CAP_READ (1<<0)
#define | SND_SEQ_PORT_CAP_WRITE (1<<1)
#define | SND_SEQ_PORT_CAP_SYNC_READ (1<<2)
#define | SND_SEQ_PORT_CAP_SYNC_WRITE (1<<3)
#define | SND_SEQ_PORT_CAP_DUPLEX (1<<4)
#define | SND_SEQ_PORT_CAP_SUBS_READ (1<<5)
#define | SND_SEQ_PORT_CAP_SUBS_WRITE (1<<6)
#define | SND_SEQ_PORT_CAP_NO_EXPORT (1<<7)
#define | SND_SEQ_PORT_TYPE_SPECIFIC (1<<0)
#define | SND_SEQ_PORT_TYPE_MIDI_GENERIC (1<<1)
#define | SND_SEQ_PORT_TYPE_MIDI_GM (1<<2)
#define | SND_SEQ_PORT_TYPE_MIDI_GS (1<<3)
#define | SND_SEQ_PORT_TYPE_MIDI_XG (1<<4)
#define | SND_SEQ_PORT_TYPE_MIDI_MT32 (1<<5)
#define | SND_SEQ_PORT_TYPE_MIDI_GM2 (1<<6)
#define | SND_SEQ_PORT_TYPE_SYNTH (1<<10)
#define | SND_SEQ_PORT_TYPE_DIRECT_SAMPLE (1<<11)
#define | SND_SEQ_PORT_TYPE_SAMPLE (1<<12)
#define | SND_SEQ_PORT_TYPE_HARDWARE (1<<16)
#define | SND_SEQ_PORT_TYPE_SOFTWARE (1<<17)
#define | SND_SEQ_PORT_TYPE_SYNTHESIZER (1<<18)
#define | SND_SEQ_PORT_TYPE_PORT (1<<19)
#define | SND_SEQ_PORT_TYPE_APPLICATION (1<<20)
#define | snd_seq_port_info_alloca(ptr) __snd_alloca(ptr, snd_seq_port_info)

## Typedefs
typedef struct _snd_seq_port_info | snd_seq_port_info_t

## Functions
size_t | snd_seq_port_info_sizeof (void)
| get size of snd_seq_port_info_t More...
int | snd_seq_port_info_malloc (snd_seq_port_info_t **ptr)
| allocate an empty snd_seq_port_info_t using standard malloc More...
void | snd_seq_port_info_free (snd_seq_port_info_t *ptr)
| frees a previously allocated snd_seq_port_info_t More...
void | snd_seq_port_info_copy (snd_seq_port_info_t *dst, const snd_seq_port_info_t *src)
| copy one snd_seq_port_info_t to another More...
int | snd_seq_port_info_get_client (const snd_seq_port_info_t *info)
| Get client id of a port_info container. More...
int | snd_seq_port_info_get_port (const snd_seq_port_info_t *info)
| Get port id of a port_info container. More...
const snd_seq_addr_t * | snd_seq_port_info_get_addr (const snd_seq_port_info_t *info)
| Get client/port address of a port_info container. More...
const char * | snd_seq_port_info_get_name (const snd_seq_port_info_t *info)
| Get the name of a port_info container. More...
unsigned int | snd_seq_port_info_get_capability (const snd_seq_port_info_t *info)
| Get the capability bits of a port_info container. More...
unsigned int | snd_seq_port_info_get_type (const snd_seq_port_info_t *info)
| Get the type bits of a port_info container. More...
int | snd_seq_port_info_get_midi_channels (const snd_seq_port_info_t *info)
| Get the midi channels of a port_info container. More...
int | snd_seq_port_info_get_midi_voices (const snd_seq_port_info_t *info)
| Get the midi voices of a port_info container. More...
int | snd_seq_port_info_get_synth_voices (const snd_seq_port_info_t *info)
| Get the synth voices of a port_info container. More...
int | snd_seq_port_info_get_read_use (const snd_seq_port_info_t *info)
| Get the number of read subscriptions of a port_info container. More...
int | snd_seq_port_info_get_write_use (const snd_seq_port_info_t *info)
| Get the number of write subscriptions of a port_info container. More...
int | snd_seq_port_info_get_port_specified (const snd_seq_port_info_t *info)
| Get the port-specified mode of a port_info container. More...
int | snd_seq_port_info_get_timestamping (const snd_seq_port_info_t *info)
| Get the time-stamping mode of the given port in a port_info container. More...
int | snd_seq_port_info_get_timestamp_real (const snd_seq_port_info_t *info)
| Get whether the time-stamping of the given port is real-time mode. More...
int | snd_seq_port_info_get_timestamp_queue (const snd_seq_port_info_t *info)
| Get the queue id to update timestamps. More...
void | snd_seq_port_info_set_client (snd_seq_port_info_t *info, int client)
| Set the client id of a port_info container. More...
void | snd_seq_port_info_set_port (snd_seq_port_info_t *info, int port)
| Set the port id of a port_info container. More...
void | snd_seq_port_info_set_addr (snd_seq_port_info_t *info, const snd_seq_addr_t *addr)
| Set the client/port address of a port_info container. More...
void | snd_seq_port_info_set_name (snd_seq_port_info_t *info, const char *name)
| Set the name of a port_info container. More...
void | snd_seq_port_info_set_capability (snd_seq_port_info_t *info, unsigned int capability)
| set the capability bits of a port_info container More...
void | snd_seq_port_info_set_type (snd_seq_port_info_t *info, unsigned int type)
| Get the type bits of a port_info container. More...
void | snd_seq_port_info_set_midi_channels (snd_seq_port_info_t *info, int channels)
| set the midi channels of a port_info container More...
void | snd_seq_port_info_set_midi_voices (snd_seq_port_info_t *info, int voices)
| set the midi voices of a port_info container More...
void | snd_seq_port_info_set_synth_voices (snd_seq_port_info_t *info, int voices)
| set the synth voices of a port_info container More...
void | snd_seq_port_info_set_port_specified (snd_seq_port_info_t *info, int val)
| Set the port-specified mode of a port_info container. More...
void | snd_seq_port_info_set_timestamping (snd_seq_port_info_t *info, int enable)
| Set the time-stamping mode of the given port. More...
void | snd_seq_port_info_set_timestamp_real (snd_seq_port_info_t *info, int realtime)
| Set whether the timestime is updated in the real-time mode. More...
void | snd_seq_port_info_set_timestamp_queue (snd_seq_port_info_t *info, int queue)
| Set the queue id for timestamping. More...
int | snd_seq_create_port (snd_seq_t *handle, snd_seq_port_info_t *info)
| create a sequencer port on the current client More...
int | snd_seq_delete_port (snd_seq_t *handle, int port)
| delete a sequencer port on the current client More...
int | snd_seq_get_port_info (snd_seq_t *handle, int port, snd_seq_port_info_t *info)
| obtain the information of a port on the current client More...
int | snd_seq_get_any_port_info (snd_seq_t *handle, int client, int port, snd_seq_port_info_t *info)
| obtain the information of a port on an arbitrary client More...
int | snd_seq_set_port_info (snd_seq_t *handle, int port, snd_seq_port_info_t *info)
| set the information of a port on the current client More...
int | snd_seq_query_next_port (snd_seq_t *handle, snd_seq_port_info_t *info)
| query the next matching port More...

## Detailed Description

Sequencer Port Interface

## Macro Definition Documentation

#define SND_SEQ_PORT_CAP_DUPLEX (1<<4)

allow read/write duplex

#define SND_SEQ_PORT_CAP_NO_EXPORT (1<<7)

routing not allowed

#define SND_SEQ_PORT_CAP_READ (1<<0)

port capabilities (32 bits) readable from this port

#define SND_SEQ_PORT_CAP_SUBS_READ (1<<5)

allow read subscription

#define SND_SEQ_PORT_CAP_SUBS_WRITE (1<<6)

allow write subscription

#define SND_SEQ_PORT_CAP_SYNC_READ (1<<2)

allow read subscriptions

#define SND_SEQ_PORT_CAP_SYNC_WRITE (1<<3)

allow write subscriptions

#define SND_SEQ_PORT_CAP_WRITE (1<<1)

writable to this port

#define snd_seq_port_info_alloca | ( |  | ptr | ) | __snd_alloca(ptr, snd_seq_port_info)

allocate a snd_seq_port_info_t container on stack

#define SND_SEQ_PORT_SYSTEM_ANNOUNCE 1

system announce port

#define SND_SEQ_PORT_SYSTEM_TIMER 0

known port numbers system timer port

#define SND_SEQ_PORT_TYPE_APPLICATION (1<<20)

This port belongs to an application, such as a sequencer or editor.

#define SND_SEQ_PORT_TYPE_DIRECT_SAMPLE (1<<11)

Instruments can be downloaded to this port (with SND_SEQ_EVENT_INSTR_xxx messages sent directly).

#define SND_SEQ_PORT_TYPE_HARDWARE (1<<16)

This port is implemented in hardware.

#define SND_SEQ_PORT_TYPE_MIDI_GENERIC (1<<1)

This port understands MIDI messages.

#define SND_SEQ_PORT_TYPE_MIDI_GM (1<<2)

This port is compatible with the General MIDI specification.

#define SND_SEQ_PORT_TYPE_MIDI_GM2 (1<<6)

This port is compatible with the General MIDI 2 specification.

#define SND_SEQ_PORT_TYPE_MIDI_GS (1<<3)

This port is compatible with the Roland GS standard.

#define SND_SEQ_PORT_TYPE_MIDI_MT32 (1<<5)

This port is compatible with the Roland MT-32.

#define SND_SEQ_PORT_TYPE_MIDI_XG (1<<4)

This port is compatible with the Yamaha XG specification.

#define SND_SEQ_PORT_TYPE_PORT (1<<19)

This port may connect to other devices (whose characteristics are not known).

#define SND_SEQ_PORT_TYPE_SAMPLE (1<<12)

Instruments can be downloaded to this port (with SND_SEQ_EVENT_INSTR_xxx messages sent directly or through a queue).

#define SND_SEQ_PORT_TYPE_SOFTWARE (1<<17)

This port is implemented in software.

#define SND_SEQ_PORT_TYPE_SPECIFIC (1<<0)

Messages sent from/to this port have device-specific semantics.

#define SND_SEQ_PORT_TYPE_SYNTH (1<<10)

This port understands SND_SEQ_EVENT_SAMPLE_xxx messages (these are not MIDI messages).

#define SND_SEQ_PORT_TYPE_SYNTHESIZER (1<<18)

Messages sent to this port will generate sounds.

## Typedef Documentation

typedef struct _snd_seq_port_info snd_seq_port_info_t

port information container

## Function Documentation

int snd_seq_create_port | ( | snd_seq_t * | seq,
|  | snd_seq_port_info_t * | port
| ) |  |

create a sequencer port on the current client

Parameters

  seq | sequencer handle
  port | port information for the new port

Returns
  0 on success otherwise a negative error code

Creates a sequencer port on the current client. The attributes of created port is specified in info argument.

The client field in info argument is overwritten with the current client id. The port id to be created can be specified via snd_seq_port_info_set_port_specified. You can get the created port id by reading the port pointer via snd_seq_port_info_get_port.

Each port has the capability bit-masks to specify the access capability of the port from other clients. The capability bit flags are defined as follows:

- SND_SEQ_PORT_CAP_READ Readable from this port
- SND_SEQ_PORT_CAP_WRITE Writable to this port.
- SND_SEQ_PORT_CAP_SYNC_READ For synchronization (not implemented)
- SND_SEQ_PORT_CAP_SYNC_WRITE For synchronization (not implemented)
- SND_SEQ_PORT_CAP_DUPLEX Read/write duplex access is supported
- SND_SEQ_PORT_CAP_SUBS_READ Read subscription is allowed
- SND_SEQ_PORT_CAP_SUBS_WRITE Write subscription is allowed
- SND_SEQ_PORT_CAP_NO_EXPORT Subscription management from 3rd client is disallowed

Each port has also the type bitmasks defined as follows:

- SND_SEQ_PORT_TYPE_SPECIFIC Hardware specific port
- SND_SEQ_PORT_TYPE_MIDI_GENERIC Generic MIDI device
- SND_SEQ_PORT_TYPE_MIDI_GM General MIDI compatible device
- SND_SEQ_PORT_TYPE_MIDI_GM2 General MIDI 2 compatible device
- SND_SEQ_PORT_TYPE_MIDI_GS GS compatible device
- SND_SEQ_PORT_TYPE_MIDI_XG XG compatible device
- SND_SEQ_PORT_TYPE_MIDI_MT32 MT-32 compatible device
- SND_SEQ_PORT_TYPE_HARDWARE Implemented in hardware
- SND_SEQ_PORT_TYPE_SOFTWARE Implemented in software
- SND_SEQ_PORT_TYPE_SYNTHESIZER Generates sound
- SND_SEQ_PORT_TYPE_PORT Connects to other device(s)
- SND_SEQ_PORT_TYPE_APPLICATION Application (sequencer/editor)

A port may contain specific midi channels, midi voices and synth voices. These values could be zero as default.

See Also
  snd_seq_delete_port(), snd_seq_get_port_info(), snd_seq_create_simple_port()

int snd_seq_delete_port | ( | snd_seq_t * | seq,
|  | int | port
| ) |  |

delete a sequencer port on the current client

Parameters

  seq | sequencer handle
  port | port to be deleted

Returns
  0 on success otherwise a negative error code

Deletes the existing sequencer port on the current client.

See Also
  snd_seq_create_port(), snd_seq_delete_simple_port()

int snd_seq_get_any_port_info | ( | snd_seq_t * | seq,
|  | int | client,
|  | int | port,
|  | snd_seq_port_info_t * | info
| ) |  |

obtain the information of a port on an arbitrary client

Parameters

  seq | sequencer handle
  client | client id to get
  port | port id to get
  info | pointer information returns

Returns
  0 on success otherwise a negative error code

See Also
  snd_seq_get_port_info()

int snd_seq_get_port_info | ( | snd_seq_t * | seq,
|  | int | port,
|  | snd_seq_port_info_t * | info
| ) |  |

obtain the information of a port on the current client

Parameters

  seq | sequencer handle
  port | port id to get
  info | pointer information returns

Returns
  0 on success otherwise a negative error code

See Also
  snd_seq_create_port(), snd_seq_get_any_port_info(), snd_seq_set_port_info(), snd_seq_query_next_port()

void snd_seq_port_info_copy | ( | snd_seq_port_info_t * | dst,
|  | const snd_seq_port_info_t * | src
| ) |  |

copy one snd_seq_port_info_t to another

Parameters

  dst | pointer to destination
  src | pointer to source

void snd_seq_port_info_free | ( | snd_seq_port_info_t * | obj | ) |

frees a previously allocated snd_seq_port_info_t

Parameters

  obj | pointer to object to free

const snd_seq_addr_t* snd_seq_port_info_get_addr | ( | const snd_seq_port_info_t * | info | ) |

Get client/port address of a port_info container.

Parameters

  info | port_info container

Returns
  client/port address pointer

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_addr()

unsigned int snd_seq_port_info_get_capability | ( | const snd_seq_port_info_t * | info | ) |

Get the capability bits of a port_info container.

Parameters

  info | port_info container

Returns
  capability bits

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_capability()

int snd_seq_port_info_get_client | ( | const snd_seq_port_info_t * | info | ) |

Get client id of a port_info container.

Parameters

  info | port_info container

Returns
  client id

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_client()

int snd_seq_port_info_get_midi_channels | ( | const snd_seq_port_info_t * | info | ) |

Get the midi channels of a port_info container.

Parameters

  info | port_info container

Returns
  number of midi channels (default 0)

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_midi_channels()

int snd_seq_port_info_get_midi_voices | ( | const snd_seq_port_info_t * | info | ) |

Get the midi voices of a port_info container.

Parameters

  info | port_info container

Returns
  number of midi voices (default 0)

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_midi_voices()

const char* snd_seq_port_info_get_name | ( | const snd_seq_port_info_t * | info | ) |

Get the name of a port_info container.

Parameters

  info | port_info container

Returns
  name string

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_name()

int snd_seq_port_info_get_port | ( | const snd_seq_port_info_t * | info | ) |

Get port id of a port_info container.

Parameters

  info | port_info container

Returns
  port id

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_port()

int snd_seq_port_info_get_port_specified | ( | const snd_seq_port_info_t * | info | ) |

Get the port-specified mode of a port_info container.

Parameters

  info | port_info container

Returns
  1 if port id is specified at creation

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_port_specified()

int snd_seq_port_info_get_read_use | ( | const snd_seq_port_info_t * | info | ) |

Get the number of read subscriptions of a port_info container.

Parameters

  info | port_info container

Returns
  number of read subscriptions

See Also
  snd_seq_get_port_info()

int snd_seq_port_info_get_synth_voices | ( | const snd_seq_port_info_t * | info | ) |

Get the synth voices of a port_info container.

Parameters

  info | port_info container

Returns
  number of synth voices (default 0)

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_synth_voices()

int snd_seq_port_info_get_timestamp_queue | ( | const snd_seq_port_info_t * | info | ) |

Get the queue id to update timestamps.

Parameters

  info | port_info container

Returns
  the queue id to get the timestamps

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_timestamp_queue()

int snd_seq_port_info_get_timestamp_real | ( | const snd_seq_port_info_t * | info | ) |

Get whether the time-stamping of the given port is real-time mode.

Parameters

  info | port_info container

Returns
  1 if the time-stamping is in the real-time mode

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_timestamp_real()

int snd_seq_port_info_get_timestamping | ( | const snd_seq_port_info_t * | info | ) |

Get the time-stamping mode of the given port in a port_info container.

Parameters

  info | port_info container

Returns
  1 if the port updates timestamps of incoming events

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_timestamping()

unsigned int snd_seq_port_info_get_type | ( | const snd_seq_port_info_t * | info | ) |

Get the type bits of a port_info container.

Parameters

  info | port_info container

Returns
  port type bits

See Also
  snd_seq_get_port_info(), snd_seq_port_info_set_type()

int snd_seq_port_info_get_write_use | ( | const snd_seq_port_info_t * | info | ) |

Get the number of write subscriptions of a port_info container.

Parameters

  info | port_info container

Returns
  number of write subscriptions

See Also
  snd_seq_get_port_info()

int snd_seq_port_info_malloc | ( | snd_seq_port_info_t ** | ptr | ) |

allocate an empty snd_seq_port_info_t using standard malloc

Parameters

  ptr | returned pointer

Returns
  0 on success otherwise negative error code

void snd_seq_port_info_set_addr | ( | snd_seq_port_info_t * | info,
|  | const snd_seq_addr_t * | addr
| ) |  |

Set the client/port address of a port_info container.

Parameters

  info | port_info container
  addr | client/port address

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_addr()

void snd_seq_port_info_set_capability | ( | snd_seq_port_info_t * | info,
|  | unsigned int | capability
| ) |  |

set the capability bits of a port_info container

Parameters

  info | port_info container
  capability | capability bits

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_capability()

void snd_seq_port_info_set_client | ( | snd_seq_port_info_t * | info,
|  | int | client
| ) |  |

Set the client id of a port_info container.

Parameters

  info | port_info container
  client | client id

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_client()

void snd_seq_port_info_set_midi_channels | ( | snd_seq_port_info_t * | info,
|  | int | channels
| ) |  |

set the midi channels of a port_info container

Parameters

  info | port_info container
  channels | midi channels (default 0)

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_midi_channels()

void snd_seq_port_info_set_midi_voices | ( | snd_seq_port_info_t * | info,
|  | int | voices
| ) |  |

set the midi voices of a port_info container

Parameters

  info | port_info container
  voices | midi voices (default 0)

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_midi_voices()

void snd_seq_port_info_set_name | ( | snd_seq_port_info_t * | info,
|  | const char * | name
| ) |  |

Set the name of a port_info container.

Parameters

  info | port_info container
  name | name string

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_name()

void snd_seq_port_info_set_port | ( | snd_seq_port_info_t * | info,
|  | int | port
| ) |  |

Set the port id of a port_info container.

Parameters

  info | port_info container
  port | port id

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_port()

void snd_seq_port_info_set_port_specified | ( | snd_seq_port_info_t * | info,
|  | int | val
| ) |  |

Set the port-specified mode of a port_info container.

Parameters

  info | port_info container
  val | non-zero if specifying the port id at creation

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_port_specified()

void snd_seq_port_info_set_synth_voices | ( | snd_seq_port_info_t * | info,
|  | int | voices
| ) |  |

set the synth voices of a port_info container

Parameters

  info | port_info container
  voices | synth voices (default 0)

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_synth_voice()

void snd_seq_port_info_set_timestamp_queue | ( | snd_seq_port_info_t * | info,
|  | int | queue
| ) |  |

Set the queue id for timestamping.

Parameters

  info | port_info container
  queue | the queue id to get timestamps

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_timestamp_queue()

void snd_seq_port_info_set_timestamp_real | ( | snd_seq_port_info_t * | info,
|  | int | enable
| ) |  |

Set whether the timestime is updated in the real-time mode.

Parameters

  info | port_info container
  enable | non-zero if updating the timestamps in real-time mode

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_timestamp_real()

void snd_seq_port_info_set_timestamping | ( | snd_seq_port_info_t * | info,
|  | int | enable
| ) |  |

Set the time-stamping mode of the given port.

Parameters

  info | port_info container
  enable | non-zero if updating the timestamps of incoming events

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_timestamping()

void snd_seq_port_info_set_type | ( | snd_seq_port_info_t * | info,
|  | unsigned int | type
| ) |  |

Get the type bits of a port_info container.

Parameters

  info | port_info container
  type | port type bits

See Also
  snd_seq_get_port_info(), snd_seq_port_info_get_type()

size_t snd_seq_port_info_sizeof | ( | void |  | ) |

get size of snd_seq_port_info_t

Returns
  size in bytes

int snd_seq_query_next_port | ( | snd_seq_t * | seq,
|  | snd_seq_port_info_t * | info
| ) |  |

query the next matching port

Parameters

  seq | sequencer handle
  info | query pattern and result

Queries the next matching port on the client specified in info argument. The search begins at the next port specified in port field of info argument. For finding the first port at a certain client, give -1.

If a matching port is found, its attributes are stored on info and function returns zero. Otherwise, a negative error code is returned.

See Also
  snd_seq_get_port_info()

int snd_seq_set_port_info | ( | snd_seq_t * | seq,
|  | int | port,
|  | snd_seq_port_info_t * | info
| ) |  |

set the information of a port on the current client

Parameters

  seq | sequencer handle
  port | port to be set
  info | port information to be set

Returns
  0 on success otherwise a negative error code

See Also
  snd_seq_set_port_info()