Sequencer Port Interface

Overview

Sequencer Port Interface More…

// typedefs

typedef struct _snd_seq_port_info snd_seq_port_info_t;

// global functions

size_t
snd_seq_port_info_sizeof(void);

int
snd_seq_port_info_malloc(snd_seq_port_info_t** ptr);

void
snd_seq_port_info_free(snd_seq_port_info_t* ptr);

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

int
snd_seq_port_info_get_client(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_port(const snd_seq_port_info_t* info);

const snd_seq_addr_t*
snd_seq_port_info_get_addr(const snd_seq_port_info_t* info);

const char*
snd_seq_port_info_get_name(const snd_seq_port_info_t* info);

unsigned int
snd_seq_port_info_get_capability(const snd_seq_port_info_t* info);

unsigned int
snd_seq_port_info_get_type(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_midi_channels(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_midi_voices(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_synth_voices(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_read_use(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_write_use(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_port_specified(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_timestamping(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_timestamp_real(const snd_seq_port_info_t* info);

int
snd_seq_port_info_get_timestamp_queue(const snd_seq_port_info_t* info);

void
snd_seq_port_info_set_client(
    snd_seq_port_info_t* info,
    int client
);

void
snd_seq_port_info_set_port(
    snd_seq_port_info_t* info,
    int port
);

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

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

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

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

void
snd_seq_port_info_set_midi_channels(
    snd_seq_port_info_t* info,
    int channels
);

void
snd_seq_port_info_set_midi_voices(
    snd_seq_port_info_t* info,
    int voices
);

void
snd_seq_port_info_set_synth_voices(
    snd_seq_port_info_t* info,
    int voices
);

void
snd_seq_port_info_set_port_specified(
    snd_seq_port_info_t* info,
    int val
);

void
snd_seq_port_info_set_timestamping(
    snd_seq_port_info_t* info,
    int enable
);

void
snd_seq_port_info_set_timestamp_real(
    snd_seq_port_info_t* info,
    int realtime
);

void
snd_seq_port_info_set_timestamp_queue(
    snd_seq_port_info_t* info,
    int queue
);

int
snd_seq_create_port(
    snd_seq_t* handle,
    snd_seq_port_info_t* info
);

int
snd_seq_delete_port(
    snd_seq_t* handle,
    int port
);

int
snd_seq_get_port_info(
    snd_seq_t* handle,
    int port,
    snd_seq_port_info_t* info
);

int
snd_seq_get_any_port_info(
    snd_seq_t* handle,
    int client,
    int port,
    snd_seq_port_info_t* info
);

int
snd_seq_set_port_info(
    snd_seq_t* handle,
    int port,
    snd_seq_port_info_t* info
);

int
snd_seq_query_next_port(
    snd_seq_t* handle,
    snd_seq_port_info_t* info
);

// macros

#define SND_SEQ_PORT_CAP_DUPLEX
#define SND_SEQ_PORT_CAP_NO_EXPORT
#define SND_SEQ_PORT_CAP_READ
#define SND_SEQ_PORT_CAP_SUBS_READ
#define SND_SEQ_PORT_CAP_SUBS_WRITE
#define SND_SEQ_PORT_CAP_SYNC_READ
#define SND_SEQ_PORT_CAP_SYNC_WRITE
#define SND_SEQ_PORT_CAP_WRITE
#define SND_SEQ_PORT_SYSTEM_ANNOUNCE
#define SND_SEQ_PORT_SYSTEM_TIMER
#define SND_SEQ_PORT_TYPE_APPLICATION
#define SND_SEQ_PORT_TYPE_DIRECT_SAMPLE
#define SND_SEQ_PORT_TYPE_HARDWARE
#define SND_SEQ_PORT_TYPE_MIDI_GENERIC
#define SND_SEQ_PORT_TYPE_MIDI_GM
#define SND_SEQ_PORT_TYPE_MIDI_GM2
#define SND_SEQ_PORT_TYPE_MIDI_GS
#define SND_SEQ_PORT_TYPE_MIDI_MT32
#define SND_SEQ_PORT_TYPE_MIDI_XG
#define SND_SEQ_PORT_TYPE_PORT
#define SND_SEQ_PORT_TYPE_SAMPLE
#define SND_SEQ_PORT_TYPE_SOFTWARE
#define SND_SEQ_PORT_TYPE_SPECIFIC
#define SND_SEQ_PORT_TYPE_SYNTH
#define SND_SEQ_PORT_TYPE_SYNTHESIZER
#define snd_seq_port_info_alloca(ptr)

Detailed Documentation

Typedefs

typedef struct _snd_seq_port_info snd_seq_port_info_t

port information container

Global Functions

size_t
snd_seq_port_info_sizeof(void)

get size of snd_seq_port_info_t

Returns:

size in bytes

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_free(snd_seq_port_info_t* ptr)

frees a previously allocated snd_seq_port_info_t

Parameters:

obj	pointer to object to free

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

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

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

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

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

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

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

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)

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)

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)

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

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

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

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

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

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

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

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

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

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

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)

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)

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

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

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.

Parameters:

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

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

int
snd_seq_create_port(
    snd_seq_t* handle,
    snd_seq_port_info_t* info
)

create a sequencer port on the current client

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.

Parameters:

seq	sequencer handle
port	port information for the new port

Returns:

0 on success otherwise a negative error code

int
snd_seq_delete_port(
    snd_seq_t* handle,
    int port
)

delete a sequencer port on the current client

Deletes the existing sequencer port on the current client.

Parameters:

seq	sequencer handle
port	port to be deleted

Returns:

0 on success otherwise a negative error code

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

Parameters:

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

Returns:

0 on success otherwise a negative error code

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

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

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

int
snd_seq_query_next_port(
    snd_seq_t* handle,
    snd_seq_port_info_t* info
)

query the next matching port

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.

Parameters:

seq	sequencer handle
info	query pattern and result

See also:

snd_seq_get_port_info()

Macros

#define SND_SEQ_PORT_CAP_DUPLEX

allow read/write duplex

#define SND_SEQ_PORT_CAP_NO_EXPORT

routing not allowed

#define SND_SEQ_PORT_CAP_READ

port capabilities (32 bits) readable from this port

#define SND_SEQ_PORT_CAP_SUBS_READ

allow read subscription

#define SND_SEQ_PORT_CAP_SUBS_WRITE

allow write subscription

#define SND_SEQ_PORT_CAP_SYNC_READ

allow read subscriptions

#define SND_SEQ_PORT_CAP_SYNC_WRITE

allow write subscriptions

#define SND_SEQ_PORT_CAP_WRITE

writable to this port

#define SND_SEQ_PORT_SYSTEM_ANNOUNCE

system announce port

#define SND_SEQ_PORT_SYSTEM_TIMER

known port numbers system timer port

#define SND_SEQ_PORT_TYPE_APPLICATION

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

#define SND_SEQ_PORT_TYPE_DIRECT_SAMPLE

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

#define SND_SEQ_PORT_TYPE_HARDWARE

This port is implemented in hardware.

#define SND_SEQ_PORT_TYPE_MIDI_GENERIC

This port understands MIDI messages.

#define SND_SEQ_PORT_TYPE_MIDI_GM

This port is compatible with the General MIDI specification.

#define SND_SEQ_PORT_TYPE_MIDI_GM2

This port is compatible with the General MIDI 2 specification.

#define SND_SEQ_PORT_TYPE_MIDI_GS

This port is compatible with the Roland GS standard.

#define SND_SEQ_PORT_TYPE_MIDI_MT32

This port is compatible with the Roland MT-32.

#define SND_SEQ_PORT_TYPE_MIDI_XG

This port is compatible with the Yamaha XG specification.

#define SND_SEQ_PORT_TYPE_PORT

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

#define SND_SEQ_PORT_TYPE_SAMPLE

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

This port is implemented in software.

#define SND_SEQ_PORT_TYPE_SPECIFIC

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

#define SND_SEQ_PORT_TYPE_SYNTH

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

#define SND_SEQ_PORT_TYPE_SYNTHESIZER

Messages sent to this port will generate sounds.

#define snd_seq_port_info_alloca(ptr)

allocate a snd_seq_port_info_t container on stack