2 * \file rawmidi/rawmidi.c
3 * \brief RawMidi Interface
4 * \author Jaroslav Kysela <perex@perex.cz>
5 * \author Abramo Bagnara <abramo@alsa-project.org>
8 * See the \ref rawmidi page for more details.
12 * This library is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Lesser General Public License as
14 * published by the Free Software Foundation; either version 2.1 of
15 * the License, or (at your option) any later version.
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Lesser General Public License for more details.
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this library; if not, write to the Free Software
24 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
28 /*! \page rawmidi RawMidi interface
30 <P>RawMidi Interface is designed to write or read raw (unchanged) MIDI
31 data over the MIDI line without any timestamps defined in interface. MIDI
32 stands Musical Instrument Digital Interface and more information about
33 this standard can be found at http://www.midi.org.
35 \section rawmidi_general_overview General overview
37 The rawmidi implementation uses ring buffers to store outgoing and incoming
38 MIDI stream. The buffer size is tunable and drivers report underruns for incoming
41 \section rawmidi_open Open handling
43 RawMidi devices are opened exclusively for a selected direction.
44 While more than one process may not open a given MIDI device in the same
45 direction simultaneously, separate processes may open a single MIDI device
46 in different directions (i.e. process one opens a MIDI device in write
47 direction and process two opens the same device in read direction).
49 \subsection rawmidi_open_nonblock Nonblocking open (flag)
51 Using #SND_RAWMIDI_NONBLOCK flag for snd_rawmidi_open() or snd_rawmidi_open_lconf()
52 instruct device driver to return the -EBUSY error when device is already occupied
53 with another application. This flag also changes behaviour of snd_rawmidi_write()
54 and snd_rawmidi_read() returning -EAGAIN when no more bytes can be processed.
56 Note: In opposite (default) behaviour, application is blocked until device resources
59 \subsection rawmidi_open_append Append open (flag)
61 Using #SND_RAWMIDI_APPEND flag (output only) instruct device driver to append
62 contents of written buffer - passed by snd_rawmidi_write() - atomically
63 to output ring buffer in the kernel space. This flag also means that device
64 is not opened exclusively, so more applications can share given rawmidi device.
65 Note that applications must send the whole MIDI message including the running status,
66 because another writting application might break the MIDI message in the output
69 \subsection rawmidi_open_sync Sync open (flag)
71 Using #SND_RAWMIDI_SYNC flag (output only) assures that the contents of output
72 buffer specified using snd_rawmidi_write() is always drained before the function
73 exits. This behaviour is same like 'snd_rawmidi_write() followed by
74 snd_rawmidi_drain() immediately'.
76 \subsection rawmidi_io I/O handling
78 There is only standard read/write access to device internal ring buffer. Use
79 snd_rawmidi_read() and snd_rawmidi_write() functions to obtain / write MIDI bytes.
81 \subsection rawmidi_dev_names RawMidi naming conventions
83 The ALSA library uses a generic string representation for names of devices.
84 The devices might be virtual, physical or a mix of both. The generic string
85 is passed to \link ::snd_rawmidi_open() \endlink or \link ::snd_rawmidi_open_lconf() \endlink.
86 It contains two parts: device name and arguments. Devices and arguments are described
87 in configuration files. The usual place for default definitions is at /usr/share/alsa/alsa.conf.
89 \subsection rawmidi_dev_names_default
91 The default device is equal to hw device. The defaults are used:
93 defaults.rawmidi.card 0
94 defaults.rawmidi.device 0
95 defaults.rawmidi.subdevice -1
97 These defaults can be freely overwritten in local configuration files.
105 \subsection rawmidi_dev_names_hw HW device
107 The hw device description uses the hw plugin. The three arguments (in order: CARD,DEV,SUBDEV)
108 specify card number or identifier, device number and subdevice number (-1 means any).
118 hw:DEV=1,CARD=soundwave,SUBDEV=2
121 \section rawmidi_examples Examples
123 The full featured examples with cross-links:
125 \par Simple input/output test program
126 \ref example_test_rawmidi "example code"
128 This example shows open and read/write rawmidi operations.
133 * \example ../test/rawmidi.c
134 * \anchor example_test_rawmidi
142 #include "rawmidi_local.h"
145 * \brief setup the default parameters
146 * \param rawmidi RawMidi handle
147 * \param params pointer to a snd_rawmidi_params_t structure
148 * \return 0 on success otherwise a negative error code
150 static int snd_rawmidi_params_default(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params)
154 params->buffer_size = page_size();
155 params->avail_min = 1;
156 params->no_active_sensing = 0;
160 static int snd_rawmidi_open_conf(snd_rawmidi_t **inputp, snd_rawmidi_t **outputp,
161 const char *name, snd_config_t *rawmidi_root,
162 snd_config_t *rawmidi_conf, int mode)
167 snd_config_t *conf, *type_conf = NULL;
168 snd_config_iterator_t i, next;
169 snd_rawmidi_params_t params;
171 const char *lib = NULL, *open_name = NULL;
172 int (*open_func)(snd_rawmidi_t **, snd_rawmidi_t **,
173 const char *, snd_config_t *, snd_config_t *, int) = NULL;
175 extern void *snd_rawmidi_open_symbols(void);
178 if (snd_config_get_type(rawmidi_conf) != SND_CONFIG_TYPE_COMPOUND) {
180 SNDERR("Invalid type for RAWMIDI %s definition", name);
182 SNDERR("Invalid type for RAWMIDI definition");
185 err = snd_config_search(rawmidi_conf, "type", &conf);
187 SNDERR("type is not defined");
190 err = snd_config_get_id(conf, &id);
192 SNDERR("unable to get id");
195 err = snd_config_get_string(conf, &str);
197 SNDERR("Invalid type for %s", id);
200 err = snd_config_search_definition(rawmidi_root, "rawmidi_type", str, &type_conf);
202 if (snd_config_get_type(type_conf) != SND_CONFIG_TYPE_COMPOUND) {
203 SNDERR("Invalid type for RAWMIDI type %s definition", str);
206 snd_config_for_each(i, next, type_conf) {
207 snd_config_t *n = snd_config_iterator_entry(i);
209 if (snd_config_get_id(n, &id) < 0)
211 if (strcmp(id, "comment") == 0)
213 if (strcmp(id, "lib") == 0) {
214 err = snd_config_get_string(n, &lib);
216 SNDERR("Invalid type for %s", id);
221 if (strcmp(id, "open") == 0) {
222 err = snd_config_get_string(n, &open_name);
224 SNDERR("Invalid type for %s", id);
229 SNDERR("Unknown field %s", id);
236 snprintf(buf, sizeof(buf), "_snd_rawmidi_%s_open", str);
239 snd_rawmidi_open_symbols();
241 h = snd_dlopen(lib, RTLD_NOW);
243 open_func = snd_dlsym(h, open_name, SND_DLSYM_VERSION(SND_RAWMIDI_DLSYM_VERSION));
246 SNDERR("Cannot open shared library %s", lib);
248 } else if (!open_func) {
249 SNDERR("symbol %s is not defined inside %s", open_name, lib);
255 snd_config_delete(type_conf);
257 err = open_func(inputp, outputp, name, rawmidi_root, rawmidi_conf, mode);
261 (*inputp)->dl_handle = h; h = NULL;
262 snd_rawmidi_params_default(*inputp, ¶ms);
263 err = snd_rawmidi_params(*inputp, ¶ms);
267 (*outputp)->dl_handle = h;
268 snd_rawmidi_params_default(*outputp, ¶ms);
269 err = snd_rawmidi_params(*outputp, ¶ms);
275 static int snd_rawmidi_open_noupdate(snd_rawmidi_t **inputp, snd_rawmidi_t **outputp,
276 snd_config_t *root, const char *name, int mode)
279 snd_config_t *rawmidi_conf;
280 err = snd_config_search_definition(root, "rawmidi", name, &rawmidi_conf);
282 SNDERR("Unknown RawMidi %s", name);
285 err = snd_rawmidi_open_conf(inputp, outputp, name, root, rawmidi_conf, mode);
286 snd_config_delete(rawmidi_conf);
291 * \brief Opens a new connection to the RawMidi interface.
292 * \param inputp Returned input handle (NULL if not wanted)
293 * \param outputp Returned output handle (NULL if not wanted)
294 * \param name ASCII identifier of the RawMidi handle
295 * \param mode Open mode
296 * \return 0 on success otherwise a negative error code
298 * Opens a new connection to the RawMidi interface specified with
299 * an ASCII identifier and mode.
301 int snd_rawmidi_open(snd_rawmidi_t **inputp, snd_rawmidi_t **outputp,
302 const char *name, int mode)
305 assert((inputp || outputp) && name);
306 err = snd_config_update();
309 return snd_rawmidi_open_noupdate(inputp, outputp, snd_config, name, mode);
313 * \brief Opens a new connection to the RawMidi interface using local configuration
314 * \param inputp Returned input handle (NULL if not wanted)
315 * \param outputp Returned output handle (NULL if not wanted)
316 * \param name ASCII identifier of the RawMidi handle
317 * \param mode Open mode
318 * \param lconf Local configuration
319 * \return 0 on success otherwise a negative error code
321 * Opens a new connection to the RawMidi interface specified with
322 * an ASCII identifier and mode.
324 int snd_rawmidi_open_lconf(snd_rawmidi_t **inputp, snd_rawmidi_t **outputp,
325 const char *name, int mode, snd_config_t *lconf)
327 assert((inputp || outputp) && name && lconf);
328 return snd_rawmidi_open_noupdate(inputp, outputp, lconf, name, mode);
332 * \brief close RawMidi handle
333 * \param rawmidi RawMidi handle
334 * \return 0 on success otherwise a negative error code
336 * Closes the specified RawMidi handle and frees all associated
339 int snd_rawmidi_close(snd_rawmidi_t *rawmidi)
343 err = rawmidi->ops->close(rawmidi);
345 if (rawmidi->dl_handle)
346 snd_dlclose(rawmidi->dl_handle);
352 * \brief get identifier of RawMidi handle
353 * \param rawmidi a RawMidi handle
354 * \return ascii identifier of RawMidi handle
356 * Returns the ASCII identifier of given RawMidi handle. It's the same
357 * identifier specified in snd_rawmidi_open().
359 const char *snd_rawmidi_name(snd_rawmidi_t *rawmidi)
362 return rawmidi->name;
366 * \brief get type of RawMidi handle
367 * \param rawmidi a RawMidi handle
368 * \return type of RawMidi handle
370 * Returns the type #snd_rawmidi_type_t of given RawMidi handle.
372 snd_rawmidi_type_t snd_rawmidi_type(snd_rawmidi_t *rawmidi)
375 return rawmidi->type;
379 * \brief get stream (direction) of RawMidi handle
380 * \param rawmidi a RawMidi handle
381 * \return stream of RawMidi handle
383 * Returns the stream #snd_rawmidi_stream_t of given RawMidi handle.
385 snd_rawmidi_stream_t snd_rawmidi_stream(snd_rawmidi_t *rawmidi)
388 return rawmidi->stream;
392 * \brief get count of poll descriptors for RawMidi handle
393 * \param rawmidi RawMidi handle
394 * \return count of poll descriptors
396 int snd_rawmidi_poll_descriptors_count(snd_rawmidi_t *rawmidi)
403 * \brief get poll descriptors
404 * \param rawmidi RawMidi handle
405 * \param pfds array of poll descriptors
406 * \param space space in the poll descriptor array
407 * \return count of filled descriptors
409 int snd_rawmidi_poll_descriptors(snd_rawmidi_t *rawmidi, struct pollfd *pfds, unsigned int space)
413 pfds->fd = rawmidi->poll_fd;
414 pfds->events = rawmidi->stream == SND_RAWMIDI_STREAM_OUTPUT ? (POLLOUT|POLLERR|POLLNVAL) : (POLLIN|POLLERR|POLLNVAL);
421 * \brief get returned events from poll descriptors
422 * \param rawmidi rawmidi RawMidi handle
423 * \param pfds array of poll descriptors
424 * \param nfds count of poll descriptors
425 * \param revents returned events
426 * \return zero if success, otherwise a negative error code
428 int snd_rawmidi_poll_descriptors_revents(snd_rawmidi_t *rawmidi, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
430 assert(rawmidi && pfds && revents);
432 *revents = pfds->revents;
439 * \brief set nonblock mode
440 * \param rawmidi RawMidi handle
441 * \param nonblock 0 = block, 1 = nonblock mode
442 * \return 0 on success otherwise a negative error code
444 * The nonblock mode cannot be used when the stream is in
445 * #SND_RAWMIDI_APPEND state.
447 int snd_rawmidi_nonblock(snd_rawmidi_t *rawmidi, int nonblock)
451 assert(!(rawmidi->mode & SND_RAWMIDI_APPEND));
452 if ((err = rawmidi->ops->nonblock(rawmidi, nonblock)) < 0)
455 rawmidi->mode |= SND_RAWMIDI_NONBLOCK;
457 rawmidi->mode &= ~SND_RAWMIDI_NONBLOCK;
462 * \brief get size of the snd_rawmidi_info_t structure in bytes
463 * \return size of the snd_rawmidi_info_t structure in bytes
465 size_t snd_rawmidi_info_sizeof()
467 return sizeof(snd_rawmidi_info_t);
471 * \brief allocate a new snd_rawmidi_info_t structure
472 * \param info returned pointer
473 * \return 0 on success otherwise a negative error code if fails
475 * Allocates a new snd_rawmidi_params_t structure using the standard
476 * malloc C library function.
478 int snd_rawmidi_info_malloc(snd_rawmidi_info_t **info)
481 *info = calloc(1, sizeof(snd_rawmidi_info_t));
488 * \brief frees the snd_rawmidi_info_t structure
489 * \param info pointer to the snd_rawmidi_info_t structure to free
491 * Frees the given snd_rawmidi_params_t structure using the standard
492 * free C library function.
494 void snd_rawmidi_info_free(snd_rawmidi_info_t *info)
501 * \brief copy one snd_rawmidi_info_t structure to another
502 * \param dst destination snd_rawmidi_info_t structure
503 * \param src source snd_rawmidi_info_t structure
505 void snd_rawmidi_info_copy(snd_rawmidi_info_t *dst, const snd_rawmidi_info_t *src)
512 * \brief get rawmidi device number
513 * \param info pointer to a snd_rawmidi_info_t structure
514 * \return rawmidi device number
516 unsigned int snd_rawmidi_info_get_device(const snd_rawmidi_info_t *info)
523 * \brief get rawmidi subdevice number
524 * \param info pointer to a snd_rawmidi_info_t structure
525 * \return rawmidi subdevice number
527 unsigned int snd_rawmidi_info_get_subdevice(const snd_rawmidi_info_t *info)
530 return info->subdevice;
534 * \brief get rawmidi stream identification
535 * \param info pointer to a snd_rawmidi_info_t structure
536 * \return rawmidi stream identification
538 snd_rawmidi_stream_t snd_rawmidi_info_get_stream(const snd_rawmidi_info_t *info)
545 * \brief get rawmidi card number
546 * \param info pointer to a snd_rawmidi_info_t structure
547 * \return rawmidi card number
549 int snd_rawmidi_info_get_card(const snd_rawmidi_info_t *info)
556 * \brief get rawmidi flags
557 * \param info pointer to a snd_rawmidi_info_t structure
558 * \return rawmidi flags
560 unsigned int snd_rawmidi_info_get_flags(const snd_rawmidi_info_t *info)
567 * \brief get rawmidi hardware driver identifier
568 * \param info pointer to a snd_rawmidi_info_t structure
569 * \return rawmidi hardware driver identifier
571 const char *snd_rawmidi_info_get_id(const snd_rawmidi_info_t *info)
574 return (const char *)info->id;
578 * \brief get rawmidi hardware driver name
579 * \param info pointer to a snd_rawmidi_info_t structure
580 * \return rawmidi hardware driver name
582 const char *snd_rawmidi_info_get_name(const snd_rawmidi_info_t *info)
585 return (const char *)info->name;
589 * \brief get rawmidi subdevice name
590 * \param info pointer to a snd_rawmidi_info_t structure
591 * \return rawmidi subdevice name
593 const char *snd_rawmidi_info_get_subdevice_name(const snd_rawmidi_info_t *info)
596 return (const char *)info->subname;
600 * \brief get rawmidi count of subdevices
601 * \param info pointer to a snd_rawmidi_info_t structure
602 * \return rawmidi count of subdevices
604 unsigned int snd_rawmidi_info_get_subdevices_count(const snd_rawmidi_info_t *info)
607 return info->subdevices_count;
611 * \brief get rawmidi available count of subdevices
612 * \param info pointer to a snd_rawmidi_info_t structure
613 * \return rawmidi available count of subdevices
615 unsigned int snd_rawmidi_info_get_subdevices_avail(const snd_rawmidi_info_t *info)
618 return info->subdevices_avail;
622 * \brief set rawmidi device number
623 * \param info pointer to a snd_rawmidi_info_t structure
624 * \param val device number
626 void snd_rawmidi_info_set_device(snd_rawmidi_info_t *info, unsigned int val)
633 * \brief set rawmidi subdevice number
634 * \param info pointer to a snd_rawmidi_info_t structure
635 * \param val subdevice number
637 void snd_rawmidi_info_set_subdevice(snd_rawmidi_info_t *info, unsigned int val)
640 info->subdevice = val;
644 * \brief set rawmidi stream identifier
645 * \param info pointer to a snd_rawmidi_info_t structure
646 * \param val rawmidi stream identifier
648 void snd_rawmidi_info_set_stream(snd_rawmidi_info_t *info, snd_rawmidi_stream_t val)
655 * \brief get information about RawMidi handle
656 * \param rawmidi RawMidi handle
657 * \param info pointer to a snd_rawmidi_info_t structure to be filled
658 * \return 0 on success otherwise a negative error code
660 int snd_rawmidi_info(snd_rawmidi_t *rawmidi, snd_rawmidi_info_t * info)
664 return rawmidi->ops->info(rawmidi, info);
668 * \brief get size of the snd_rawmidi_params_t structure in bytes
669 * \return size of the snd_rawmidi_params_t structure in bytes
671 size_t snd_rawmidi_params_sizeof()
673 return sizeof(snd_rawmidi_params_t);
677 * \brief allocate the snd_rawmidi_params_t structure
678 * \param params returned pointer
679 * \return 0 on success otherwise a negative error code if fails
681 * Allocates a new snd_rawmidi_params_t structure using the standard
682 * malloc C library function.
684 int snd_rawmidi_params_malloc(snd_rawmidi_params_t **params)
687 *params = calloc(1, sizeof(snd_rawmidi_params_t));
694 * \brief frees the snd_rawmidi_params_t structure
695 * \param params pointer to the #snd_rawmidi_params_t structure to free
697 * Frees the given snd_rawmidi_params_t structure using the standard
698 * free C library function.
700 void snd_rawmidi_params_free(snd_rawmidi_params_t *params)
707 * \brief copy one snd_rawmidi_params_t structure to another
708 * \param dst destination snd_rawmidi_params_t structure
709 * \param src source snd_rawmidi_params_t structure
711 void snd_rawmidi_params_copy(snd_rawmidi_params_t *dst, const snd_rawmidi_params_t *src)
718 * \brief set rawmidi I/O ring buffer size
719 * \param rawmidi RawMidi handle
720 * \param params pointer to a snd_rawmidi_params_t structure
721 * \param val size in bytes
722 * \return 0 on success otherwise a negative error code
725 int snd_rawmidi_params_set_buffer_size(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, size_t val)
727 int snd_rawmidi_params_set_buffer_size(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params, size_t val)
730 assert(rawmidi && params);
731 assert(val > params->avail_min);
732 params->buffer_size = val;
737 * \brief get rawmidi I/O ring buffer size
738 * \param params pointer to a snd_rawmidi_params_t structure
739 * \return size of rawmidi I/O ring buffer in bytes
741 size_t snd_rawmidi_params_get_buffer_size(const snd_rawmidi_params_t *params)
744 return params->buffer_size;
748 * \brief set minimum available bytes in rawmidi I/O ring buffer for wakeup
749 * \param rawmidi RawMidi handle
750 * \param params pointer to a snd_rawmidi_params_t structure
751 * \param val desired value
754 int snd_rawmidi_params_set_avail_min(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, size_t val)
756 int snd_rawmidi_params_set_avail_min(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params, size_t val)
759 assert(rawmidi && params);
760 assert(val < params->buffer_size);
761 params->avail_min = val;
766 * \brief get minimum available bytes in rawmidi I/O ring buffer for wakeup
767 * \param params pointer to snd_rawmidi_params_t structure
768 * \return minimum available bytes
770 size_t snd_rawmidi_params_get_avail_min(const snd_rawmidi_params_t *params)
773 return params->avail_min;
777 * \brief set no-active-sensing action on snd_rawmidi_close()
778 * \param rawmidi RawMidi handle
779 * \param params pointer to snd_rawmidi_params_t structure
780 * \param val value: 0 = enable to send the active sensing message, 1 = disable
781 * \return 0 on success otherwise a negative error code
784 int snd_rawmidi_params_set_no_active_sensing(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, int val)
786 int snd_rawmidi_params_set_no_active_sensing(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params, int val)
789 assert(rawmidi && params);
790 params->no_active_sensing = val;
795 * \brief get no-active-sensing action status
796 * \param params pointer to snd_rawmidi_params_t structure
797 * \return the current status (0 = enable, 1 = disable the active sensing message)
799 int snd_rawmidi_params_get_no_active_sensing(const snd_rawmidi_params_t *params)
802 return params->no_active_sensing;
806 * \brief set parameters about rawmidi stream
807 * \param rawmidi RawMidi handle
808 * \param params pointer to a snd_rawmidi_params_t structure to be filled
809 * \return 0 on success otherwise a negative error code
811 int snd_rawmidi_params(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t * params)
816 err = rawmidi->ops->params(rawmidi, params);
819 rawmidi->buffer_size = params->buffer_size;
820 rawmidi->avail_min = params->avail_min;
821 rawmidi->no_active_sensing = params->no_active_sensing;
826 * \brief get current parameters about rawmidi stream
827 * \param rawmidi RawMidi handle
828 * \param params pointer to a snd_rawmidi_params_t structure to be filled
829 * \return 0 on success otherwise a negative error code
831 int snd_rawmidi_params_current(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params)
835 params->buffer_size = rawmidi->buffer_size;
836 params->avail_min = rawmidi->avail_min;
837 params->no_active_sensing = rawmidi->no_active_sensing;
842 * \brief get size of the snd_rawmidi_status_t structure in bytes
843 * \return size of the snd_rawmidi_status_t structure in bytes
845 size_t snd_rawmidi_status_sizeof()
847 return sizeof(snd_rawmidi_status_t);
851 * \brief allocate the snd_rawmidi_status_t structure
852 * \param ptr returned pointer
853 * \return 0 on success otherwise a negative error code if fails
855 * Allocates a new snd_rawmidi_status_t structure using the standard
856 * malloc C library function.
858 int snd_rawmidi_status_malloc(snd_rawmidi_status_t **ptr)
861 *ptr = calloc(1, sizeof(snd_rawmidi_status_t));
868 * \brief frees the snd_rawmidi_status_t structure
869 * \param status pointer to the snd_rawmidi_status_t structure to free
871 * Frees the given snd_rawmidi_status_t structure using the standard
872 * free C library function.
874 void snd_rawmidi_status_free(snd_rawmidi_status_t *status)
881 * \brief copy one snd_rawmidi_status_t structure to another
882 * \param dst destination snd_rawmidi_status_t structure
883 * \param src source snd_rawmidi_status_t structure
885 void snd_rawmidi_status_copy(snd_rawmidi_status_t *dst, const snd_rawmidi_status_t *src)
892 * \brief get the start timestamp
893 * \param status pointer to a snd_rawmidi_status_t structure
894 * \param tstamp returned timestamp value
896 void snd_rawmidi_status_get_tstamp(const snd_rawmidi_status_t *status, snd_htimestamp_t *tstamp)
898 assert(status && tstamp);
899 *tstamp = status->tstamp;
903 * \brief get current available bytes in the rawmidi I/O ring buffer
904 * \param status pointer to a snd_rawmidi_status_t structure
905 * \return current available bytes in the rawmidi I/O ring buffer
907 size_t snd_rawmidi_status_get_avail(const snd_rawmidi_status_t *status)
910 return status->avail;
914 * \brief get count of xruns
915 * \param status pointer to a snd_rawmidi_status_t structure
916 * \return count of xruns
918 size_t snd_rawmidi_status_get_xruns(const snd_rawmidi_status_t *status)
921 return status->xruns;
925 * \brief get status of rawmidi stream
926 * \param rawmidi RawMidi handle
927 * \param status pointer to a snd_rawmidi_status_t structure to be filled
928 * \return 0 on success otherwise a negative error code
930 int snd_rawmidi_status(snd_rawmidi_t *rawmidi, snd_rawmidi_status_t * status)
934 return rawmidi->ops->status(rawmidi, status);
938 * \brief drop all bytes in the rawmidi I/O ring buffer immediately
939 * \param rawmidi RawMidi handle
940 * \return 0 on success otherwise a negative error code
942 int snd_rawmidi_drop(snd_rawmidi_t *rawmidi)
945 return rawmidi->ops->drop(rawmidi);
949 * \brief drain all bytes in the rawmidi I/O ring buffer
950 * \param rawmidi RawMidi handle
951 * \return 0 on success otherwise a negative error code
953 * Waits until all MIDI bytes are not drained (sent) to the
956 int snd_rawmidi_drain(snd_rawmidi_t *rawmidi)
959 return rawmidi->ops->drain(rawmidi);
963 * \brief write MIDI bytes to MIDI stream
964 * \param rawmidi RawMidi handle
965 * \param buffer buffer containing MIDI bytes
966 * \param size output buffer size in bytes
968 ssize_t snd_rawmidi_write(snd_rawmidi_t *rawmidi, const void *buffer, size_t size)
971 assert(rawmidi->stream == SND_RAWMIDI_STREAM_OUTPUT);
972 assert(buffer || size == 0);
973 return rawmidi->ops->write(rawmidi, buffer, size);
977 * \brief read MIDI bytes from MIDI stream
978 * \param rawmidi RawMidi handle
979 * \param buffer buffer to store the input MIDI bytes
980 * \param size input buffer size in bytes
982 ssize_t snd_rawmidi_read(snd_rawmidi_t *rawmidi, void *buffer, size_t size)
985 assert(rawmidi->stream == SND_RAWMIDI_STREAM_INPUT);
986 assert(buffer || size == 0);
987 return (rawmidi->ops->read)(rawmidi, buffer, size);
990 int snd_rawmidi_conf_generic_id(const char *id)
992 static const char *ids[] = {
999 for (k = 0; k < sizeof ids / sizeof *ids; ++k) {
1000 if (strcmp(id, ids[k]) == 0)