Lines Matching defs:*
2 * \file rawmidi/rawmidi.c
3 * \brief RawMidi Interface
4 * \author Jaroslav Kysela <perex@perex.cz>
5 * \author Abramo Bagnara <abramo@alsa-project.org>
6 * \date 2000-2001
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
39 stream as well.
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
57 are free.
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
67 buffer.
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.
99 Example:
101 \code
102 default
103 \endcode
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).
110 Example:
112 \code
113 hw
114 hw:0
115 hw:0,0
116 hw:supersonic,1
117 hw:soundwave,1,2
118 hw:DEV=1,CARD=soundwave,SUBDEV=2
119 \endcode
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"
127 \par
128 This example shows open and read/write rawmidi operations.
133 * \example ../test/rawmidi.c
134 * \anchor example_test_rawmidi
137 #include <stdio.h>
138 #include <stdlib.h>
139 #include <stdarg.h>
140 #include <unistd.h>
141 #include <string.h>
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)
152 assert(rawmidi);
153 assert(params);
154 params->buffer_size = page_size();
155 params->avail_min = 1;
156 params->no_active_sensing = 1;
157 return 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)
164 const char *str;
165 char buf[256];
166 int err;
167 snd_config_t *conf, *type_conf = NULL;
168 snd_config_iterator_t i, next;
169 snd_rawmidi_params_t params;
170 const char *id;
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;
174 #ifndef PIC
175 extern void *snd_rawmidi_open_symbols(void);
176 #endif
177 void *h = NULL;
178 if (snd_config_get_type(rawmidi_conf) != SND_CONFIG_TYPE_COMPOUND) {
179 if (name)
180 SNDERR("Invalid type for RAWMIDI %s definition", name);
181 else
182 SNDERR("Invalid type for RAWMIDI definition");
183 return -EINVAL;
185 err = snd_config_search(rawmidi_conf, "type", &conf);
186 if (err < 0) {
187 SNDERR("type is not defined");
188 return err;
190 err = snd_config_get_id(conf, &id);
191 if (err < 0) {
192 SNDERR("unable to get id");
193 return err;
195 err = snd_config_get_string(conf, &str);
196 if (err < 0) {
197 SNDERR("Invalid type for %s", id);
198 return err;
200 err = snd_config_search_definition(rawmidi_root, "rawmidi_type", str, &type_conf);
201 if (err >= 0) {
202 if (snd_config_get_type(type_conf) != SND_CONFIG_TYPE_COMPOUND) {
203 SNDERR("Invalid type for RAWMIDI type %s definition", str);
204 err = -EINVAL;
205 goto _err;
207 snd_config_for_each(i, next, type_conf) {
208 snd_config_t *n = snd_config_iterator_entry(i);
209 const char *id;
210 if (snd_config_get_id(n, &id) < 0)
211 continue;
212 if (strcmp(id, "comment") == 0)
213 continue;
214 if (strcmp(id, "lib") == 0) {
215 err = snd_config_get_string(n, &lib);
216 if (err < 0) {
217 SNDERR("Invalid type for %s", id);
218 goto _err;
220 continue;
222 if (strcmp(id, "open") == 0) {
223 err = snd_config_get_string(n, &open_name);
224 if (err < 0) {
225 SNDERR("Invalid type for %s", id);
226 goto _err;
228 continue;
230 SNDERR("Unknown field %s", id);
231 err = -EINVAL;
232 goto _err;
235 if (!open_name) {
236 open_name = buf;
237 snprintf(buf, sizeof(buf), "_snd_rawmidi_%s_open", str);
239 #ifndef PIC
240 snd_rawmidi_open_symbols();
241 #endif
242 h = snd_dlopen(lib, RTLD_NOW);
243 if (h)
244 open_func = snd_dlsym(h, open_name, SND_DLSYM_VERSION(SND_RAWMIDI_DLSYM_VERSION));
245 err = 0;
246 if (!h) {
247 SNDERR("Cannot open shared library %s", lib);
248 err = -ENOENT;
249 } else if (!open_func) {
250 SNDERR("symbol %s is not defined inside %s", open_name, lib);
251 snd_dlclose(h);
252 err = -ENXIO;
254 _err:
255 if (type_conf)
256 snd_config_delete(type_conf);
257 if (err >= 0)
258 err = open_func(inputp, outputp, name, rawmidi_root, rawmidi_conf, mode);
259 if (err < 0)
260 return err;
261 if (inputp) {
262 (*inputp)->dl_handle = h; h = NULL;
263 snd_rawmidi_params_default(*inputp, ¶ms);
264 err = snd_rawmidi_params(*inputp, ¶ms);
265 assert(err >= 0);
267 if (outputp) {
268 (*outputp)->dl_handle = h;
269 snd_rawmidi_params_default(*outputp, ¶ms);
270 err = snd_rawmidi_params(*outputp, ¶ms);
271 assert(err >= 0);
273 return 0;
276 static int snd_rawmidi_open_noupdate(snd_rawmidi_t **inputp, snd_rawmidi_t **outputp,
277 snd_config_t *root, const char *name, int mode)
279 int err;
280 snd_config_t *rawmidi_conf;
281 err = snd_config_search_definition(root, "rawmidi", name, &rawmidi_conf);
282 if (err < 0) {
283 SNDERR("Unknown RawMidi %s", name);
284 return err;
286 err = snd_rawmidi_open_conf(inputp, outputp, name, root, rawmidi_conf, mode);
287 snd_config_delete(rawmidi_conf);
288 return err;
292 * \brief Opens a new connection to the RawMidi interface.
293 * \param inputp Returned input handle (NULL if not wanted)
294 * \param outputp Returned output handle (NULL if not wanted)
295 * \param name ASCII identifier of the RawMidi handle
296 * \param mode Open mode
297 * \return 0 on success otherwise a negative error code
299 * Opens a new connection to the RawMidi interface specified with
300 * an ASCII identifier and mode.
302 int snd_rawmidi_open(snd_rawmidi_t **inputp, snd_rawmidi_t **outputp,
303 const char *name, int mode)
305 int err;
306 assert((inputp || outputp) && name);
307 err = snd_config_update();
308 if (err < 0)
309 return err;
310 return snd_rawmidi_open_noupdate(inputp, outputp, snd_config, name, mode);
314 * \brief Opens a new connection to the RawMidi interface using local configuration
315 * \param inputp Returned input handle (NULL if not wanted)
316 * \param outputp Returned output handle (NULL if not wanted)
317 * \param name ASCII identifier of the RawMidi handle
318 * \param mode Open mode
319 * \param lconf Local configuration
320 * \return 0 on success otherwise a negative error code
322 * Opens a new connection to the RawMidi interface specified with
323 * an ASCII identifier and mode.
325 int snd_rawmidi_open_lconf(snd_rawmidi_t **inputp, snd_rawmidi_t **outputp,
326 const char *name, int mode, snd_config_t *lconf)
328 assert((inputp || outputp) && name && lconf);
329 return snd_rawmidi_open_noupdate(inputp, outputp, lconf, name, mode);
333 * \brief close RawMidi handle
334 * \param rawmidi RawMidi handle
335 * \return 0 on success otherwise a negative error code
337 * Closes the specified RawMidi handle and frees all associated
338 * resources.
340 int snd_rawmidi_close(snd_rawmidi_t *rawmidi)
342 int err;
343 assert(rawmidi);
344 err = rawmidi->ops->close(rawmidi);
345 free(rawmidi->name);
346 if (rawmidi->dl_handle)
347 snd_dlclose(rawmidi->dl_handle);
348 free(rawmidi);
349 return err;
353 * \brief get identifier of RawMidi handle
354 * \param rawmidi a RawMidi handle
355 * \return ascii identifier of RawMidi handle
357 * Returns the ASCII identifier of given RawMidi handle. It's the same
358 * identifier specified in snd_rawmidi_open().
360 const char *snd_rawmidi_name(snd_rawmidi_t *rawmidi)
362 assert(rawmidi);
363 return rawmidi->name;
367 * \brief get type of RawMidi handle
368 * \param rawmidi a RawMidi handle
369 * \return type of RawMidi handle
371 * Returns the type #snd_rawmidi_type_t of given RawMidi handle.
373 snd_rawmidi_type_t snd_rawmidi_type(snd_rawmidi_t *rawmidi)
375 assert(rawmidi);
376 return rawmidi->type;
380 * \brief get stream (direction) of RawMidi handle
381 * \param rawmidi a RawMidi handle
382 * \return stream of RawMidi handle
384 * Returns the stream #snd_rawmidi_stream_t of given RawMidi handle.
386 snd_rawmidi_stream_t snd_rawmidi_stream(snd_rawmidi_t *rawmidi)
388 assert(rawmidi);
389 return rawmidi->stream;
393 * \brief get count of poll descriptors for RawMidi handle
394 * \param rawmidi RawMidi handle
395 * \return count of poll descriptors
397 int snd_rawmidi_poll_descriptors_count(snd_rawmidi_t *rawmidi)
399 assert(rawmidi);
400 return 1;
404 * \brief get poll descriptors
405 * \param rawmidi RawMidi handle
406 * \param pfds array of poll descriptors
407 * \param space space in the poll descriptor array
408 * \return count of filled descriptors
410 int snd_rawmidi_poll_descriptors(snd_rawmidi_t *rawmidi, struct pollfd *pfds, unsigned int space)
412 assert(rawmidi);
413 if (space >= 1) {
414 pfds->fd = rawmidi->poll_fd;
415 pfds->events = rawmidi->stream == SND_RAWMIDI_STREAM_OUTPUT ? (POLLOUT|POLLERR|POLLNVAL) : (POLLIN|POLLERR|POLLNVAL);
416 return 1;
418 return 0;
422 * \brief get returned events from poll descriptors
423 * \param rawmidi rawmidi RawMidi handle
424 * \param pfds array of poll descriptors
425 * \param nfds count of poll descriptors
426 * \param revents returned events
427 * \return zero if success, otherwise a negative error code
429 int snd_rawmidi_poll_descriptors_revents(snd_rawmidi_t *rawmidi, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
431 assert(rawmidi && pfds && revents);
432 if (nfds == 1) {
433 *revents = pfds->revents;
434 return 0;
436 return -EINVAL;
440 * \brief set nonblock mode
441 * \param rawmidi RawMidi handle
442 * \param nonblock 0 = block, 1 = nonblock mode
443 * \return 0 on success otherwise a negative error code
445 * The nonblock mode cannot be used when the stream is in
446 * #SND_RAWMIDI_APPEND state.
448 int snd_rawmidi_nonblock(snd_rawmidi_t *rawmidi, int nonblock)
450 int err;
451 assert(rawmidi);
452 assert(!(rawmidi->mode & SND_RAWMIDI_APPEND));
453 if ((err = rawmidi->ops->nonblock(rawmidi, nonblock)) < 0)
454 return err;
455 if (nonblock)
456 rawmidi->mode |= SND_RAWMIDI_NONBLOCK;
457 else
458 rawmidi->mode &= ~SND_RAWMIDI_NONBLOCK;
459 return 0;
463 * \brief get size of the snd_rawmidi_info_t structure in bytes
464 * \return size of the snd_rawmidi_info_t structure in bytes
466 size_t snd_rawmidi_info_sizeof()
468 return sizeof(snd_rawmidi_info_t);
472 * \brief allocate a new snd_rawmidi_info_t structure
473 * \param info returned pointer
474 * \return 0 on success otherwise a negative error code if fails
476 * Allocates a new snd_rawmidi_params_t structure using the standard
477 * malloc C library function.
479 int snd_rawmidi_info_malloc(snd_rawmidi_info_t **info)
481 assert(info);
482 *info = calloc(1, sizeof(snd_rawmidi_info_t));
483 if (!*info)
484 return -ENOMEM;
485 return 0;
489 * \brief frees the snd_rawmidi_info_t structure
490 * \param info pointer to the snd_rawmidi_info_t structure to free
492 * Frees the given snd_rawmidi_params_t structure using the standard
493 * free C library function.
495 void snd_rawmidi_info_free(snd_rawmidi_info_t *info)
497 assert(info);
498 free(info);
502 * \brief copy one snd_rawmidi_info_t structure to another
503 * \param dst destination snd_rawmidi_info_t structure
504 * \param src source snd_rawmidi_info_t structure
506 void snd_rawmidi_info_copy(snd_rawmidi_info_t *dst, const snd_rawmidi_info_t *src)
508 assert(dst && src);
509 *dst = *src;
513 * \brief get rawmidi device number
514 * \param info pointer to a snd_rawmidi_info_t structure
515 * \return rawmidi device number
517 unsigned int snd_rawmidi_info_get_device(const snd_rawmidi_info_t *info)
519 assert(info);
520 return info->device;
524 * \brief get rawmidi subdevice number
525 * \param info pointer to a snd_rawmidi_info_t structure
526 * \return rawmidi subdevice number
528 unsigned int snd_rawmidi_info_get_subdevice(const snd_rawmidi_info_t *info)
530 assert(info);
531 return info->subdevice;
535 * \brief get rawmidi stream identification
536 * \param info pointer to a snd_rawmidi_info_t structure
537 * \return rawmidi stream identification
539 snd_rawmidi_stream_t snd_rawmidi_info_get_stream(const snd_rawmidi_info_t *info)
541 assert(info);
542 return info->stream;
546 * \brief get rawmidi card number
547 * \param info pointer to a snd_rawmidi_info_t structure
548 * \return rawmidi card number
550 int snd_rawmidi_info_get_card(const snd_rawmidi_info_t *info)
552 assert(info);
553 return info->card;
557 * \brief get rawmidi flags
558 * \param info pointer to a snd_rawmidi_info_t structure
559 * \return rawmidi flags
561 unsigned int snd_rawmidi_info_get_flags(const snd_rawmidi_info_t *info)
563 assert(info);
564 return info->flags;
568 * \brief get rawmidi hardware driver identifier
569 * \param info pointer to a snd_rawmidi_info_t structure
570 * \return rawmidi hardware driver identifier
572 const char *snd_rawmidi_info_get_id(const snd_rawmidi_info_t *info)
574 assert(info);
575 return (const char *)info->id;
579 * \brief get rawmidi hardware driver name
580 * \param info pointer to a snd_rawmidi_info_t structure
581 * \return rawmidi hardware driver name
583 const char *snd_rawmidi_info_get_name(const snd_rawmidi_info_t *info)
585 assert(info);
586 return (const char *)info->name;
590 * \brief get rawmidi subdevice name
591 * \param info pointer to a snd_rawmidi_info_t structure
592 * \return rawmidi subdevice name
594 const char *snd_rawmidi_info_get_subdevice_name(const snd_rawmidi_info_t *info)
596 assert(info);
597 return (const char *)info->subname;
601 * \brief get rawmidi count of subdevices
602 * \param info pointer to a snd_rawmidi_info_t structure
603 * \return rawmidi count of subdevices
605 unsigned int snd_rawmidi_info_get_subdevices_count(const snd_rawmidi_info_t *info)
607 assert(info);
608 return info->subdevices_count;
612 * \brief get rawmidi available count of subdevices
613 * \param info pointer to a snd_rawmidi_info_t structure
614 * \return rawmidi available count of subdevices
616 unsigned int snd_rawmidi_info_get_subdevices_avail(const snd_rawmidi_info_t *info)
618 assert(info);
619 return info->subdevices_avail;
623 * \brief set rawmidi device number
624 * \param info pointer to a snd_rawmidi_info_t structure
625 * \param val device number
627 void snd_rawmidi_info_set_device(snd_rawmidi_info_t *info, unsigned int val)
629 assert(info);
630 info->device = val;
634 * \brief set rawmidi subdevice number
635 * \param info pointer to a snd_rawmidi_info_t structure
636 * \param val subdevice number
638 void snd_rawmidi_info_set_subdevice(snd_rawmidi_info_t *info, unsigned int val)
640 assert(info);
641 info->subdevice = val;
645 * \brief set rawmidi stream identifier
646 * \param info pointer to a snd_rawmidi_info_t structure
647 * \param val rawmidi stream identifier
649 void snd_rawmidi_info_set_stream(snd_rawmidi_info_t *info, snd_rawmidi_stream_t val)
651 assert(info);
652 info->stream = val;
656 * \brief get information about RawMidi handle
657 * \param rawmidi RawMidi handle
658 * \param info pointer to a snd_rawmidi_info_t structure to be filled
659 * \return 0 on success otherwise a negative error code
661 int snd_rawmidi_info(snd_rawmidi_t *rawmidi, snd_rawmidi_info_t * info)
663 assert(rawmidi);
664 assert(info);
665 return rawmidi->ops->info(rawmidi, info);
669 * \brief get size of the snd_rawmidi_params_t structure in bytes
670 * \return size of the snd_rawmidi_params_t structure in bytes
672 size_t snd_rawmidi_params_sizeof()
674 return sizeof(snd_rawmidi_params_t);
678 * \brief allocate the snd_rawmidi_params_t structure
679 * \param params returned pointer
680 * \return 0 on success otherwise a negative error code if fails
682 * Allocates a new snd_rawmidi_params_t structure using the standard
683 * malloc C library function.
685 int snd_rawmidi_params_malloc(snd_rawmidi_params_t **params)
687 assert(params);
688 *params = calloc(1, sizeof(snd_rawmidi_params_t));
689 if (!*params)
690 return -ENOMEM;
691 return 0;
695 * \brief frees the snd_rawmidi_params_t structure
696 * \param params pointer to the #snd_rawmidi_params_t structure to free
698 * Frees the given snd_rawmidi_params_t structure using the standard
699 * free C library function.
701 void snd_rawmidi_params_free(snd_rawmidi_params_t *params)
703 assert(params);
704 free(params);
708 * \brief copy one snd_rawmidi_params_t structure to another
709 * \param dst destination snd_rawmidi_params_t structure
710 * \param src source snd_rawmidi_params_t structure
712 void snd_rawmidi_params_copy(snd_rawmidi_params_t *dst, const snd_rawmidi_params_t *src)
714 assert(dst && src);
715 *dst = *src;
719 * \brief set rawmidi I/O ring buffer size
720 * \param rawmidi RawMidi handle
721 * \param params pointer to a snd_rawmidi_params_t structure
722 * \param val size in bytes
723 * \return 0 on success otherwise a negative error code
725 #ifndef DOXYGEN
726 int snd_rawmidi_params_set_buffer_size(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, size_t val)
727 #else
728 int snd_rawmidi_params_set_buffer_size(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params, size_t val)
729 #endif
731 assert(rawmidi && params);
732 assert(val > params->avail_min);
733 params->buffer_size = val;
734 return 0;
738 * \brief get rawmidi I/O ring buffer size
739 * \param params pointer to a snd_rawmidi_params_t structure
740 * \return size of rawmidi I/O ring buffer in bytes
742 size_t snd_rawmidi_params_get_buffer_size(const snd_rawmidi_params_t *params)
744 assert(params);
745 return params->buffer_size;
749 * \brief set minimum available bytes in rawmidi I/O ring buffer for wakeup
750 * \param rawmidi RawMidi handle
751 * \param params pointer to a snd_rawmidi_params_t structure
752 * \param val desired value
754 #ifndef DOXYGEN
755 int snd_rawmidi_params_set_avail_min(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, size_t val)
756 #else
757 int snd_rawmidi_params_set_avail_min(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params, size_t val)
758 #endif
760 assert(rawmidi && params);
761 assert(val < params->buffer_size);
762 params->avail_min = val;
763 return 0;
767 * \brief get minimum available bytes in rawmidi I/O ring buffer for wakeup
768 * \param params pointer to snd_rawmidi_params_t structure
769 * \return minimum available bytes
771 size_t snd_rawmidi_params_get_avail_min(const snd_rawmidi_params_t *params)
773 assert(params);
774 return params->avail_min;
778 * \brief set no-active-sensing action on snd_rawmidi_close()
779 * \param rawmidi RawMidi handle
780 * \param params pointer to snd_rawmidi_params_t structure
781 * \param val value: 0 = enable to send the active sensing message, 1 = disable
782 * \return 0 on success otherwise a negative error code
784 #ifndef DOXYGEN
785 int snd_rawmidi_params_set_no_active_sensing(snd_rawmidi_t *rawmidi ATTRIBUTE_UNUSED, snd_rawmidi_params_t *params, int val)
786 #else
787 int snd_rawmidi_params_set_no_active_sensing(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params, int val)
788 #endif
790 assert(rawmidi && params);
791 params->no_active_sensing = val;
792 return 0;
796 * \brief get no-active-sensing action status
797 * \param params pointer to snd_rawmidi_params_t structure
798 * \return the current status (0 = enable, 1 = disable the active sensing message)
800 int snd_rawmidi_params_get_no_active_sensing(const snd_rawmidi_params_t *params)
802 assert(params);
803 return params->no_active_sensing;
807 * \brief set parameters about rawmidi stream
808 * \param rawmidi RawMidi handle
809 * \param params pointer to a snd_rawmidi_params_t structure to be filled
810 * \return 0 on success otherwise a negative error code
812 int snd_rawmidi_params(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t * params)
814 int err;
815 assert(rawmidi);
816 assert(params);
817 err = rawmidi->ops->params(rawmidi, params);
818 if (err < 0)
819 return err;
820 rawmidi->buffer_size = params->buffer_size;
821 rawmidi->avail_min = params->avail_min;
822 rawmidi->no_active_sensing = params->no_active_sensing;
823 return 0;
827 * \brief get current parameters about rawmidi stream
828 * \param rawmidi RawMidi handle
829 * \param params pointer to a snd_rawmidi_params_t structure to be filled
830 * \return 0 on success otherwise a negative error code
832 int snd_rawmidi_params_current(snd_rawmidi_t *rawmidi, snd_rawmidi_params_t *params)
834 assert(rawmidi);
835 assert(params);
836 params->buffer_size = rawmidi->buffer_size;
837 params->avail_min = rawmidi->avail_min;
838 params->no_active_sensing = rawmidi->no_active_sensing;
839 return 0;
843 * \brief get size of the snd_rawmidi_status_t structure in bytes
844 * \return size of the snd_rawmidi_status_t structure in bytes
846 size_t snd_rawmidi_status_sizeof()
848 return sizeof(snd_rawmidi_status_t);
852 * \brief allocate the snd_rawmidi_status_t structure
853 * \param ptr returned pointer
854 * \return 0 on success otherwise a negative error code if fails
856 * Allocates a new snd_rawmidi_status_t structure using the standard
857 * malloc C library function.
859 int snd_rawmidi_status_malloc(snd_rawmidi_status_t **ptr)
861 assert(ptr);
862 *ptr = calloc(1, sizeof(snd_rawmidi_status_t));
863 if (!*ptr)
864 return -ENOMEM;
865 return 0;
869 * \brief frees the snd_rawmidi_status_t structure
870 * \param status pointer to the snd_rawmidi_status_t structure to free
872 * Frees the given snd_rawmidi_status_t structure using the standard
873 * free C library function.
875 void snd_rawmidi_status_free(snd_rawmidi_status_t *status)
877 assert(status);
878 free(status);
882 * \brief copy one snd_rawmidi_status_t structure to another
883 * \param dst destination snd_rawmidi_status_t structure
884 * \param src source snd_rawmidi_status_t structure
886 void snd_rawmidi_status_copy(snd_rawmidi_status_t *dst, const snd_rawmidi_status_t *src)
888 assert(dst && src);
889 *dst = *src;
893 * \brief get the start timestamp
894 * \param status pointer to a snd_rawmidi_status_t structure
895 * \param tstamp returned timestamp value
897 void snd_rawmidi_status_get_tstamp(const snd_rawmidi_status_t *status, snd_htimestamp_t *tstamp)
899 assert(status && tstamp);
900 *tstamp = status->tstamp;
904 * \brief get current available bytes in the rawmidi I/O ring buffer
905 * \param status pointer to a snd_rawmidi_status_t structure
906 * \return current available bytes in the rawmidi I/O ring buffer
908 size_t snd_rawmidi_status_get_avail(const snd_rawmidi_status_t *status)
910 assert(status);
911 return status->avail;
915 * \brief get count of xruns
916 * \param status pointer to a snd_rawmidi_status_t structure
917 * \return count of xruns
919 size_t snd_rawmidi_status_get_xruns(const snd_rawmidi_status_t *status)
921 assert(status);
922 return status->xruns;
926 * \brief get status of rawmidi stream
927 * \param rawmidi RawMidi handle
928 * \param status pointer to a snd_rawmidi_status_t structure to be filled
929 * \return 0 on success otherwise a negative error code
931 int snd_rawmidi_status(snd_rawmidi_t *rawmidi, snd_rawmidi_status_t * status)
933 assert(rawmidi);
934 assert(status);
935 return rawmidi->ops->status(rawmidi, status);
939 * \brief drop all bytes in the rawmidi I/O ring buffer immediately
940 * \param rawmidi RawMidi handle
941 * \return 0 on success otherwise a negative error code
943 int snd_rawmidi_drop(snd_rawmidi_t *rawmidi)
945 assert(rawmidi);
946 return rawmidi->ops->drop(rawmidi);
950 * \brief drain all bytes in the rawmidi I/O ring buffer
951 * \param rawmidi RawMidi handle
952 * \return 0 on success otherwise a negative error code
954 * Waits until all MIDI bytes are not drained (sent) to the
955 * hardware device.
957 int snd_rawmidi_drain(snd_rawmidi_t *rawmidi)
959 assert(rawmidi);
960 return rawmidi->ops->drain(rawmidi);
964 * \brief write MIDI bytes to MIDI stream
965 * \param rawmidi RawMidi handle
966 * \param buffer buffer containing MIDI bytes
967 * \param size output buffer size in bytes
969 ssize_t snd_rawmidi_write(snd_rawmidi_t *rawmidi, const void *buffer, size_t size)
971 assert(rawmidi);
972 assert(rawmidi->stream == SND_RAWMIDI_STREAM_OUTPUT);
973 assert(buffer || size == 0);
974 return rawmidi->ops->write(rawmidi, buffer, size);
978 * \brief read MIDI bytes from MIDI stream
979 * \param rawmidi RawMidi handle
980 * \param buffer buffer to store the input MIDI bytes
981 * \param size input buffer size in bytes
983 ssize_t snd_rawmidi_read(snd_rawmidi_t *rawmidi, void *buffer, size_t size)
985 assert(rawmidi);
986 assert(rawmidi->stream == SND_RAWMIDI_STREAM_INPUT);
987 assert(buffer || size == 0);
988 return (rawmidi->ops->read)(rawmidi, buffer, size);
991 #ifndef DOC_HIDDEN
992 int snd_rawmidi_conf_generic_id(const char *id)
994 static const char ids[][8] = {
995 "comment",
996 "type",
997 "hint",
999 unsigned int k;
1001 for (k = 0; k < sizeof ids / sizeof *ids; ++k) {
1002 if (strcmp(id, ids[k]) == 0)
1003 return 1;
1005 return 0;
1007 #endif