Core¶
A main include file
-
NANOSECONDS_IN_SECOND
¶ An amount of nanoseconds in a second
-
QUEUE_TEMPO
¶ A constant that defines the beat tempo in microseconds
-
QUEUE_STATUS_PPQ
¶ A constant that defines the base resolution of the ticks (pulses per quarter note)
-
void
init_midi_port
(MIDI_port **current_midi_port)¶ Allocates memory for a
MIDI_port
instance- Parameters
current_midi_port – a double pointer used to allocate memory for a
MIDI_port
instance
- Since
v0.1
-
void
print_midi_port
(MIDI_port *current_midi_port)¶ Prints a name of
snd_seq_client_info_t
andsnd_seq_port_info_t
containers- Parameters
current_midi_port – a
MIDI_port
instance to display
- Since
v0.1
-
void
free_midi_message
(MIDI_message *msg)¶ Deallocates memory for
MIDI_message
instance- Parameters
msg – a
MIDI_message
instance
- Since
v0.1
-
void
init_amidi_data_instance
(Alsa_MIDI_data **amidi_data)¶ Allocates memory for an instance of
Alsa_MIDI_data
or throws an error- Parameters
amidi_data – a double pointer used to allocate memory for a
Alsa_MIDI_data
instance
- Since
v0.1
-
void
assign_midi_queue
(MIDI_in_data *input_data)¶ Creates an assigns a MIDI message queue for a
MIDI_in_data
instance- Parameters
input_data – a pointer containing a
MIDI_in_data
instance for creating aGAsyncQueue
instance.
- Since
v0.1
-
void
assign_midi_data
(MIDI_in_data *input_data, Alsa_MIDI_data *amidi_data)¶ Assign
Alsa_MIDI_data
instance toMIDI_in_data
instance- Parameters
input_data –
MIDI_in_data
instanceamidi_data –
Alsa_MIDI_data
instance
- Since
v0.1
-
void
set_MIDI_in_callback
(MIDI_in_data *input_data, MIDI_callback callback, void *user_data)¶ Sets a callback for MIDI input events.
- Parameters
input_data –
MIDI_in_data
instancecallback –
MIDI_callback
instanceuser_data – an optional pointer to additional data that is passed to the callback function whenever it is called.
- Since
v0.1
-
void
enqueue_error
(MIDI_in_data *input_data, char *etype, char *msg)¶ Add an
error_message
instance toMIDI_in_data
instance- Parameters
input_data – a
MIDI_in_data
instance containing a queue to send an error toetype – error type string, for example, “V0001”, “S0001”
msg – error message
- Since
v0.1
-
void
assign_error_queue
(MIDI_in_data *input_data)¶ Create an error queue, add to
MIDI_in_data
instance- Parameters
input_data – a
MIDI_in_data
instance to add an error queue to
- Since
v0.1
-
int
init_amidi_data
(Alsa_MIDI_data *amidi_data, mp_type_t port_type)¶ Fill
Alsa_MIDI_data
struct instance- Parameters
amidi_data –
Alsa_MIDI_data
instance to initializeport_type – a port type to use, supports all values for
mp_type_t
- Returns
0 on success, -1 when
port_type
is notmp_type_t.MP_IN
,mp_type_t.MP_VIRTUAL_IN
,mp_type_t.MP_OUT
,mp_type_t.MP_VIRTUAL_OUT
.- Since
v0.1
-
int
init_seq
(Alsa_MIDI_data *amidi_data, const char *client_name, mp_type_t port_type)¶ Creates a seq instance, assigns it to
Alsa_MIDI_data
- Parameters
amidi_data –
Alsa_MIDI_data
instanceclient_name – client name string
port_type – a port type for a sequencer, supports all values for
mp_type_t
- Returns
0 on success, -1 on error.
- Since
v0.1
-
int
start_input_seq
(Alsa_MIDI_data *amidi_data, const char *queue_name, RMR_Port_config *port_config)¶ Creates a named input queue, sets its tempo and other parameters.
- Parameters
amidi_data –
Alsa_MIDI_data
instancequeue_name – a name for a new named queue
port_config – an instance of port configuration:
RMR_Port_config
- Returns
0 or -1 when an error happens
- Since
v0.1
-
int
prepare_output
(int is_virtual, Alsa_MIDI_data *amidi_data, const char *port_name)¶ Creates a MIDI event parser, a virtual port for virtual mode and allocates a buffer for normal mode.
TODO pick a new name, considering calls to snd_midi_event_new, snd_midi_event_init, snd_seq_create_simple_port (virtual mode) and malloc for amidi_data->buffer (normal mode).
- Parameters
is_virtual – should the function create normal output port or a virtual one?
amidi_data –
Alsa_MIDI_data
instanceport_name – a name to set for a new virtual output port
- Returns
0 on success, -1 on an error
- Since
v0.1
-
unsigned int
port_info
(int *seq, int *pinfo, unsigned int type, int port_number)¶ This function is used to count or get the pinfo structure for a given port number.
- Parameters
snd_seq_t – Alsa’s
snd_seq_t
instancepinfo – Alsa’s
snd_seq_port_info_t
instancetype – Alsa MIDI port capabilities
SND_SEQ_PORT_CAP_READ
|SND_SEQ_PORT_CAP_SUBS_READ
orSND_SEQ_PORT_CAP_WRITE
|SND_SEQ_PORT_CAP_SUBS_WRITE
port_number – use -1 for counting ports and a port number to get port info (in that case a function returns 1).
TODO do we query a client number, not a port number? We are using snd_seq_query_next_client.
- Returns
port count (or the amount of ports) when a negative port_number value is provided, 1 when a port ID is provided and the port is found, 0 when a port ID is not found
-
unsigned int
get_midi_port_count
(Alsa_MIDI_data *amidi_data, unsigned int type)¶ Counts midi ports for input and output types
- Parameters
amidi_data –
Alsa_MIDI_data
instancetype – Alsa MIDI port capabilities, like “
SND_SEQ_PORT_CAP_READ
|SND_SEQ_PORT_CAP_SUBS_READ
” or “SND_SEQ_PORT_CAP_WRITE
|SND_SEQ_PORT_CAP_SUBS_WRITE
”
- Returns
MIDI port count
- Since
v0.1
-
void
get_port_descriptor_by_id
(MIDI_port *port, Alsa_MIDI_data *amidi_data, unsigned int port_number, unsigned int type)¶ Updates a port pointer to
MIDI_port
instance from a selected port_number.- Parameters
port – a pointer to update
amidi_data –
Alsa_MIDI_data
instanceport_number – a port number
type – Alsa MIDI port capabilities
SND_SEQ_PORT_CAP_READ
|SND_SEQ_PORT_CAP_SUBS_READ
orSND_SEQ_PORT_CAP_WRITE
|SND_SEQ_PORT_CAP_SUBS_WRITE
- Since
v0.1
-
void
deallocate_input_thread
(struct MIDI_in_data *input_data)¶ Free an Alsa MIDI event parser, reset its value in
MIDI_in_data
instance, set currentMIDI_in_data
thread to dummy_thread_id- Parameters
input_data – a
MIDI_in_data
instance
- Since
v0.1
-
void *
alsa_MIDI_handler
(void *ptr)¶ A start routine for
alsa_MIDI_handler
.- Parameters
ptr – a void-pointer to
MIDI_in_data
.
- Since
v0.1
-
int
open_virtual_port
(Alsa_MIDI_data *amidi_data, const char *port_name, MIDI_in_data *input_data)¶ Opens a MIDI port with a given name, creates a thread and queues for it.
- Parameters
amidi_data –
Alsa_MIDI_data
instanceport_name – a char array pointer pointing to a port name string
input_data – a
MIDI_in_data
instance
- Returns
0 on success
- Since
v0.1
-
int
send_midi_message
(Alsa_MIDI_data *amidi_data, const unsigned char *message, int size)¶ Sends a MIDI message using a provided
Alsa_MIDI_data
instance- Parameters
amidi_data –
Alsa_MIDI_data
instancemessage – a MIDI message to be sent
size – a size of MIDI message in bytes
- Returns
0 on success, -1 on an error
- Since
v0.1
-
int
find_midi_port
(Alsa_MIDI_data *amidi_data, MIDI_port *port, mp_type_t port_type, const char *substr)¶ Finds a MIDI port (port) by a given substring. Matches a substring in
MIDI_port.client_info_name
attribute.- Parameters
amidi_data –
Alsa_MIDI_data
instanceport –
MIDI_port
instanceport_type – a port type for a sequencer, supports all values for
mp_type_t
, distinguishes only between “input” and “output”, so a virtual input will still be “an input”substr – a port substring
- Returns
1 when a port was found, -1 on an error, -2 when an invalid port type was provided
- Since
v0.1
-
int
open_port
(mp_type_t port_type, unsigned int port_number, const char *port_name, Alsa_MIDI_data *amidi_data, MIDI_in_data *input_data)¶ Opens a MIDI port by its number. Converted from two RtMIDI methods, initially accepted boolean pointing if it’s input.
TODO read all calls in a function and decide if it really makes sense for port_type not to be inverted.
- Parameters
port_type – a port type for a opening, supports all values for
mp_type_t
, currently expects MP_IN or MP_VIRTUAL_IN in input contextport_number – number of a port to look for
port_name – a name of a port to set using
snd_seq_port_info_set_name()
amidi_data –
Alsa_MIDI_data
instanceinput_data – a
MIDI_in_data
instance
- Returns
0 on success, -1 on an error
- Since
v0.1
-
void
close_port
(Alsa_MIDI_data *amidi_data, MIDI_in_data *input_data, int mode)¶ Closes input or output port, works for both virtual and not ports
- Parameters
amidi_data –
Alsa_MIDI_data
instanceinput_data –
MIDI_in_data
instancemode – accepts
SND_SEQ_OPEN_INPUT
orSND_SEQ_OPEN_OUTPUT
- Since
v0.1
-
int
destroy_midi_output
(Alsa_MIDI_data *amidi_data, MIDI_in_data *input_data)¶ Destroys a MIDI output port: closes a port connection and performs a cleanup.
- Parameters
amidi_data –
Alsa_MIDI_data
instanceinput_data –
MIDI_in_data
instance
- Returns
0 on success
- Since
v0.1
-
int
destroy_midi_input
(Alsa_MIDI_data *amidi_data, MIDI_in_data *input_data)¶ Destroys a MIDI input port: closes a port connection, shuts the input thread down, performs cleanup / deallocations.
- Parameters
amidi_data –
Alsa_MIDI_data
instanceinput_data –
MIDI_in_data
instance
- Returns
0 on success
- Since
v0.1
-
void
set_port_name
(Alsa_MIDI_data *amidi_data, const char *port_name)¶ Set the name of a port_info container in Alsa SEQ interface port information container, update a port info value for an
amidi_data.vport
value.- Parameters
amidi_data – Alsa_MIDI_data instance
port_name – a new name for Alsa seq port
- Since
v0.1
-
void
set_client_name
(Alsa_MIDI_data *amidi_data, const char *client_name)¶ Set name for a
amidi_data.seq
snd_seq_t
instance.- Parameters
amidi_data –
Alsa_MIDI_data
instanceclient_name – a new name for Alsa seq client
- Since
v0.1
-
int
prepare_input_data_with_queues
(MIDI_in_data **input_data)¶ Allocates memory for
MIDI_in_data
instance. Assigns two queues: one for MIDI messages and one for errors.- Parameters
input_data – a double pointer used to allocate memory for a
MIDI_in_data
instance
- Returns
0 on success
- Since
v0.1
-
int
start_virtual_output_port
(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)¶ A wrapper function for a initializing a virtual output MIDI port.
- Parameters
amidi_data – a double pointer to
Alsa_MIDI_data
instanceport_config – an instance of port configuration:
RMR_Port_config
- Returns
0 on success
- Since
v0.1
-
int
start_output_port
(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)¶ A wrapper function for starting a non-virtual output port.
- Parameters
amidi_data – a double pointer to
Alsa_MIDI_data
instanceport_config – an instance of port configuration:
RMR_Port_config
- Returns
0 on success
- Since
v0.1
-
int
start_virtual_input_port
(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)¶ A wrapper function for opening a virtual input port
- Parameters
amidi_data – a double pointer to
Alsa_MIDI_data
instanceport_config – an instance of port configuration:
RMR_Port_config
- Returns
0 on success
- Since
v0.1
-
int
start_input_port
(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)¶ A wrapper function for starting a non-virtual input port.
- Parameters
amidi_data – a double pointer to
Alsa_MIDI_data
instanceport_config – an instance of port configuration:
RMR_Port_config
- Returns
0 on success
- Since
v0.1
-
int
reset_port_config
(RMR_Port_config *port_config, mp_type_t port_type)¶ Fills
RMR_Port_config
attributes.A port type is set first, then a queue tempo and ppq you can change. “client_name”, “port_name” and “queue_name” are set as “N/A” and then changed to default values needed for a certain port type.
- Parameters
port_config – an instance of port configuration:
RMR_Port_config
port_type – a port type for a sequencer, supports all values for
mp_type_t
- Returns
0 on success
- Since
v0.1.3
-
int
setup_port_config
(RMR_Port_config **port_config, mp_type_t port_type)¶ Allocates memory for an instance of
RMR_Port_config
, sets default values for it- Parameters
port_config – an instance of port configuration:
RMR_Port_config
port_type – a port type for a sequencer, supports all values for
mp_type_t
- Returns
0 on success
- Since
v0.1.3
-
int
destroy_port_config
(RMR_Port_config *port_config)¶ Deallocates an instance of
RMR_Port_config
- Parameters
port_config – an instance of port configuration (
RMR_Port_config
)
- Returns
0 on success
- Since
v0.1.3
-
int
start_port
(Alsa_MIDI_data **amidi_data, RMR_Port_config *port_config)¶ A wrapper for in, out, virtual in and virtual out MIDI port initialization. TODO add Port_config input.
- Parameters
amidi_data – a double pointer to
Alsa_MIDI_data
instanceport_config – an instance of port configuration:
RMR_Port_config
- Returns
0 on success
- Since
v0.1
-
int
get_full_port_name
(char *port_name, unsigned int port_number, mp_type_t port_type, Alsa_MIDI_data *amidi_data)¶ Finds a complete port name, including both client info and port info. A rewrite of both RtMIDI’s getPortName functions.
While this output format might look unusual, it provides info about two Alsa containers: “client info” and “port info”, in that order. It shows names and IDs.
- Parameters
port_name – a const char pointer pointing to a string to be filled
port_number – a number of a port to look for
port_type – supports all values for
mp_type_t
, used to selectSND_SEQ_PORT_CAP_READ
|SND_SEQ_PORT_CAP_SUBS_READ
orSND_SEQ_PORT_CAP_WRITE
|SND_SEQ_PORT_CAP_SUBS_WRITE
port capabilitiesamidi_data – a double pointer to
Alsa_MIDI_data
instance
- Returns
0 on success, -1 when port_name is a null pointer, -2 when incorrect value was passed for port_type argument, -3 when port wasn’t found.
- Since
v0.1