RawMidi devices are opened exclusively for a selected direction. While more than one process may not open a given MIDI device in the same direction simultaneously, seperate processes may open a single MIDI device in different directions (i.e. process one opens a MIDI device in write direction and process two opens the same device in read direction). MIDI devices return EBUSY error to applications when other applications have already opened the requested direction.
int snd_rawmidi_open
(snd_rawmidi_t **handle, int card, int device, int mode);
Creates a new handle and opens a connection to the kernel sound audio interface for sound card number card (0-N) and RawMidi device number device. Function also checks if protocol is compatible to prevent use of old programs with a new kernel API. Function returns zero if successful, otherwise it returns an error code. Error code -EBUSY is returned when another process owns the selected direction.
The following modes should be used for the mode argument:
#define SND_RAWMIDI_OPEN_OUTPUT (O_WRONLY) #define SND_RAWMIDI_OPEN_OUTPUT_APPEND (O_WRONLY|O_APPEND|O_NONBLOCK) #define SND_RAWMIDI_OPEN_INPUT (O_RDONLY) #define SND_RAWMIDI_OPEN_DUPLEX (O_RDWR) #define SND_RAWMIDI_OPEN_DUPLEX_APPEND (O_RDWR|O_APPEND|O_NONBLOCK) #define SND_RAWMIDI_OPEN_NONBLOCK (O_NONBLOCK)
int snd_rawmidi_close
(snd_rawmidi_t *handle);
Frees all resources allocated with audio handle and closes the connection to the kernel sound RawMidi interface. Function returns zero if successful, otherwise it returns an error code.
int snd_rawmidi_file_descriptor
(snd_rawmidi_t *handle);
Returns the file descriptor of the connection to the kernel sound audio interface. Function returns an error code if an error was encountered.
The file descriptor should be used for the poll or select functions (see man 2 poll or man 2 select for more details) for determining, if something can be read or write. Application should call snd_rawmidi_read or snd_rawmidi_write functions if data is waiting to be read or a write can be performed. Calling these functions is highly recommended.
int snd_rawmidi_block_mode
(snd_rawmidi_t *handle, intenable);
Sets up block (default) or non-block mode for a handle. Block mode suspends execution of a program when snd_rawmidi_read or snd_rawmidi_write is called for the time which is needed for the actual output or input over of the selected limit. In non-block mode, programs aren't suspended and the above functions return immediately with the count of bytes which were read or written by the driver. When used in this way, don't try to use the entire buffer after the call, but instead process the number of bytes returned, and call the function again.
int snd_rawmidi_info
(snd_rawmidi_t *handle, snd_rawmidi_info_t *info);
Fills the *info structure with data about the RawMidi device selected by handle. Function returns zero if successful, otherwise it returns an error code.
/* device is capable rawmidi output */ #define SND_RAWMIDI_INFO_OUTPUT 0x00000001 /* device is capable rawmidi input */ #define SND_RAWMIDI_INFO_INPUT 0x00000002 /* device is capable the duplex module */ #define SND_RAWMIDI_INFO_DUPLEX 0x00000004 typedef struct snd_rawmidi_info { /* soundcard type */ int type; /* see SND_RAWMIDI_INFO_XXXX */ unsigned int flags; /* ID of this RawMidi device */ unsigned char id[64]; /* name of this RawMidi device */ unsigned char name[80]; /* reserved for the future use */ unsigned char reserved[64]; } snd_rawmidi_info_t;
int snd_rawmidi_output_params
(snd_rawmidi_t *handle, snd_rawmidi_output_params_t *params);
Sets various parameters for output direction. Function returns zero if successful, otherwise it returns an error code.
typedef struct snd_rawmidi_output_params { int size; int max; int room; unsigned char reserved[16]; } snd_rawmidi_output_params_t;
Requested queue size of output buffer in bytes (default setup is 4096 [i386] or 8192 [alpha] bytes - this is system architecture dependent).
Maximum number of bytes in queue for wakeup. If the current byte count of filled portion of output buffer is greater than this value the driver will block an application or return immediately if non block mode is active.
Minimum number of bytes writable for wakeup. This value should be in most cases 1 which means return back to application if at least one byte is free in output buffer.
int snd_rawmidi_input_params
(snd_rawmidi_t *handle, snd_rawmidi_input_params_t *params);
Function sets various parameters for the recording direction. Function returns zero if successful, otherwise it returns an error code.
typedef struct snd_rawmidi_input_params { int size; int min; int pad; unsigned char reserved[16]; } snd_rawmidi_input_params_t;
Requested queue size of output buffer in bytes (default setup is 4096 [i386] or 8192 [alpha] bytes - this is system architecture dependent).
Minimum filled bytes in queue for wakeup. Driver blocks the application (if block mode is selected) until input buffer is filled with fewer than the number of bytes specified with this value.
int snd_rawmidi_output_status
(snd_rawmidi_t *handle, snd_rawmidi_output_status_t *status);
Fills the *status structure. Function returns zero if successful, otherwise it returns an error code.
typedef struct snd_rawmidi_output_status { int size; int count; int queue; int pad; unsigned char reserved[16]; } snd_rawmidi_output_status_t;
Size of currently allocated queue in bytes.
Count of bytes writable without blocking.
Count of bytes in queue (number of bytes waiting to be output).
int snd_rawmidi_input_status
(snd_rawmidi_t *handle, snd_rawmidi_input_status_t *status);
Fills the *status structure. Function returns zero if successful, otherwise it returns an error code.
typedef struct snd_rawmidi_input_status { int size; int count; int free; int overrun; unsigned char reserved[16]; } snd_rawmidi_input_status_t;
Size of currently allocated queue in bytes.
Count of bytes readable without blocking.
Count of bytes in queue still free.
This value tells the application the count of overruns since the last call to snd_rawmidi_input_status.
int snd_rawmidi_drain_output
(snd_rawmidi_t *handle);
This function stops and drains (destroys) the output queue immediately. Function returns zero if successful, otherwise it returns an error code.
int snd_rawmidi_flush_output
(snd_rawmidi_t *handle);
This function flushes the output queue. It blocks the program while the all the waiting bytes in kernel output queue are processed. Function returns zero if successful, otherwise it returns an error code.
int snd_rawmidi_flush_input
(snd_rawmidi_t *handle);
This function flushes (destroys) input queue. Function returns zero if successful, otherwise it returns an error code.
ssize_t snd_rawmidi_write
(snd_rawmidi_t *handle, const void *buffer, size_t size);
Writes bytes to the output queue. Function returns zero or positive value if the write was successful (value represents count of bytes which were successfully written to the device) or an error value if error occurred. Function will suspend the process if block mode is active.
ssize_t snd_rawmidi_read
(snd_rawmidi_t *handle, void *buffer, size_t size);
Function reads bytes from input queue. Function returns zero or positive value if the read was successful (value represents count of bytes which were successfully read from device) or negative error value if error occurred. Function will suspend the process if block mode is active.