3 * \brief Sequencer Interface
4 * \author Jaroslav Kysela <perex@perex.cz>
5 * \author Abramo Bagnara <abramo@alsa-project.org>
6 * \author Takashi Iwai <tiwai@suse.de>
9 * See \ref seq page for more details.
13 * Sequencer Interface - main file
15 * This library is free software; you can redistribute it and/or modify
16 * it under the terms of the GNU Lesser General Public License as
17 * published by the Free Software Foundation; either version 2.1 of
18 * the License, or (at your option) any later version.
20 * This program is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 * GNU Lesser General Public License for more details.
25 * You should have received a copy of the GNU Lesser General Public
26 * License along with this library; if not, write to the Free Software
27 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
31 /*! \page seq Sequencer interface
33 \section seq_general Genral
35 The ALSA sequencer interface is designed to deliver the MIDI-like
36 events between clients/ports.
37 A typical usage is the MIDI patch-bay. A MIDI application can be
38 connected arbitrarily from/to the other MIDI clients.
39 The routing between clients can be changed dynamically, so the
40 application can handle incoming or outgoing MIDI events regardless of
41 the devices or the application connections.
43 The sequencer core stuff only takes care of two things:
44 scheduling events and dispatching them to the destination at the
45 right time. All processing of MIDI events has to be done within the clients.
46 The event can be dispatched immediately without queueing, too.
47 The event scheduling can be done either on a MIDI tempo queue or
48 on a wallclock-time queue.
50 \section seq_client Client and Port
52 A <i>client</i> is created at each time #snd_seq_open() is called.
53 Later on, the attributes of client such as its name string can be changed
54 via #snd_seq_set_client_info(). There are helper functions for ease of use,
55 e.g. #snd_seq_set_client_name() and #snd_seq_set_client_event_filter().
56 A typical code would be like below:
58 // create a new client
59 snd_seq_t *open_client()
63 err = snd_seq_open(&handle, "default", SND_SEQ_OPEN_INPUT, 0);
66 snd_seq_set_client_name(handle, "My Client");
71 You'll need to know the id number of the client eventually, for example,
72 when accessing to a certain port (see the section \ref seq_subs).
73 The client id can be obtained by #snd_seq_client_id() function.
75 A client can have one or more <i>ports</i> to communicate between other
76 clients. A port is corresponding to the MIDI port in the case of MIDI device,
77 but in general it is nothing but the access point between other clients.
78 Each port may have capability flags, which specify the read/write
79 accessbility and subscription permissions of the port.
80 For creation of a port, call #snd_seq_create_port()
81 with the appropirate port attribute specified in #snd_seq_port_info_t
84 For creating a port for the normal use, there is a helper function
85 #snd_seq_create_simple_port(). An example with this function is like below.
87 // create a new port; return the port id
88 // port will be writable and accept the write-subscription.
89 int my_new_port(snd_seq_t *handle)
91 return snd_seq_create_simple_port(handle, "my port",
92 SND_SEQ_PORT_CAP_WRITE|SND_SEQ_PORT_CAP_SUBS_WRITE,
93 SND_SEQ_PORT_TYPE_MIDI_GENERIC);
97 \section seq_memory Memory Pool
99 Each client owns memory pools on kernel space
100 for each input and output events.
101 Here, input and output mean
102 input (read) from other clients and output (write) to others, respectively.
103 Since memory pool of each client is independent from others,
104 it avoids such a situation that a client eats the whole events pool
105 and interfere other clients' responce.
107 The all scheduled output events or input events from dispatcher are stored
108 on these pools until delivered to other clients or extracted to user space.
109 The size of input/output pools can be changed independently.
110 The output pool has also a room size, which is used to wake up the
111 thread when it falls into sleep in blocking write mode.
113 Note that ports on the same client share the same memory pool.
114 If a port fills the memory pool, another can't use it any more.
115 For avoiding this, multiple clients can be used.
117 For chancing the pool size and the condition, access to #snd_seq_client_pool_t
118 record. There are helper functions, #snd_seq_set_client_pool_output(),
119 #snd_seq_set_client_pool_output_room() and #snd_seq_set_client_pool_input(),
120 for setting the total output-pool size, the output-room size and the input-pool
123 \section seq_subs Subscription
125 One of the new features in ALSA sequencer system is <i>subscription</i> of ports.
126 In general, subscription is a connection between two sequencer ports.
127 Even though an event can be delivered to a port without subscription
128 using an explicit destination address,
129 the subscription mechanism provides us more abstraction.
131 Suppose a MIDI input device which sends events from a keyboard.
132 The port associated with this device has READ capability - which means
133 this port is readable from other ports.
134 If a user program wants to capture events from keyboard and store them
135 as MIDI stream, this program must subscribe itself to the MIDI port
137 Then, a connection from MIDI input port to this program is established.
138 From this time, events from keyboard are automatically sent to this program.
139 Timestamps will be updated according to the subscribed queue.
141 MIDI input port (keyboard)
144 ALSA sequencer - update timestamp
150 There is another subscription type for opposite direction:
151 Suppose a MIDI sequencer program which sends events to a MIDI output device.
152 In ALSA system, MIDI device is not opened until the associated MIDI port
153 is accessed. Thus, in order to activate MIDI device, we have to subscribe
154 to MIDI port for write.
155 After this connection is established, events will be properly sent
156 to MIDI output device.
161 ALSA sequencer - events are scheduled
164 MIDI output port (WaveTable etc.)
167 From the viewpoint of subscription, the examples above are special cases.
168 Basically, subscription means the connection between two arbitrary ports.
169 For example, imagine a filter application which modifies
170 the MIDI events like program, velocity or chorus effects.
171 This application can accept arbitrary MIDI input
172 and send to arbitrary port, just like a Unix pipe application using
173 stdin and stdout files.
174 We can even connect several filter applictions which work individually
175 in order to process the MIDI events.
176 Subscription can be used for this purpose.
177 The connection between ports can be done also by the "third" client.
178 Thus, filter applications have to manage
179 only input and output events regardless of receiver/sender addresses.
184 ALSA sequencer (scheduled or real-time)
190 For the detail about subscription, see the section \ref seq_subs_more.
192 \section seq_events Sequencer Events
194 Messaging between clients is performed by sending events from one client to
195 another. These events contain high-level MIDI oriented messages or sequencer
198 All the sequencer events are stored in a sequencer event record,
199 #snd_seq_event_t type.
200 Application can send and receive these event records to/from other
201 clients via sequencer.
202 An event has several stroage types according to its usage.
203 For example, a SYSEX message is stored on the variable length event,
204 and a large synth sample data is delivered using a user-space data pointer.
207 \subsection seq_ev_struct Structure of an event
209 An event consists of the following items:
211 <li>The type of the event
212 <li>Event flags. It describes various conditions:
214 <li>time stamp; "real time" / "song ticks"
215 <li>time mode; "absolute" / "relative to current time"
217 <li>Timestamp of the event.
218 <li>Scheduling queue id.
219 <li>Source address of the event, given by the combination
220 of client id and port id numbers.
221 <li>Destination address of the event.
222 <li>The actual event data. (up to 12 bytes)
225 The actual record is shown in #snd_seq_event_t.
226 The type field contains the type of the event
228 The flags field consists of bit flags which
229 describe several conditions of the event (1 byte).
230 It includes the time-stamp mode, data storage type, and scheduling prority.
231 The tag field is an arbitrary tag.
232 This tag can used for removing a distinct event from the event queue
233 via #snd_seq_remove_events().
234 The queue field is the queue id for scheduling.
235 The source and dest fields are source and destination addresses.
236 The data field is a union of event data.
238 \subsection seq_ev_queue Scheduling queue
240 An event can be delivered either on scheduled or direct dispatch mode.
241 On the scheduling mode, an event is once stored on the priority queue
242 and delivered later (or even immediately) to the destination,
243 whereas on the direct disatch mode, an event is passed to the destination
246 For a scheduled delivery, a queue to process the event must exist.
247 Usually, a client creates its own queue by
248 #snd_seq_alloc_queue() function.
249 Alternatively, a queue may be shared among several clients.
250 For scheduling an event on the specified queue,
251 a client needs to fill queue field
252 with the preferred queue id.
254 Meanwhile, for dispatching an event directly, just
255 use #SND_SEQ_QUEUE_DIRECT as the target queue id.
256 A macro #snd_seq_ev_set_direct() is provided for ease
259 Note that scheduling at the current or earlier time is different
260 from the direct dispatch mode even though the event is delivered immediately.
261 On the former scheme, an event is once stored on priority queue, then
262 delivered actually. Thus, it acquires a space from memory pool.
263 On the other hand, the latter is passed without using memory pool.
264 Although the direct dispatched event needs less memory, it means also
265 that the event cannot be resent if the destination is unable to receive it
268 \subsection seq_ev_time Time stamp
270 The timestamp of the event can either specified in
271 <i>real time</i> or in <i>song ticks</i>.
272 The former means the wallclock time while the latter corresponds to
274 Which format is used is determined by the event flags.
276 The resolution of real-time value is in nano second.
277 Since 64 bit length is required for the actual time calculation,
279 a structure of pair of second and nano second
280 defined as #snd_seq_real_time_t type.
281 The song tick is defined simply as a 32 bit integer,
282 defined as #snd_seq_tick_time_t type.
283 The time stored in an event record is a union of these two different
286 Note that the time format used for real time events is very similar to
287 timeval struct used for unix system time.
288 The absurd resolution of the timestamps allows us to perform very accurate
289 conversions between songposition and real time. Round-off errors can be
292 If a timestamp with a
293 <i>relative</i> timestamp is delivered to ALSA, the
294 specified timestamp will be used as an offset to the current time of the
295 queue the event is sent into.
296 An <i>absolute</i> timestamp is on the contrary the time
297 counted from the moment when the queue started.
299 An client that relies on these relative timestamps is the MIDI input port.
300 As each sequencer queue has it's own clock the only way to deliver events at
301 the right time is by using the relative timestamp format. When the event
302 arrives at the queue it is normalised to absolute format.
304 The timestamp format is specified in the flag bitfield masked by
305 #SND_SEQ_TIME_STAMP_MASK.
306 To schedule the event in a real-time queue or in a tick queue,
307 macros #snd_seq_ev_schedule_real() and
308 #snd_seq_ev_schedule_tick() are provided, respectively.
310 \subsection seq_ev_addr Source and destination addresses
312 To identify the source and destination of an event, the addressing field
313 contains a combination of client id and port id numbers, defined as
314 #snd_seq_addr_t type.
315 When an event is passed to sequencer from a client, sequencer fills
317 with the sender's id automatically.
318 It is the responsibility of sender client to
319 fill the port id of source.port and
320 both client and port of dest field.
322 If an existing address is set to the destination,
323 the event is simplly delivered to it.
324 When #SND_SEQ_ADDRESS_SUBSCRIBERS is set to the destination client id,
325 the event is delivered to all the clients connected to the source port.
328 A sequencer core has two pre-defined system ports on the system client
329 #SND_SEQ_CLIENT_SYSTEM: #SND_SEQ_PORT_SYSTEM_TIMER and #SND_SEQ_PORT_SYSTEM_ANNOUNCE.
330 The #SND_SEQ_PORT_SYSTEM_TIMER is the system timer port,
331 and #SND_SEQ_PORT_SYSTEM_ANNOUNCE is the system
333 In order to control a queue from a client, client should send a
335 like start, stop and continue queue, change tempo, etc.
336 to the system timer port.
337 Then the sequencer system handles the queue according to the received event.
338 This port supports subscription. The received timer events are
339 broadcasted to all subscribed clients.
341 The latter port does not receive messages but supports subscription.
342 When each client or port is attached, detached or modified,
343 an announcement is sent to subscribers from this port.
345 \subsection seq_ev_data Data storage type
347 Some events like SYSEX message, however, need larger data space
348 than the standard data.
349 For such events, ALSA sequencer provides seveal different data storage types.
350 The data type is specified in the flag bits masked by #SND_SEQ_EVENT_LENGTH_MASK.
351 The following data types are available:
354 Normal events stores their parameters on
355 data field (12 byte).
356 The flag-bit type is #SND_SEQ_EVENT_LENGTH_FIXED.
357 A macro #snd_seq_ev_set_fixed() is provided to set this type.
359 \par Variable length data
360 SYSEX or a returned error use this type.
361 The actual data is stored on an extra allocated space.
362 On sequecer kernel, the whole extra-data is duplicated, so that the event
363 can be scheduled on queue.
364 The data contains only the length and the
365 pointer of extra-data.
366 The flag-bit type is #SND_SEQ_EVENT_LENGTH_VARIABLE.
367 A macro #snd_seq_ev_set_variable() is provided to set this type.
370 This type refers also an extra data space like variable length data,
371 but the extra-data is not duplicated but
372 but referred as a user-space data on kernel,
373 so that it reduces the time and resource for transferring
374 large bulk of data like synth sample wave.
375 This data type, however, can be used only for direct dispatch mode,
376 and supposed to be used only for a special purpose like a bulk data
378 The data length and pointer are stored also in
379 data.ext field as well as variable length data.
380 The flag-bit type is #SND_SEQ_EVENT_LENGTH_VARUSR.
381 A macro #snd_seq_ev_set_varusr() is provided to set this type.
383 \subsection seq_ev_sched Scheduling priority
385 There are two priorities for scheduling:
387 If an event with the same scheduling time is already present on the queue,
388 the new event is appended to the older.
390 If an event with the same scheduling time is already present on the queue,
391 the new event is inserted before others.
393 The scheduling priority is set in the flag bitfeld masked by #SND_SEQ_PRIORITY_MASK.
394 A macro #snd_seq_ev_set_priority() is provided to set the mode type.
396 \section seq_queue Event Queues
397 \subsection seq_ev_control Creation of a queue
399 Creating a queue is done usually by calling #snd_seq_alloc_queue.
400 You can create a queue with a certain name by #snd_seq_alloc_named_queue(), too.
402 // create a queue and return its id
403 int my_queue(snd_seq_t *handle)
405 return snd_seq_alloc_named_queue(handle, "my queue");
408 These functions are the wrapper to the function #snd_seq_create_queue().
409 For releasing the allocated queue, call #snd_seq_free_queue() with the
412 Once when a queue is created, the two queues are associated to that
413 queue record in fact: one is the realtime queue and another is the
414 tick queue. These two queues are bound together to work
415 synchronously. Hence, when you schedule an event, you have to choose
416 which queue type is used as described in the section \ref
419 \subsection seq_ev_tempo Setting queue tempo
421 The tempo (or the speed) of the scheduling queue is variable.
422 In the case of <i>tick</i> queue, the tempo is controlled
423 in the manner of MIDI. There are two parameters to define the
424 actual tempo, PPQ (pulse per quarter note) and MIDI tempo.
425 The former defines the base resolution of the ticks, while
426 the latter defines the beat tempo in microseconds.
427 As default, 96 PPQ and 120 BPM are used, respectively.
428 That is, the tempo is set to 500000 (= 60 * 1000000 / 120).
429 Note that PPQ cannot be changed while the queue is running.
430 It must be set before the queue is started.
432 On the other hand, in the case of <i>realtime</i> queue, the
433 time resolution is fixed to nanosecononds. There is, however,
434 a parameter to change the speed of this queue, called <i>skew</i>.
435 You can make the queue faster or slower by setting the skew value
436 bigger or smaller. In the API, the skew is defined by two values,
437 the skew base and the skew value. The actual skew is the fraction
438 of them, <i>value/base</i>. As default, the skew base is set to 16bit
439 (0x10000) and the skew value is the identical, so that the queue is
440 processed as well as in the real world.
442 When the tempo of realtime queue is changed, the tempo of
443 the associated tick queue is changed together, too.
444 That's the reason why two queues are created always.
445 This feature can be used to synchronize the event queue with
446 the external synchronization source like SMPTE. In such a case,
447 the realtime queue is skewed to match with the external source,
448 so that both the realtime timestamp and the MIDI timestamp are
451 For setting these tempo parameters, use #snd_seq_queue_tempo_t record.
452 For example, to set the tempo of the queue <code>q</code> to
455 void set_tempo(snd_seq_t *handle)
457 snd_seq_queue_tempo_t *tempo;
458 snd_seq_queue_tempo_alloca(&tempo);
459 snd_seq_queue_tempo_set_tempo(tempo, 1000000); // 60 BPM
460 snd_seq_queue_tempo_set_ppq(tempo, 48); // 48 PPQ
461 snd_seq_set_queue_tempo(handle, tempo);
465 For changing the (running) queue's tempo on the fly, you can either
466 set the tempo via #snd_seq_queue_tempo() or send a MIDI tempo event
467 to the system timer port. For example,
469 int change_tempo(snd_seq_t *handle, int q, unsigned int tempo)
472 snd_seq_ev_clear(&ev);
473 ev.dest.client = SND_SEQ_CLIENT_SYSTEM;
474 ev.dest.port = SND_SEQ_PORT_SYSTEM_TIMER;
475 ev.source.client = my_client_id;
476 ev.source.port = my_port_id;
477 ev.queue = SND_SEQ_QUEUE_DIRECT; // no scheduling
478 ev.data.queue.queue = q; // affected queue id
479 ev.data.queue.value = tempo; // new tempo in microsec.
480 return snd_seq_event_output(handle, &ev);
483 There is a helper function to do this easily,
484 #snd_seq_change_queue_tempo().
485 Set NULL to the last argument, if you don't need any
488 In the above example, the tempo is changed immediately after
489 the buffer is flushed by #snd_seq_drain_output() call.
490 You can schedule the event in a certain queue so that the tempo
491 change happes at the scheduled time, too.
493 \subsection seq_ev_start Starting and stopping a queue
495 To start, stop, or continue a queue, you need to send a queue-control
496 event to the system timer port as well. There are helper functions,
497 #snd_seq_start_queue(), #snd_seq_stop_queue() and
498 #snd_seq_continue_queue().
499 Note that if the last argument of these functions is NULL, the
500 event is sent (i.e. operated) immediately after the buffer flush.
501 If you want to schedule the event at the certain time, set up
502 the event record and provide the pointer of that event record as the
505 Only calling these functions doesn't deliver the event to the
506 sequencer core but only put to the output buffer. You'll need to
507 call #snd_seq_drain_output() eventually.
510 \section seq_subs_more More inside the subscription
512 \subsection seq_subs_perm Permissions
514 Each ALSA port can have capability flags.
515 The most basic capability flags are
516 #SND_SEQ_PORT_CAP_READ and #SND_SEQ_PORT_CAP_WRITE.
517 The former means that the port allows to send events to other ports,
518 whereas the latter capability menas
519 that the port allows to receive events from other ports.
520 You may have noticed that meanings of \c READ and \c WRITE
521 are permissions of the port from the viewpoint of other ports.
523 For allowing subscription from/to other clients, another capability
524 flags must be set together with read/write capabilities above.
525 For allowing read and write subscriptions,
526 #SND_SEQ_PORT_CAP_SUBS_READ and
527 #SND_SEQ_PORT_CAP_SUBS_WRITE are used,
529 For example, the port with MIDI input device always has
530 #SND_SEQ_PORT_CAP_SUBS_READ capability,
531 and the port with MIDI output device always has
532 #SND_SEQ_PORT_CAP_SUBS_WRITE capability together with
533 #SND_SEQ_PORT_CAP_READ and #SND_SEQ_PORT_CAP_WRITE capabilities,
535 Obviously, these flags have no influence
536 if \c READ or \c WRITE> capability is not set.
538 Note that these flags are not necessary if the client subscribes itself
539 to the spcified port.
540 For example, when a port makes READ subscription
541 to MIDI input port, this port must have #SND_SEQ_PORT_CAP_WRITE capability,
542 but no #SND_SEQ_PORT_CAP_SUBS_WRITE capability is required.
543 Only MIDI input port must have #SND_SEQ_PORT_SUBS_READ capability.
545 As default, the connection of ports via the third client is always allowed
546 if proper read and write (subscription) capabilities are set both to the
547 source and destination ports.
548 For prohibiting this behavior, set a capability
549 #SND_SEQ_PORT_CAP_NO_EXPORT to the port.
550 If this flag is set, subscription must be done by sender or receiver
552 It is useful to avoid unexpected disconnection.
553 The ports which won't accept subscription should have this capability
556 \subsection seq_subs_handle Subscription handlers
558 In ALSA library, subscription is done via
559 #snd_seq_subscribe_port() function.
560 It takes the argument of #snd_seq_port_subscribe_t record pointer.
561 Suppose that you have a client which will receive data from
562 a MIDI input device. The source and destination addresses
565 snd_seq_addr_t sender, dest;
566 sender.client = MIDI_input_client;
567 sender.port = MIDI_input_port;
568 dest.client = my_client;
571 To set these values as the connection call like this.
573 snd_seq_port_subscribe_t *subs;
574 snd_seq_port_subscribe_alloca(&subs);
575 snd_seq_port_subscribe_set_sender(subs, &sender);
576 snd_seq_port_subscribe_set_dest(subs, &dest);
577 snd_seq_subscribe_port(handle, subs);
580 When the connection should be exclusively done only between
581 a certain pair, set <i>exclusive</i> attribute to the subscription
582 record before calling #snd_seq_port_subscribe.
584 snd_seq_port_subscribe_set_exclusive(subs, 1);
586 The succeeding subscriptions will be refused.
588 The timestamp can be updated independently on each connection.
589 When set up, the timestamp of incoming queue to the destination port
590 is updated automatically to the time of the specified queue.
592 snd_seq_port_subscribe_set_time_update(subs, 1);
593 snd_seq_port_subscribe_set_queue(subs, q);
595 For getting the wallclock time (sec/nsec pair), set <i>real</i> attribute:
597 snd_seq_port_subscribe_set_time_real(subs, 1);
599 Otherwise, the timestamp is stored in tick unit.
600 This feature is useful when receiving events from MIDI input device.
601 The event time is automatically set in the event record.
603 Note that an outsider client may connect other ports.
604 In this case, however, the subscription may be refused
605 if #SND_SEQ_PORT_CAP_NO_EXPORT capability is set in either sender or receiver port.
607 \section seq_subs_ex Examples of subscription
609 \subsection seq_subs_ex_capt Capture from keyboard
611 Assume MIDI input port = 64:0, application port = 128:0, and
612 queue for timestamp = 1 with real-time stamp.
613 The application port must have capabilty #SND_SEQ_PORT_CAP_WRITE.
615 void capture_keyboard(snd_seq_t *seq)
617 snd_seq_addr_t sender, dest;
618 snd_seq_port_subscribe_t *subs;
623 snd_seq_port_subscribe_alloca(&subs);
624 snd_seq_port_subscribe_set_sender(subs, &sender);
625 snd_seq_port_subscribe_set_dest(subs, &dest);
626 snd_seq_port_subscribe_set_queue(subs, 1);
627 snd_seq_port_subscribe_set_time_update(subs, 1);
628 snd_seq_port_subscribe_set_time_real(subs, 1);
629 snd_seq_subscribe_port(seq, subs);
633 \subsection seq_subs_ex_out Output to MIDI device
635 Assume MIDI output port = 65:1 and application port = 128:0.
636 The application port must have capabilty #SND_SEQ_PORT_CAP_READ.
638 void subscribe_output(snd_seq_t *seq)
640 snd_seq_addr_t sender, dest;
641 snd_seq_port_subscribe_t *subs;
646 snd_seq_port_subscribe_alloca(&subs);
647 snd_seq_port_subscribe_set_sender(subs, &sender);
648 snd_seq_port_subscribe_set_dest(subs, &dest);
649 snd_seq_subscribe_port(seq, subs);
652 This example can be simplified by using #snd_seq_connect_to() function.
654 void subscribe_output(snd_seq_t *seq)
656 snd_seq_connect_to(seq, 0, 65, 1);
660 \subsection seq_subs_ex_arbit Arbitrary connection
662 Assume connection from application 128:0 to 129:0,
663 and that subscription is done by the third application (130:0).
664 The sender must have capabilities both
665 #SND_SEQ_PORT_CAP_READ and
666 #SND_SEQ_PORT_SUBS_READ,
668 #SND_SEQ_PORT_CAP_WRITE and
669 #SND_SEQ_PORT_CAP_SUBS_WRITE, respectively.
671 // ..in the third application (130:0) ..
672 void coupling(snd_seq_t *seq)
674 snd_seq_addr_t sender, dest;
675 snd_seq_port_subscribe_t *subs;
680 snd_seq_port_subscribe_alloca(&subs);
681 snd_seq_port_subscribe_set_sender(subs, &sender);
682 snd_seq_port_subscribe_set_dest(subs, &dest);
683 snd_seq_subscribe_port(seq, subs);
687 \section seq_ex_event Event Processing
689 \subsection seq_ex_address Addressing
691 Now, two ports are connected by subscription. Then how to send events?
693 The subscribed port doesn't have to know the exact sender address.
694 Instead, there is a special address for subscribers,
695 #SND_SEQ_ADDRESS_SUBSCRIBERS.
696 The sender must set this value as the destination client.
697 Destination port is ignored.
699 The other values in source and destination addresses are identical with
700 the normal event record.
701 If the event is scheduled, proper queue and timestamp values must be set.
703 There is a convenient function to set the address in an event record.
704 In order to set destination as subscribers, use
705 #snd_seq_ev_set_subs().
707 \subsection Scheduled Delivery
709 If we send an event at the scheduled time <code>t</code> (tick)
710 on the queue <code>Q</code>,
711 the sender must set both schedule queue and time in the
713 The program appears like this:
715 void schedule_event(snd_seq_t *seq)
719 snd_seq_ev_clear(&ev);
720 snd_seq_ev_set_source(&ev, my_port);
721 snd_seq_ev_set_subs(&ev);
722 snd_seq_ev_schedule_tick(&ev, Q, 0, t);
723 ... // set event type, data, so on..
725 snd_seq_event_output(seq, &ev);
727 snd_seq_drain_output(seq); // if necessary
730 Of course, you can use realtime stamp, too.
732 \subsection seq_ex_direct Direct Delivery
734 If the event is sent immediately without enqueued, the sender doesn't take
735 care of queue and timestamp.
736 As well as the case above, there is a function to set the direct delivery,
737 #snd_seq_ev_set_direct().
738 The program can be more simplified as follows:
740 void direct_delivery(snd_seq_t *seq)
744 snd_seq_ev_clear(&ev);
745 snd_seq_ev_set_source(&ev, port);
746 snd_seq_ev_set_subs(&ev);
747 snd_seq_ev_set_direct(&ev);
748 ... // set event type, data, so on..
750 snd_seq_event_output(seq, &ev);
751 snd_seq_drain_output(seq);
754 You should flush event soon after output event.
755 Otherwise, the event is enqueued on output queue of ALSA library
756 (not in the kernel!), and will be never processed until
757 this queue becomes full.
759 \subsection seq_ex_filter Filter Application
761 A typical filter program, which receives an event and sends it immediately
762 after some modification, will appear as following:
764 void event_filter(snd_seq_t *seq, snd_seq_event_t *ev)
766 while (snd_seq_event_input(seq, &ev) >= 0) {
767 //.. modify input event ..
769 snd_seq_ev_set_source(ev, my_port);
770 snd_seq_ev_set_subs(ev);
771 snd_seq_ev_set_direct(ev);
772 snd_seq_event_output(seq, ev);
773 snd_seq_drain_output(seq);
780 #include <sys/poll.h>
781 #include "seq_local.h"
783 /****************************************************************************
788 ****************************************************************************/
791 * \brief get identifier of sequencer handle
792 * \param seq sequencer handle
793 * \return ascii identifier of sequencer handle
795 * Returns the ASCII identifier of the given sequencer handle. It's the same
796 * identifier specified in snd_seq_open().
800 const char *snd_seq_name(snd_seq_t *seq)
807 * \brief get type of sequencer handle
808 * \param seq sequencer handle
809 * \return type of sequencer handle
811 * Returns the type #snd_seq_type_t of the given sequencer handle.
815 snd_seq_type_t snd_seq_type(snd_seq_t *seq)
821 static int snd_seq_open_conf(snd_seq_t **seqp, const char *name,
822 snd_config_t *seq_root, snd_config_t *seq_conf,
823 int streams, int mode)
828 snd_config_t *conf, *type_conf = NULL;
829 snd_config_iterator_t i, next;
831 const char *lib = NULL, *open_name = NULL;
832 int (*open_func)(snd_seq_t **, const char *,
833 snd_config_t *, snd_config_t *,
836 extern void *snd_seq_open_symbols(void);
839 if (snd_config_get_type(seq_conf) != SND_CONFIG_TYPE_COMPOUND) {
841 SNDERR("Invalid type for SEQ %s definition", name);
843 SNDERR("Invalid type for SEQ definition");
846 err = snd_config_search(seq_conf, "type", &conf);
848 SNDERR("type is not defined");
851 err = snd_config_get_id(conf, &id);
853 SNDERR("unable to get id");
856 err = snd_config_get_string(conf, &str);
858 SNDERR("Invalid type for %s", id);
861 err = snd_config_search_definition(seq_root, "seq_type", str, &type_conf);
863 if (snd_config_get_type(type_conf) != SND_CONFIG_TYPE_COMPOUND) {
864 SNDERR("Invalid type for SEQ type %s definition", str);
867 snd_config_for_each(i, next, type_conf) {
868 snd_config_t *n = snd_config_iterator_entry(i);
870 if (snd_config_get_id(n, &id) < 0)
872 if (strcmp(id, "comment") == 0)
874 if (strcmp(id, "lib") == 0) {
875 err = snd_config_get_string(n, &lib);
877 SNDERR("Invalid type for %s", id);
882 if (strcmp(id, "open") == 0) {
883 err = snd_config_get_string(n, &open_name);
885 SNDERR("Invalid type for %s", id);
890 SNDERR("Unknown field %s", id);
897 snprintf(buf, sizeof(buf), "_snd_seq_%s_open", str);
900 snd_seq_open_symbols();
902 h = snd_dlopen(lib, RTLD_NOW);
904 open_func = snd_dlsym(h, open_name, SND_DLSYM_VERSION(SND_SEQ_DLSYM_VERSION));
907 SNDERR("Cannot open shared library %s", lib);
909 } else if (!open_func) {
910 SNDERR("symbol %s is not defined inside %s", open_name, lib);
916 snd_config_delete(type_conf);
918 err = open_func(seqp, name, seq_root, seq_conf, streams, mode);
922 (*seqp)->dl_handle = h;
927 static int snd_seq_open_noupdate(snd_seq_t **seqp, snd_config_t *root,
928 const char *name, int streams, int mode,
932 snd_config_t *seq_conf;
933 err = snd_config_search_definition(root, "seq", name, &seq_conf);
935 SNDERR("Unknown SEQ %s", name);
938 snd_config_set_hop(seq_conf, hop);
939 err = snd_seq_open_conf(seqp, name, root, seq_conf, streams, mode);
940 snd_config_delete(seq_conf);
946 * \brief Open the ALSA sequencer
948 * \param seqp Pointer to a snd_seq_t pointer. This pointer must be
949 * kept and passed to most of the other sequencer functions.
950 * \param name The sequencer's "name". This is \em not a name you make
951 * up for your own purposes; it has special significance to the ALSA
952 * library. Usually you need to pass \c "default" here.
953 * \param streams The read/write mode of the sequencer. Can be one of
955 * - #SND_SEQ_OPEN_OUTPUT - open the sequencer for output only
956 * - #SND_SEQ_OPEN_INPUT - open the sequencer for input only
957 * - #SND_SEQ_OPEN_DUPLEX - open the sequencer for output and input
958 * \note Internally, these are translated to \c O_WRONLY, \c O_RDONLY and
959 * \c O_RDWR respectively and used as the second argument to the C library
961 * \param mode Optional modifier. Can be either 0, or
962 * #SND_SEQ_NONBLOCK, which will make read/write operations
963 * non-blocking. This can also be set later using #snd_seq_nonblock().
964 * \return 0 on success otherwise a negative error code
966 * Creates a new handle and opens a connection to the kernel
967 * sequencer interface.
968 * After a client is created successfully, an event
969 * with #SND_SEQ_EVENT_CLIENT_START is broadcast to announce port.
971 * \sa snd_seq_open_lconf(), snd_seq_close(), snd_seq_type(), snd_seq_name(),
972 * snd_seq_nonblock(), snd_seq_client_id()
974 int snd_seq_open(snd_seq_t **seqp, const char *name,
975 int streams, int mode)
978 assert(seqp && name);
979 err = snd_config_update();
982 return snd_seq_open_noupdate(seqp, snd_config, name, streams, mode, 0);
986 * \brief Open the ALSA sequencer using local configuration
988 * \param seqp Pointer to a snd_seq_t pointer.
989 * \param name The name to open
990 * \param streams The read/write mode of the sequencer.
991 * \param mode Optional modifier
992 * \param lconf Local configuration
993 * \return 0 on success otherwise a negative error code
995 * See the snd_seq_open() function for further details. The extension
996 * is that the given configuration is used to resolve abstract name.
1000 int snd_seq_open_lconf(snd_seq_t **seqp, const char *name,
1001 int streams, int mode, snd_config_t *lconf)
1003 assert(seqp && name && lconf);
1004 return snd_seq_open_noupdate(seqp, lconf, name, streams, mode, 0);
1008 int _snd_seq_open_lconf(snd_seq_t **seqp, const char *name,
1009 int streams, int mode, snd_config_t *lconf,
1010 snd_config_t *parent_conf)
1013 assert(seqp && name && lconf);
1014 if ((hop = snd_config_check_hop(parent_conf)) < 0)
1016 return snd_seq_open_noupdate(seqp, lconf, name, streams, mode, hop + 1);
1021 * \brief Close the sequencer
1022 * \param seq Handle returned from #snd_seq_open()
1023 * \return 0 on success otherwise a negative error code
1025 * Closes the sequencer client and releases its resources.
1026 * After a client is closed, an event with
1027 * #SND_SEQ_EVENT_CLIENT_EXIT is broadcast to announce port.
1028 * The connection between other clients are disconnected.
1029 * Call this just before exiting your program.
1031 * \sa snd_seq_close()
1033 int snd_seq_close(snd_seq_t *seq)
1037 err = seq->ops->close(seq);
1039 snd_dlclose(seq->dl_handle);
1049 * \brief Returns the number of poll descriptors
1050 * \param seq sequencer handle
1051 * \param events the poll events to be checked (\c POLLIN and \c POLLOUT)
1052 * \return the number of poll descriptors.
1054 * Get the number of poll descriptors. The polling events to be checked
1055 * can be specified by the second argument. When both input and output
1056 * are checked, pass \c POLLIN|POLLOUT
1058 * \sa snd_seq_poll_descriptors()
1060 int snd_seq_poll_descriptors_count(snd_seq_t *seq, short events)
1064 if (events & POLLIN) {
1065 assert(seq->streams & SND_SEQ_OPEN_INPUT);
1068 if (events & POLLOUT) {
1069 assert(seq->streams & SND_SEQ_OPEN_OUTPUT);
1072 return result ? 1 : 0;
1076 * \brief Get poll descriptors
1077 * \param seq sequencer handle
1078 * \param pfds array of poll descriptors
1079 * \param space space in the poll descriptor array
1080 * \param events polling events to be checked (\c POLLIN and \c POLLOUT)
1081 * \return count of filled descriptors
1083 * Get poll descriptors assigned to the sequencer handle.
1084 * Since a sequencer handle can duplex streams, you need to set which direction(s)
1085 * is/are polled in \a events argument. When \c POLLIN bit is specified,
1086 * the incoming events to the ports are checked.
1088 * To check the returned poll-events, call #snd_seq_poll_descriptors_revents()
1089 * instead of reading the pollfd structs directly.
1091 * \sa snd_seq_poll_descriptors_count(), snd_seq_poll_descriptors_revents()
1093 int snd_seq_poll_descriptors(snd_seq_t *seq, struct pollfd *pfds, unsigned int space, short events)
1098 if ((events & POLLIN) && space >= 1) {
1099 assert(seq->streams & SND_SEQ_OPEN_INPUT);
1100 revents |= POLLIN|POLLERR|POLLNVAL;
1102 if ((events & POLLOUT) && space >= 1) {
1103 assert(seq->streams & SND_SEQ_OPEN_OUTPUT);
1104 revents |= POLLOUT|POLLERR|POLLNVAL;
1108 pfds->fd = seq->poll_fd;
1109 pfds->events = revents;
1114 * \brief get returned events from poll descriptors
1115 * \param seq sequencer handle
1116 * \param pfds array of poll descriptors
1117 * \param nfds count of poll descriptors
1118 * \param revents returned events
1119 * \return zero if success, otherwise a negative error code
1121 * \sa snd_seq_poll_descriptors()
1123 int snd_seq_poll_descriptors_revents(snd_seq_t *seq, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
1125 assert(seq && pfds && revents);
1127 *revents = pfds->revents;
1134 * \brief Set nonblock mode
1135 * \param seq sequencer handle
1136 * \param nonblock 0 = block, 1 = nonblock mode
1137 * \return 0 on success otherwise a negative error code
1139 * Change the blocking mode of the given client.
1140 * In block mode, the client falls into sleep when it fills the
1141 * output memory pool with full events. The client will be woken up
1142 * after a certain amount of free space becomes available.
1144 * \sa snd_seq_open()
1146 int snd_seq_nonblock(snd_seq_t *seq, int nonblock)
1150 err = seq->ops->nonblock(seq, nonblock);
1154 seq->mode |= SND_SEQ_NONBLOCK;
1156 seq->mode &= ~SND_SEQ_NONBLOCK;
1161 * \brief Get the client id
1162 * \param seq sequencer handle
1163 * \return the client id
1165 * Returns the id of the specified client.
1166 * If an error occurs, function returns the negative error code.
1167 * A client id is necessary to inquiry or to set the client information.
1168 * A user client is assigned from 128 to 191.
1170 * \sa snd_seq_open()
1172 int snd_seq_client_id(snd_seq_t *seq)
1179 * \brief Return the size of output buffer
1180 * \param seq sequencer handle
1181 * \return the size of output buffer in bytes
1183 * Obtains the size of output buffer.
1184 * This buffer is used to store decoded byte-stream of output events
1185 * before transferring to sequencer.
1187 * \sa snd_seq_set_output_buffer_size()
1189 size_t snd_seq_get_output_buffer_size(snd_seq_t *seq)
1194 return seq->obufsize;
1198 * \brief Return the size of input buffer
1199 * \param seq sequencer handle
1200 * \return the size of input buffer in bytes
1202 * Obtains the size of input buffer.
1203 * This buffer is used to read byte-stream of input events from sequencer.
1205 * \sa snd_seq_set_input_buffer_size()
1207 size_t snd_seq_get_input_buffer_size(snd_seq_t *seq)
1212 return seq->ibufsize * sizeof(snd_seq_event_t);
1216 * \brief Change the size of output buffer
1217 * \param seq sequencer handle
1218 * \param size the size of output buffer to be changed in bytes
1219 * \return 0 on success otherwise a negative error code
1221 * Changes the size of output buffer.
1223 * \sa snd_seq_get_output_buffer_size()
1225 int snd_seq_set_output_buffer_size(snd_seq_t *seq, size_t size)
1227 assert(seq && seq->obuf);
1228 assert(size >= sizeof(snd_seq_event_t));
1229 snd_seq_drop_output(seq);
1230 if (size != seq->obufsize) {
1232 newbuf = calloc(1, size);
1237 seq->obufsize = size;
1243 * \brief Resize the input buffer
1244 * \param seq sequencer handle
1245 * \param size the size of input buffer to be changed in bytes
1246 * \return 0 on success otherwise a negative error code
1248 * Changes the size of input buffer.
1250 * \sa snd_seq_get_input_buffer_size()
1252 int snd_seq_set_input_buffer_size(snd_seq_t *seq, size_t size)
1254 assert(seq && seq->ibuf);
1255 assert(size >= sizeof(snd_seq_event_t));
1256 snd_seq_drop_input(seq);
1257 size = (size + sizeof(snd_seq_event_t) - 1) / sizeof(snd_seq_event_t);
1258 if (size != seq->ibufsize) {
1259 snd_seq_event_t *newbuf;
1260 newbuf = calloc(sizeof(snd_seq_event_t), size);
1265 seq->ibufsize = size;
1272 * \brief Get size of #snd_seq_system_info_t
1273 * \return size in bytes
1275 size_t snd_seq_system_info_sizeof()
1277 return sizeof(snd_seq_system_info_t);
1281 * \brief Allocate an empty #snd_seq_system_info_t using standard malloc
1282 * \param ptr returned pointer
1283 * \return 0 on success otherwise negative error code
1285 int snd_seq_system_info_malloc(snd_seq_system_info_t **ptr)
1288 *ptr = calloc(1, sizeof(snd_seq_system_info_t));
1295 * \brief Frees a previously allocated #snd_seq_system_info_t
1296 * \param obj pointer to object to free
1298 void snd_seq_system_info_free(snd_seq_system_info_t *obj)
1304 * \brief Copy one #snd_seq_system_info_t to another
1305 * \param dst pointer to destination
1306 * \param src pointer to source
1308 void snd_seq_system_info_copy(snd_seq_system_info_t *dst, const snd_seq_system_info_t *src)
1316 * \brief Get maximum number of queues
1317 * \param info #snd_seq_system_info_t container
1318 * \return maximum number of queues
1320 * \sa snd_seq_system_info()
1322 int snd_seq_system_info_get_queues(const snd_seq_system_info_t *info)
1325 return info->queues;
1329 * \brief Get maximum number of clients
1330 * \param info #snd_seq_system_info_t container
1331 * \return maximum number of clients
1333 * \sa snd_seq_system_info()
1335 int snd_seq_system_info_get_clients(const snd_seq_system_info_t *info)
1338 return info->clients;
1342 * \brief Get maximum number of ports
1343 * \param info #snd_seq_system_info_t container
1344 * \return maximum number of ports
1346 * \sa snd_seq_system_info()
1348 int snd_seq_system_info_get_ports(const snd_seq_system_info_t *info)
1355 * \brief Get maximum number of channels
1356 * \param info #snd_seq_system_info_t container
1357 * \return maximum number of channels
1359 * \sa snd_seq_system_info()
1361 int snd_seq_system_info_get_channels(const snd_seq_system_info_t *info)
1364 return info->channels;
1368 * \brief Get the current number of clients
1369 * \param info #snd_seq_system_info_t container
1370 * \return current number of clients
1372 * \sa snd_seq_system_info()
1374 int snd_seq_system_info_get_cur_clients(const snd_seq_system_info_t *info)
1377 return info->cur_clients;
1381 * \brief Get the current number of queues
1382 * \param info #snd_seq_system_info_t container
1383 * \return current number of queues
1385 * \sa snd_seq_system_info()
1387 int snd_seq_system_info_get_cur_queues(const snd_seq_system_info_t *info)
1390 return info->cur_queues;
1394 * \brief obtain the sequencer system information
1395 * \param seq sequencer handle
1396 * \param info the pointer to be stored
1397 * \return 0 on success otherwise a negative error code
1399 * Stores the global system information of ALSA sequencer system.
1400 * The returned data contains
1401 * the maximum available numbers of queues, clients, ports and channels.
1403 int snd_seq_system_info(snd_seq_t *seq, snd_seq_system_info_t * info)
1405 assert(seq && info);
1406 return seq->ops->system_info(seq, info);
1410 /*----------------------------------------------------------------*/
1413 * \brief get size of #snd_seq_client_info_t
1414 * \return size in bytes
1416 size_t snd_seq_client_info_sizeof()
1418 return sizeof(snd_seq_client_info_t);
1422 * \brief allocate an empty #snd_seq_client_info_t using standard malloc
1423 * \param ptr returned pointer
1424 * \return 0 on success otherwise negative error code
1426 int snd_seq_client_info_malloc(snd_seq_client_info_t **ptr)
1429 *ptr = calloc(1, sizeof(snd_seq_client_info_t));
1436 * \brief frees a previously allocated #snd_seq_client_info_t
1437 * \param obj pointer to object to free
1439 void snd_seq_client_info_free(snd_seq_client_info_t *obj)
1445 * \brief copy one #snd_seq_client_info_t to another
1446 * \param dst pointer to destination
1447 * \param src pointer to source
1449 void snd_seq_client_info_copy(snd_seq_client_info_t *dst, const snd_seq_client_info_t *src)
1457 * \brief Get client id of a client_info container
1458 * \param info client_info container
1461 * \sa snd_seq_get_client_info(), snd_seq_client_info_set_client(), snd_seq_client_id()
1463 int snd_seq_client_info_get_client(const snd_seq_client_info_t *info)
1466 return info->client;
1470 * \brief Get client type of a client_info container
1471 * \param info client_info container
1472 * \return client type
1474 * The client type is either #SEQ_CLIENT_TYPE_KERNEL or #SEQ_CLIENT_TYPE_USER
1475 * for kernel or user client respectively.
1477 * \sa snd_seq_get_client_info()
1479 snd_seq_client_type_t snd_seq_client_info_get_type(const snd_seq_client_info_t *info)
1486 * \brief Get the name of a client_info container
1487 * \param info client_info container
1488 * \return name string
1490 * \sa snd_seq_get_client_info(), snd_seq_client_info_set_name()
1492 const char *snd_seq_client_info_get_name(snd_seq_client_info_t *info)
1499 * \brief Get the broadcast filter usage of a client_info container
1500 * \param info client_info container
1501 * \return 1 if broadcast is accepted
1503 * \sa snd_seq_get_client_info(), snd_seq_client_info_set_broadcast_filter()
1505 int snd_seq_client_info_get_broadcast_filter(const snd_seq_client_info_t *info)
1508 return (info->filter & SNDRV_SEQ_FILTER_BROADCAST) ? 1 : 0;
1512 * \brief Get the error-bounce usage of a client_info container
1513 * \param info client_info container
1514 * \return 1 if error-bounce is enabled
1516 * \sa snd_seq_get_client_info(), snd_seq_client_info_set_error_bounce()
1518 int snd_seq_client_info_get_error_bounce(const snd_seq_client_info_t *info)
1521 return (info->filter & SNDRV_SEQ_FILTER_BOUNCE) ? 1 : 0;
1525 * \brief Get the event filter bitmap of a client_info container
1526 * \param info client_info container
1527 * \return NULL if no event filter, or pointer to event filter bitmap
1529 * \sa snd_seq_get_client_info(), snd_seq_client_info_set_event_filter()
1531 const unsigned char *snd_seq_client_info_get_event_filter(const snd_seq_client_info_t *info)
1534 if (info->filter & SNDRV_SEQ_FILTER_USE_EVENT)
1535 return info->event_filter;
1541 * \brief Get the number of opened ports of a client_info container
1542 * \param info client_info container
1543 * \return number of opened ports
1545 * \sa snd_seq_get_client_info()
1547 int snd_seq_client_info_get_num_ports(const snd_seq_client_info_t *info)
1550 return info->num_ports;
1554 * \brief Get the number of lost events of a client_info container
1555 * \param info client_info container
1556 * \return number of lost events
1558 * \sa snd_seq_get_client_info()
1560 int snd_seq_client_info_get_event_lost(const snd_seq_client_info_t *info)
1563 return info->event_lost;
1567 * \brief Set the client id of a client_info container
1568 * \param info client_info container
1569 * \param client client id
1571 * \sa snd_seq_get_client_info(), snd_seq_client_info_get_client()
1573 void snd_seq_client_info_set_client(snd_seq_client_info_t *info, int client)
1576 info->client = client;
1580 * \brief Set the name of a client_info container
1581 * \param info client_info container
1582 * \param name name string
1584 * \sa snd_seq_get_client_info(), snd_seq_client_info_get_name(),
1585 * snd_seq_set_client_name()
1587 void snd_seq_client_info_set_name(snd_seq_client_info_t *info, const char *name)
1589 assert(info && name);
1590 strncpy(info->name, name, sizeof(info->name));
1594 * \brief Set the broadcast filter usage of a client_info container
1595 * \param info client_info container
1596 * \param val non-zero if broadcast is accepted
1598 * \sa snd_seq_get_client_info(), snd_seq_client_info_get_broadcast_filter()
1600 void snd_seq_client_info_set_broadcast_filter(snd_seq_client_info_t *info, int val)
1604 info->filter |= SNDRV_SEQ_FILTER_BROADCAST;
1606 info->filter &= ~SNDRV_SEQ_FILTER_BROADCAST;
1610 * \brief Set the error-bounce usage of a client_info container
1611 * \param info client_info container
1612 * \param val non-zero if error is bounced
1614 * \sa snd_seq_get_client_info(), snd_seq_client_info_get_error_bounce()
1616 void snd_seq_client_info_set_error_bounce(snd_seq_client_info_t *info, int val)
1620 info->filter |= SNDRV_SEQ_FILTER_BOUNCE;
1622 info->filter &= ~SNDRV_SEQ_FILTER_BOUNCE;
1626 * \brief Set the event filter bitmap of a client_info container
1627 * \param info client_info container
1628 * \param filter event filter bitmap
1630 * \sa snd_seq_get_client_info(), snd_seq_client_info_get_event_filger(),
1631 * snd_seq_set_client_event_filter()
1633 void snd_seq_client_info_set_event_filter(snd_seq_client_info_t *info, unsigned char *filter)
1637 info->filter &= ~SNDRV_SEQ_FILTER_USE_EVENT;
1639 info->filter |= SNDRV_SEQ_FILTER_USE_EVENT;
1640 memcpy(info->event_filter, filter, sizeof(info->event_filter));
1646 * \brief obtain the information of the given client
1647 * \param seq sequencer handle
1648 * \param client client id
1649 * \param info the pointer to be stored
1650 * \return 0 on success otherwise a negative error code
1652 * Obtains the information of the client with a client id specified by
1654 * The obtained information is written on info parameter.
1656 * \sa snd_seq_get_client_info()
1658 int snd_seq_get_any_client_info(snd_seq_t *seq, int client, snd_seq_client_info_t *info)
1660 assert(seq && info && client >= 0);
1661 memset(info, 0, sizeof(snd_seq_client_info_t));
1662 info->client = client;
1663 return seq->ops->get_client_info(seq, info);
1667 * \brief obtain the current client information
1668 * \param seq sequencer handle
1669 * \param info the pointer to be stored
1670 * \return 0 on success otherwise a negative error code
1672 * Obtains the information of the current client stored on info.
1673 * client and type fields are ignored.
1675 * \sa snd_seq_get_any_client_info(), snd_seq_set_client_info(),
1676 * snd_seq_query_next_client()
1678 int snd_seq_get_client_info(snd_seq_t *seq, snd_seq_client_info_t *info)
1680 return snd_seq_get_any_client_info(seq, seq->client, info);
1684 * \brief set the current client information
1685 * \param seq sequencer handle
1686 * \param info the client info data to set
1687 * \return 0 on success otherwise a negative error code
1689 * Obtains the information of the current client stored on info.
1690 * client and type fields are ignored.
1692 * \sa snd_seq_get_client_info()
1694 int snd_seq_set_client_info(snd_seq_t *seq, snd_seq_client_info_t *info)
1696 assert(seq && info);
1697 info->client = seq->client;
1698 info->type = USER_CLIENT;
1699 return seq->ops->set_client_info(seq, info);
1703 * \brief query the next client
1704 * \param seq sequencer handle
1705 * \param info query pattern and result
1707 * Queries the next client.
1708 * The search begins at the client with an id one greater than
1709 * client field in info.
1710 * If a client is found, its attributes are stored in info,
1711 * and zero is returned.
1712 * Otherwise returns a negative error code.
1714 * \sa snd_seq_get_any_client_info()
1716 int snd_seq_query_next_client(snd_seq_t *seq, snd_seq_client_info_t *info)
1718 assert(seq && info);
1719 return seq->ops->query_next_client(seq, info);
1723 /*----------------------------------------------------------------*/
1731 * \brief get size of #snd_seq_port_info_t
1732 * \return size in bytes
1734 size_t snd_seq_port_info_sizeof()
1736 return sizeof(snd_seq_port_info_t);
1740 * \brief allocate an empty #snd_seq_port_info_t using standard malloc
1741 * \param ptr returned pointer
1742 * \return 0 on success otherwise negative error code
1744 int snd_seq_port_info_malloc(snd_seq_port_info_t **ptr)
1747 *ptr = calloc(1, sizeof(snd_seq_port_info_t));
1754 * \brief frees a previously allocated #snd_seq_port_info_t
1755 * \param obj pointer to object to free
1757 void snd_seq_port_info_free(snd_seq_port_info_t *obj)
1763 * \brief copy one #snd_seq_port_info_t to another
1764 * \param dst pointer to destination
1765 * \param src pointer to source
1767 void snd_seq_port_info_copy(snd_seq_port_info_t *dst, const snd_seq_port_info_t *src)
1775 * \brief Get client id of a port_info container
1776 * \param info port_info container
1779 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_client()
1781 int snd_seq_port_info_get_client(const snd_seq_port_info_t *info)
1784 return info->addr.client;
1788 * \brief Get port id of a port_info container
1789 * \param info port_info container
1792 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_port()
1794 int snd_seq_port_info_get_port(const snd_seq_port_info_t *info)
1797 return info->addr.port;
1801 * \brief Get client/port address of a port_info container
1802 * \param info port_info container
1803 * \return client/port address pointer
1805 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_addr()
1807 const snd_seq_addr_t *snd_seq_port_info_get_addr(const snd_seq_port_info_t *info)
1814 * \brief Get the name of a port_info container
1815 * \param info port_info container
1816 * \return name string
1818 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_name()
1820 const char *snd_seq_port_info_get_name(const snd_seq_port_info_t *info)
1827 * \brief Get the capability bits of a port_info container
1828 * \param info port_info container
1829 * \return capability bits
1831 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_capability()
1833 unsigned int snd_seq_port_info_get_capability(const snd_seq_port_info_t *info)
1836 return info->capability;
1840 * \brief Get the type bits of a port_info container
1841 * \param info port_info container
1842 * \return port type bits
1844 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_type()
1846 unsigned int snd_seq_port_info_get_type(const snd_seq_port_info_t *info)
1853 * \brief Get the number of read subscriptions of a port_info container
1854 * \param info port_info container
1855 * \return number of read subscriptions
1857 * \sa snd_seq_get_port_info()
1859 int snd_seq_port_info_get_read_use(const snd_seq_port_info_t *info)
1862 return info->read_use;
1866 * \brief Get the number of write subscriptions of a port_info container
1867 * \param info port_info container
1868 * \return number of write subscriptions
1870 * \sa snd_seq_get_port_info()
1872 int snd_seq_port_info_get_write_use(const snd_seq_port_info_t *info)
1875 return info->write_use;
1879 * \brief Get the midi channels of a port_info container
1880 * \param info port_info container
1881 * \return number of midi channels (default 0)
1883 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_midi_channels()
1885 int snd_seq_port_info_get_midi_channels(const snd_seq_port_info_t *info)
1888 return info->midi_channels;
1892 * \brief Get the midi voices of a port_info container
1893 * \param info port_info container
1894 * \return number of midi voices (default 0)
1896 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_midi_voices()
1898 int snd_seq_port_info_get_midi_voices(const snd_seq_port_info_t *info)
1901 return info->midi_voices;
1905 * \brief Get the synth voices of a port_info container
1906 * \param info port_info container
1907 * \return number of synth voices (default 0)
1909 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_synth_voices()
1911 int snd_seq_port_info_get_synth_voices(const snd_seq_port_info_t *info)
1914 return info->synth_voices;
1918 * \brief Get the port-specified mode of a port_info container
1919 * \param info port_info container
1920 * \return 1 if port id is specified at creation
1922 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_port_specified()
1924 int snd_seq_port_info_get_port_specified(const snd_seq_port_info_t *info)
1927 return (info->flags & SNDRV_SEQ_PORT_FLG_GIVEN_PORT) ? 1 : 0;
1931 * \brief Get the time-stamping mode of the given port in a port_info container
1932 * \param info port_info container
1933 * \return 1 if the port updates timestamps of incoming events
1935 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_timestamping()
1937 int snd_seq_port_info_get_timestamping(const snd_seq_port_info_t *info)
1940 return (info->flags & SNDRV_SEQ_PORT_FLG_TIMESTAMP) ? 1 : 0;
1944 * \brief Get whether the time-stamping of the given port is real-time mode
1945 * \param info port_info container
1946 * \return 1 if the time-stamping is in the real-time mode
1948 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_timestamp_real()
1950 int snd_seq_port_info_get_timestamp_real(const snd_seq_port_info_t *info)
1953 return (info->flags & SNDRV_SEQ_PORT_FLG_TIME_REAL) ? 1 : 0;
1957 * \brief Get the queue id to update timestamps
1958 * \param info port_info container
1959 * \return the queue id to get the timestamps
1961 * \sa snd_seq_get_port_info(), snd_seq_port_info_set_timestamp_queue()
1963 int snd_seq_port_info_get_timestamp_queue(const snd_seq_port_info_t *info)
1966 return info->time_queue;
1970 * \brief Set the client id of a port_info container
1971 * \param info port_info container
1972 * \param client client id
1974 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_client()
1976 void snd_seq_port_info_set_client(snd_seq_port_info_t *info, int client)
1979 info->addr.client = client;
1983 * \brief Set the port id of a port_info container
1984 * \param info port_info container
1985 * \param port port id
1987 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_port()
1989 void snd_seq_port_info_set_port(snd_seq_port_info_t *info, int port)
1992 info->addr.port = port;
1996 * \brief Set the client/port address of a port_info container
1997 * \param info port_info container
1998 * \param addr client/port address
2000 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_addr()
2002 void snd_seq_port_info_set_addr(snd_seq_port_info_t *info, const snd_seq_addr_t *addr)
2009 * \brief Set the name of a port_info container
2010 * \param info port_info container
2011 * \param name name string
2013 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_name()
2015 void snd_seq_port_info_set_name(snd_seq_port_info_t *info, const char *name)
2017 assert(info && name);
2018 strncpy(info->name, name, sizeof(info->name));
2022 * \brief set the capability bits of a port_info container
2023 * \param info port_info container
2024 * \param capability capability bits
2026 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_capability()
2028 void snd_seq_port_info_set_capability(snd_seq_port_info_t *info, unsigned int capability)
2031 info->capability = capability;
2035 * \brief Get the type bits of a port_info container
2036 * \param info port_info container
2037 * \param type port type bits
2039 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_type()
2041 void snd_seq_port_info_set_type(snd_seq_port_info_t *info, unsigned int type)
2048 * \brief set the midi channels of a port_info container
2049 * \param info port_info container
2050 * \param channels midi channels (default 0)
2052 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_midi_channels()
2054 void snd_seq_port_info_set_midi_channels(snd_seq_port_info_t *info, int channels)
2057 info->midi_channels = channels;
2061 * \brief set the midi voices of a port_info container
2062 * \param info port_info container
2063 * \param voices midi voices (default 0)
2065 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_midi_voices()
2067 void snd_seq_port_info_set_midi_voices(snd_seq_port_info_t *info, int voices)
2070 info->midi_voices = voices;
2074 * \brief set the synth voices of a port_info container
2075 * \param info port_info container
2076 * \param voices synth voices (default 0)
2078 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_synth_voice()
2080 void snd_seq_port_info_set_synth_voices(snd_seq_port_info_t *info, int voices)
2083 info->synth_voices = voices;
2087 * \brief Set the port-specified mode of a port_info container
2088 * \param info port_info container
2089 * \param val non-zero if specifying the port id at creation
2091 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_port_specified()
2093 void snd_seq_port_info_set_port_specified(snd_seq_port_info_t *info, int val)
2097 info->flags |= SNDRV_SEQ_PORT_FLG_GIVEN_PORT;
2099 info->flags &= ~SNDRV_SEQ_PORT_FLG_GIVEN_PORT;
2103 * \brief Set the time-stamping mode of the given port
2104 * \param info port_info container
2105 * \param enable non-zero if updating the timestamps of incoming events
2107 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_timestamping()
2109 void snd_seq_port_info_set_timestamping(snd_seq_port_info_t *info, int enable)
2113 info->flags |= SNDRV_SEQ_PORT_FLG_TIMESTAMP;
2115 info->flags &= ~SNDRV_SEQ_PORT_FLG_TIMESTAMP;
2119 * \brief Set whether the timestime is updated in the real-time mode
2120 * \param info port_info container
2121 * \param enable non-zero if updating the timestamps in real-time mode
2123 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_timestamp_real()
2125 void snd_seq_port_info_set_timestamp_real(snd_seq_port_info_t *info, int enable)
2129 info->flags |= SNDRV_SEQ_PORT_FLG_TIME_REAL;
2131 info->flags &= ~SNDRV_SEQ_PORT_FLG_TIME_REAL;
2135 * \brief Set the queue id for timestamping
2136 * \param info port_info container
2137 * \param queue the queue id to get timestamps
2139 * \sa snd_seq_get_port_info(), snd_seq_port_info_get_timestamp_queue()
2141 void snd_seq_port_info_set_timestamp_queue(snd_seq_port_info_t *info, int queue)
2144 info->time_queue = queue;
2149 * \brief create a sequencer port on the current client
2150 * \param seq sequencer handle
2151 * \param port port information for the new port
2152 * \return 0 on success otherwise a negative error code
2154 * Creates a sequencer port on the current client.
2155 * The attributes of created port is specified in \a info argument.
2157 * The client field in \a info argument is overwritten with the current client id.
2158 * The port id to be created can be specified via #snd_seq_port_info_set_port_specified.
2159 * You can get the created port id by reading the port pointer via #snd_seq_port_info_get_port.
2161 * Each port has the capability bit-masks to specify the access capability
2162 * of the port from other clients.
2163 * The capability bit flags are defined as follows:
2164 * - #SND_SEQ_PORT_CAP_READ Readable from this port
2165 * - #SND_SEQ_PORT_CAP_WRITE Writable to this port.
2166 * - #SND_SEQ_PORT_CAP_SYNC_READ For synchronization (not implemented)
2167 * - #SND_SEQ_PORT_CAP_SYNC_WRITE For synchronization (not implemented)
2168 * - #SND_SEQ_PORT_CAP_DUPLEX Read/write duplex access is supported
2169 * - #SND_SEQ_PORT_CAP_SUBS_READ Read subscription is allowed
2170 * - #SND_SEQ_PORT_CAP_SUBS_WRITE Write subscription is allowed
2171 * - #SND_SEQ_PORT_CAP_NO_EXPORT Subscription management from 3rd client is disallowed
2173 * Each port has also the type bitmasks defined as follows:
2174 * - #SND_SEQ_PORT_TYPE_SPECIFIC Hardware specific port
2175 * - #SND_SEQ_PORT_TYPE_MIDI_GENERIC Generic MIDI device
2176 * - #SND_SEQ_PORT_TYPE_MIDI_GM General MIDI compatible device
2177 * - #SND_SEQ_PORT_TYPE_MIDI_GM2 General MIDI 2 compatible device
2178 * - #SND_SEQ_PORT_TYPE_MIDI_GS GS compatible device
2179 * - #SND_SEQ_PORT_TYPE_MIDI_XG XG compatible device
2180 * - #SND_SEQ_PORT_TYPE_MIDI_MT32 MT-32 compatible device
2181 * - #SND_SEQ_PORT_TYPE_HARDWARE Implemented in hardware
2182 * - #SND_SEQ_PORT_TYPE_SOFTWARE Implemented in software
2183 * - #SND_SEQ_PORT_TYPE_SYNTHESIZER Generates sound
2184 * - #SND_SEQ_PORT_TYPE_PORT Connects to other device(s)
2185 * - #SND_SEQ_PORT_TYPE_APPLICATION Application (sequencer/editor)
2187 * A port may contain specific midi channels, midi voices and synth voices.
2188 * These values could be zero as default.
2190 * \sa snd_seq_delete_port(), snd_seq_get_port_info(),
2191 * snd_seq_create_simple_port()
2193 int snd_seq_create_port(snd_seq_t *seq, snd_seq_port_info_t * port)
2195 assert(seq && port);
2196 port->addr.client = seq->client;
2197 return seq->ops->create_port(seq, port);
2201 * \brief delete a sequencer port on the current client
2202 * \param seq sequencer handle
2203 * \param port port to be deleted
2204 * \return 0 on success otherwise a negative error code
2206 * Deletes the existing sequencer port on the current client.
2208 * \sa snd_seq_create_port(), snd_seq_delete_simple_port()
2210 int snd_seq_delete_port(snd_seq_t *seq, int port)
2212 snd_seq_port_info_t pinfo;
2214 memset(&pinfo, 0, sizeof(pinfo));
2215 pinfo.addr.client = seq->client;
2216 pinfo.addr.port = port;
2217 return seq->ops->delete_port(seq, &pinfo);
2221 * \brief obtain the information of a port on an arbitrary client
2222 * \param seq sequencer handle
2223 * \param client client id to get
2224 * \param port port id to get
2225 * \param info pointer information returns
2226 * \return 0 on success otherwise a negative error code
2228 * \sa snd_seq_get_port_info()
2230 int snd_seq_get_any_port_info(snd_seq_t *seq, int client, int port, snd_seq_port_info_t * info)
2232 assert(seq && info && client >= 0 && port >= 0);
2233 memset(info, 0, sizeof(snd_seq_port_info_t));
2234 info->addr.client = client;
2235 info->addr.port = port;
2236 return seq->ops->get_port_info(seq, info);
2240 * \brief obtain the information of a port on the current client
2241 * \param seq sequencer handle
2242 * \param port port id to get
2243 * \param info pointer information returns
2244 * \return 0 on success otherwise a negative error code
2246 * \sa snd_seq_create_port(), snd_seq_get_any_port_info(), snd_seq_set_port_info(),
2247 * snd_seq_query_next_port()
2249 int snd_seq_get_port_info(snd_seq_t *seq, int port, snd_seq_port_info_t * info)
2251 return snd_seq_get_any_port_info(seq, seq->client, port, info);
2255 * \brief set the information of a port on the current client
2256 * \param seq sequencer handle
2257 * \param port port to be set
2258 * \param info port information to be set
2259 * \return 0 on success otherwise a negative error code
2261 * \sa snd_seq_set_port_info()
2263 int snd_seq_set_port_info(snd_seq_t *seq, int port, snd_seq_port_info_t * info)
2265 assert(seq && info && port >= 0);
2266 info->addr.client = seq->client;
2267 info->addr.port = port;
2268 return seq->ops->set_port_info(seq, info);
2272 * \brief query the next matching port
2273 * \param seq sequencer handle
2274 * \param info query pattern and result
2276 * Queries the next matching port on the client specified in
2278 * The search begins at the next port specified in
2279 * port field of \a info argument.
2280 * For finding the first port at a certain client, give -1.
2282 * If a matching port is found, its attributes are stored on
2283 * \a info and function returns zero.
2284 * Otherwise, a negative error code is returned.
2286 * \sa snd_seq_get_port_info()
2288 int snd_seq_query_next_port(snd_seq_t *seq, snd_seq_port_info_t *info)
2290 assert(seq && info);
2291 return seq->ops->query_next_port(seq, info);
2295 /*----------------------------------------------------------------*/
2303 * \brief get size of #snd_seq_port_subscribe_t
2304 * \return size in bytes
2306 size_t snd_seq_port_subscribe_sizeof()
2308 return sizeof(snd_seq_port_subscribe_t);
2312 * \brief allocate an empty #snd_seq_port_subscribe_t using standard malloc
2313 * \param ptr returned pointer
2314 * \return 0 on success otherwise negative error code
2316 int snd_seq_port_subscribe_malloc(snd_seq_port_subscribe_t **ptr)
2319 *ptr = calloc(1, sizeof(snd_seq_port_subscribe_t));
2326 * \brief frees a previously allocated #snd_seq_port_subscribe_t
2327 * \param obj pointer to object to free
2329 void snd_seq_port_subscribe_free(snd_seq_port_subscribe_t *obj)
2335 * \brief copy one #snd_seq_port_subscribe_t to another
2336 * \param dst pointer to destination
2337 * \param src pointer to source
2339 void snd_seq_port_subscribe_copy(snd_seq_port_subscribe_t *dst, const snd_seq_port_subscribe_t *src)
2347 * \brief Get sender address of a port_subscribe container
2348 * \param info port_subscribe container
2350 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_set_sender()
2352 const snd_seq_addr_t *snd_seq_port_subscribe_get_sender(const snd_seq_port_subscribe_t *info)
2355 return &info->sender;
2359 * \brief Get destination address of a port_subscribe container
2360 * \param info port_subscribe container
2362 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_set_dest()
2364 const snd_seq_addr_t *snd_seq_port_subscribe_get_dest(const snd_seq_port_subscribe_t *info)
2371 * \brief Get the queue id of a port_subscribe container
2372 * \param info port_subscribe container
2375 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_set_queue()
2377 int snd_seq_port_subscribe_get_queue(const snd_seq_port_subscribe_t *info)
2384 * \brief Get the exclusive mode of a port_subscribe container
2385 * \param info port_subscribe container
2386 * \return 1 if exclusive mode
2388 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_set_exclusive()
2390 int snd_seq_port_subscribe_get_exclusive(const snd_seq_port_subscribe_t *info)
2393 return (info->flags & SNDRV_SEQ_PORT_SUBS_EXCLUSIVE) ? 1 : 0;
2397 * \brief Get the time-update mode of a port_subscribe container
2398 * \param info port_subscribe container
2399 * \return 1 if update timestamp
2401 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_set_time_update()
2403 int snd_seq_port_subscribe_get_time_update(const snd_seq_port_subscribe_t *info)
2406 return (info->flags & SNDRV_SEQ_PORT_SUBS_TIMESTAMP) ? 1 : 0;
2410 * \brief Get the real-time update mode of a port_subscribe container
2411 * \param info port_subscribe container
2412 * \return 1 if real-time update mode
2414 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_set_time_real()
2416 int snd_seq_port_subscribe_get_time_real(const snd_seq_port_subscribe_t *info)
2419 return (info->flags & SNDRV_SEQ_PORT_SUBS_TIME_REAL) ? 1 : 0;
2423 * \brief Set sender address of a port_subscribe container
2424 * \param info port_subscribe container
2425 * \param addr sender address
2427 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_get_sender()
2429 void snd_seq_port_subscribe_set_sender(snd_seq_port_subscribe_t *info, const snd_seq_addr_t *addr)
2432 memcpy(&info->sender, addr, sizeof(*addr));
2436 * \brief Set destination address of a port_subscribe container
2437 * \param info port_subscribe container
2438 * \param addr destination address
2440 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_get_dest()
2442 void snd_seq_port_subscribe_set_dest(snd_seq_port_subscribe_t *info, const snd_seq_addr_t *addr)
2445 memcpy(&info->dest, addr, sizeof(*addr));
2449 * \brief Set the queue id of a port_subscribe container
2450 * \param info port_subscribe container
2453 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_get_queue()
2455 void snd_seq_port_subscribe_set_queue(snd_seq_port_subscribe_t *info, int q)
2462 * \brief Set the exclusive mode of a port_subscribe container
2463 * \param info port_subscribe container
2464 * \param val non-zero to enable
2466 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_get_exclusive()
2468 void snd_seq_port_subscribe_set_exclusive(snd_seq_port_subscribe_t *info, int val)
2472 info->flags |= SNDRV_SEQ_PORT_SUBS_EXCLUSIVE;
2474 info->flags &= ~SNDRV_SEQ_PORT_SUBS_EXCLUSIVE;
2478 * \brief Set the time-update mode of a port_subscribe container
2479 * \param info port_subscribe container
2480 * \param val non-zero to enable
2482 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_get_time_update()
2484 void snd_seq_port_subscribe_set_time_update(snd_seq_port_subscribe_t *info, int val)
2488 info->flags |= SNDRV_SEQ_PORT_SUBS_TIMESTAMP;
2490 info->flags &= ~SNDRV_SEQ_PORT_SUBS_TIMESTAMP;
2494 * \brief Set the real-time mode of a port_subscribe container
2495 * \param info port_subscribe container
2496 * \param val non-zero to enable
2498 * \sa snd_seq_subscribe_port(), snd_seq_port_subscribe_get_time_real()
2500 void snd_seq_port_subscribe_set_time_real(snd_seq_port_subscribe_t *info, int val)
2504 info->flags |= SNDRV_SEQ_PORT_SUBS_TIME_REAL;
2506 info->flags &= ~SNDRV_SEQ_PORT_SUBS_TIME_REAL;
2511 * \brief obtain subscription information
2512 * \param seq sequencer handle
2513 * \param sub pointer to return the subscription information
2514 * \return 0 on success otherwise a negative error code
2516 * \sa snd_seq_subscribe_port(), snd_seq_query_port_subscribers()
2518 int snd_seq_get_port_subscription(snd_seq_t *seq, snd_seq_port_subscribe_t * sub)
2521 return seq->ops->get_port_subscription(seq, sub);
2525 * \brief subscribe a port connection
2526 * \param seq sequencer handle
2527 * \param sub subscription information
2528 * \return 0 on success otherwise a negative error code
2530 * Subscribes a connection between two ports.
2531 * The subscription information is stored in sub argument.
2533 * \sa snd_seq_get_port_subscription(), snd_seq_unsubscribe_port(),
2534 * snd_seq_connect_from(), snd_seq_connect_to()
2536 int snd_seq_subscribe_port(snd_seq_t *seq, snd_seq_port_subscribe_t * sub)
2539 return seq->ops->subscribe_port(seq, sub);
2543 * \brief unsubscribe a connection between ports
2544 * \param seq sequencer handle
2545 * \param sub subscription information to disconnect
2546 * \return 0 on success otherwise a negative error code
2548 * Unsubscribes a connection between two ports,
2549 * described in sender and dest fields in sub argument.
2551 * \sa snd_seq_subscribe_port(), snd_seq_disconnect_from(), snd_seq_disconnect_to()
2553 int snd_seq_unsubscribe_port(snd_seq_t *seq, snd_seq_port_subscribe_t * sub)
2556 return seq->ops->unsubscribe_port(seq, sub);
2561 * \brief get size of #snd_seq_query_subscribe_t
2562 * \return size in bytes
2564 size_t snd_seq_query_subscribe_sizeof()
2566 return sizeof(snd_seq_query_subscribe_t);
2570 * \brief allocate an empty #snd_seq_query_subscribe_t using standard malloc
2571 * \param ptr returned pointer
2572 * \return 0 on success otherwise negative error code
2574 int snd_seq_query_subscribe_malloc(snd_seq_query_subscribe_t **ptr)
2577 *ptr = calloc(1, sizeof(snd_seq_query_subscribe_t));
2584 * \brief frees a previously allocated #snd_seq_query_subscribe_t
2585 * \param obj pointer to object to free
2587 void snd_seq_query_subscribe_free(snd_seq_query_subscribe_t *obj)
2593 * \brief copy one #snd_seq_query_subscribe_t to another
2594 * \param dst pointer to destination
2595 * \param src pointer to source
2597 void snd_seq_query_subscribe_copy(snd_seq_query_subscribe_t *dst, const snd_seq_query_subscribe_t *src)
2605 * \brief Get the client id of a query_subscribe container
2606 * \param info query_subscribe container
2609 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_set_client()
2611 int snd_seq_query_subscribe_get_client(const snd_seq_query_subscribe_t *info)
2614 return info->root.client;
2618 * \brief Get the port id of a query_subscribe container
2619 * \param info query_subscribe container
2622 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_set_port()
2624 int snd_seq_query_subscribe_get_port(const snd_seq_query_subscribe_t *info)
2627 return info->root.port;
2631 * \brief Get the client/port address of a query_subscribe container
2632 * \param info query_subscribe container
2633 * \return client/port address pointer
2635 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_set_root()
2637 const snd_seq_addr_t *snd_seq_query_subscribe_get_root(const snd_seq_query_subscribe_t *info)
2644 * \brief Get the query type of a query_subscribe container
2645 * \param info query_subscribe container
2646 * \return query type
2648 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_set_type()
2650 snd_seq_query_subs_type_t snd_seq_query_subscribe_get_type(const snd_seq_query_subscribe_t *info)
2657 * \brief Get the index of subscriber of a query_subscribe container
2658 * \param info query_subscribe container
2659 * \return subscriber's index
2661 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_set_index()
2663 int snd_seq_query_subscribe_get_index(const snd_seq_query_subscribe_t *info)
2670 * \brief Get the number of subscriptions of a query_subscribe container
2671 * \param info query_subscribe container
2672 * \return number of subscriptions
2674 * \sa snd_seq_query_port_subscribers()
2676 int snd_seq_query_subscribe_get_num_subs(const snd_seq_query_subscribe_t *info)
2679 return info->num_subs;
2683 * \brief Get the address of subscriber of a query_subscribe container
2684 * \param info query_subscribe container
2685 * \return subscriber's address pointer
2687 * \sa snd_seq_query_port_subscribers()
2689 const snd_seq_addr_t *snd_seq_query_subscribe_get_addr(const snd_seq_query_subscribe_t *info)
2696 * \brief Get the queue id of subscriber of a query_subscribe container
2697 * \param info query_subscribe container
2698 * \return subscriber's queue id
2700 * \sa snd_seq_query_port_subscribers()
2702 int snd_seq_query_subscribe_get_queue(const snd_seq_query_subscribe_t *info)
2709 * \brief Get the exclusive mode of a query_subscribe container
2710 * \param info query_subscribe container
2711 * \return 1 if exclusive mode
2713 * \sa snd_seq_query_port_subscribers()
2715 int snd_seq_query_subscribe_get_exclusive(const snd_seq_query_subscribe_t *info)
2718 return (info->flags & SNDRV_SEQ_PORT_SUBS_EXCLUSIVE) ? 1 : 0;
2722 * \brief Get the time-update mode of a query_subscribe container
2723 * \param info query_subscribe container
2724 * \return 1 if update timestamp
2726 * \sa snd_seq_query_port_subscribers()
2728 int snd_seq_query_subscribe_get_time_update(const snd_seq_query_subscribe_t *info)
2731 return (info->flags & SNDRV_SEQ_PORT_SUBS_TIMESTAMP) ? 1 : 0;
2735 * \brief Get the real-time update mode of a query_subscribe container
2736 * \param info query_subscribe container
2737 * \return 1 if real-time update mode
2739 * \sa snd_seq_query_port_subscribers()
2741 int snd_seq_query_subscribe_get_time_real(const snd_seq_query_subscribe_t *info)
2744 return (info->flags & SNDRV_SEQ_PORT_SUBS_TIMESTAMP) ? 1 : 0;
2748 * \brief Set the client id of a query_subscribe container
2749 * \param info query_subscribe container
2750 * \param client client id
2752 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_get_client()
2754 void snd_seq_query_subscribe_set_client(snd_seq_query_subscribe_t *info, int client)
2757 info->root.client = client;
2761 * \brief Set the port id of a query_subscribe container
2762 * \param info query_subscribe container
2763 * \param port port id
2765 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_get_port()
2767 void snd_seq_query_subscribe_set_port(snd_seq_query_subscribe_t *info, int port)
2770 info->root.port = port;
2774 * \brief Set the client/port address of a query_subscribe container
2775 * \param info query_subscribe container
2776 * \param addr client/port address pointer
2778 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_get_root()
2780 void snd_seq_query_subscribe_set_root(snd_seq_query_subscribe_t *info, const snd_seq_addr_t *addr)
2787 * \brief Set the query type of a query_subscribe container
2788 * \param info query_subscribe container
2789 * \param type query type
2791 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_get_type()
2793 void snd_seq_query_subscribe_set_type(snd_seq_query_subscribe_t *info, snd_seq_query_subs_type_t type)
2800 * \brief Set the subscriber's index to be queried
2801 * \param info query_subscribe container
2802 * \param index index to be queried
2804 * \sa snd_seq_query_port_subscribers(), snd_seq_query_subscribe_get_index()
2806 void snd_seq_query_subscribe_set_index(snd_seq_query_subscribe_t *info, int index)
2809 info->index = index;
2814 * \brief query port subscriber list
2815 * \param seq sequencer handle
2816 * \param subs subscription to query
2817 * \return 0 on success otherwise a negative error code
2819 * Queries the subscribers accessing to a port.
2820 * The query information is specified in subs argument.
2822 * At least, the client id, the port id, the index number and
2823 * the query type must be set to perform a proper query.
2824 * As the query type, #SND_SEQ_QUERY_SUBS_READ or #SND_SEQ_QUERY_SUBS_WRITE
2825 * can be specified to check whether the readers or the writers to the port.
2826 * To query the first subscription, set 0 to the index number. To list up
2827 * all the subscriptions, call this function with the index numbers from 0
2828 * until this returns a negative value.
2830 * \sa snd_seq_get_port_subscription()
2832 int snd_seq_query_port_subscribers(snd_seq_t *seq, snd_seq_query_subscribe_t * subs)
2834 assert(seq && subs);
2835 return seq->ops->query_port_subscribers(seq, subs);
2838 /*----------------------------------------------------------------*/
2845 * \brief get size of #snd_seq_queue_info_t
2846 * \return size in bytes
2848 size_t snd_seq_queue_info_sizeof()
2850 return sizeof(snd_seq_queue_info_t);
2854 * \brief allocate an empty #snd_seq_queue_info_t using standard malloc
2855 * \param ptr returned pointer
2856 * \return 0 on success otherwise negative error code
2858 int snd_seq_queue_info_malloc(snd_seq_queue_info_t **ptr)
2861 *ptr = calloc(1, sizeof(snd_seq_queue_info_t));
2868 * \brief frees a previously allocated #snd_seq_queue_info_t
2869 * \param obj pointer to object to free
2871 void snd_seq_queue_info_free(snd_seq_queue_info_t *obj)
2877 * \brief copy one #snd_seq_queue_info_t to another
2878 * \param dst pointer to destination
2879 * \param src pointer to source
2881 void snd_seq_queue_info_copy(snd_seq_queue_info_t *dst, const snd_seq_queue_info_t *src)
2889 * \brief Get the queue id of a queue_info container
2890 * \param info queue_info container
2893 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_set_queue()
2895 int snd_seq_queue_info_get_queue(const snd_seq_queue_info_t *info)
2902 * \brief Get the name of a queue_info container
2903 * \param info queue_info container
2904 * \return name string
2906 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_set_name()
2908 const char *snd_seq_queue_info_get_name(const snd_seq_queue_info_t *info)
2915 * \brief Get the owner client id of a queue_info container
2916 * \param info queue_info container
2917 * \return owner client id
2919 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_set_owner()
2921 int snd_seq_queue_info_get_owner(const snd_seq_queue_info_t *info)
2928 * \brief Get the lock status of a queue_info container
2929 * \param info queue_info container
2930 * \return lock status --- non-zero = locked
2932 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_set_locked()
2934 int snd_seq_queue_info_get_locked(const snd_seq_queue_info_t *info)
2937 return info->locked;
2941 * \brief Get the conditional bit flags of a queue_info container
2942 * \param info queue_info container
2943 * \return conditional bit flags
2945 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_set_flags()
2947 unsigned int snd_seq_queue_info_get_flags(const snd_seq_queue_info_t *info)
2954 * \brief Set the name of a queue_info container
2955 * \param info queue_info container
2956 * \param name name string
2958 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_get_name()
2960 void snd_seq_queue_info_set_name(snd_seq_queue_info_t *info, const char *name)
2962 assert(info && name);
2963 strncpy(info->name, name, sizeof(info->name));
2967 * \brief Set the owner client id of a queue_info container
2968 * \param info queue_info container
2969 * \param owner client id
2971 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_get_owner()
2973 void snd_seq_queue_info_set_owner(snd_seq_queue_info_t *info, int owner)
2976 info->owner = owner;
2980 * \brief Set the lock status of a queue_info container
2981 * \param info queue_info container
2982 * \param locked lock status
2984 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_get_locked()
2986 void snd_seq_queue_info_set_locked(snd_seq_queue_info_t *info, int locked)
2989 info->locked = locked;
2993 * \brief Set the conditional bit flags of a queue_info container
2994 * \param info queue_info container
2995 * \param flags conditional bit flags
2997 * \sa snd_seq_get_queue_info(), snd_seq_queue_info_get_flags()
2999 void snd_seq_queue_info_set_flags(snd_seq_queue_info_t *info, unsigned int flags)
3002 info->flags = flags;
3007 * \brief create a queue
3008 * \param seq sequencer handle
3009 * \param info queue information to initialize
3010 * \return the queue id (zero or positive) on success otherwise a negative error code
3012 * \sa snd_seq_alloc_queue()
3014 int snd_seq_create_queue(snd_seq_t *seq, snd_seq_queue_info_t *info)
3017 assert(seq && info);
3018 info->owner = seq->client;
3019 err = seq->ops->create_queue(seq, info);
3026 * \brief allocate a queue with the specified name
3027 * \param seq sequencer handle
3028 * \param name the name of the new queue
3029 * \return the queue id (zero or positive) on success otherwise a negative error code
3031 * \sa snd_seq_alloc_queue()
3033 int snd_seq_alloc_named_queue(snd_seq_t *seq, const char *name)
3035 snd_seq_queue_info_t info;
3036 memset(&info, 0, sizeof(info));
3039 strncpy(info.name, name, sizeof(info.name) - 1);
3040 return snd_seq_create_queue(seq, &info);
3044 * \brief allocate a queue
3045 * \param seq sequencer handle
3046 * \return the queue id (zero or positive) on success otherwise a negative error code
3048 * \sa snd_seq_alloc_named_queue(), snd_seq_create_queue(), snd_seq_free_queue(),
3049 * snd_seq_get_queue_info()
3051 int snd_seq_alloc_queue(snd_seq_t *seq)
3053 return snd_seq_alloc_named_queue(seq, NULL);
3057 * \brief delete the specified queue
3058 * \param seq sequencer handle
3059 * \param q queue id to delete
3060 * \return 0 on success otherwise a negative error code
3062 * \sa snd_seq_alloc_queue()
3064 int snd_seq_free_queue(snd_seq_t *seq, int q)
3066 snd_seq_queue_info_t info;
3068 memset(&info, 0, sizeof(info));
3070 return seq->ops->delete_queue(seq, &info);
3074 * \brief obtain queue attributes
3075 * \param seq sequencer handle
3076 * \param q queue id to query
3077 * \param info information returned
3078 * \return 0 on success otherwise a negative error code
3080 * \sa snd_seq_alloc_queue(), snd_seq_set_queue_info(), snd_seq_query_named_queue()
3082 int snd_seq_get_queue_info(snd_seq_t *seq, int q, snd_seq_queue_info_t *info)
3084 assert(seq && info);
3086 return seq->ops->get_queue_info(seq, info);
3090 * \brief change the queue attributes
3091 * \param seq sequencer handle
3092 * \param q queue id to change
3093 * \param info information changed
3094 * \return 0 on success otherwise a negative error code
3096 * \sa snd_seq_get_queue_info()
3098 int snd_seq_set_queue_info(snd_seq_t *seq, int q, snd_seq_queue_info_t *info)
3100 assert(seq && info);
3102 return seq->ops->set_queue_info(seq, info);
3106 * \brief query the matching queue with the specified name
3107 * \param seq sequencer handle
3108 * \param name the name string to query
3109 * \return the queue id if found or negative error code
3111 * Searches the matching queue with the specified name string.
3113 * \sa snd_seq_get_queue_info()
3115 int snd_seq_query_named_queue(snd_seq_t *seq, const char *name)
3118 snd_seq_queue_info_t info;
3119 assert(seq && name);
3120 strncpy(info.name, name, sizeof(info.name));
3121 err = seq->ops->get_named_queue(seq, &info);
3128 * \brief Get the queue usage flag to the client
3129 * \param seq sequencer handle
3131 * \return 1 = client is allowed to access the queue, 0 = not allowed,
3132 * otherwise a negative error code
3134 * \sa snd_seq_get_queue_info(), snd_seq_set_queue_usage()
3136 int snd_seq_get_queue_usage(snd_seq_t *seq, int q)
3138 struct sndrv_seq_queue_client info;
3141 memset(&info, 0, sizeof(info));
3143 info.client = seq->client;
3144 if ((err = seq->ops->get_queue_client(seq, &info)) < 0)
3150 * \brief Set the queue usage flag to the client
3151 * \param seq sequencer handle
3153 * \param used non-zero if the client is allowed
3154 * \return 0 on success otherwise a negative error code
3156 * \sa snd_seq_get_queue_info(), snd_seq_set_queue_usage()
3158 int snd_seq_set_queue_usage(snd_seq_t *seq, int q, int used)
3160 struct sndrv_seq_queue_client info;
3162 memset(&info, 0, sizeof(info));
3164 info.client = seq->client;
3165 info.used = used ? 1 : 0;
3166 return seq->ops->set_queue_client(seq, &info);
3171 * \brief get size of #snd_seq_queue_status_t
3172 * \return size in bytes
3174 size_t snd_seq_queue_status_sizeof()
3176 return sizeof(snd_seq_queue_status_t);
3180 * \brief allocate an empty #snd_seq_queue_status_t using standard malloc
3181 * \param ptr returned pointer
3182 * \return 0 on success otherwise negative error code
3184 int snd_seq_queue_status_malloc(snd_seq_queue_status_t **ptr)
3187 *ptr = calloc(1, sizeof(snd_seq_queue_status_t));
3194 * \brief frees a previously allocated #snd_seq_queue_status_t
3195 * \param obj pointer to object to free
3197 void snd_seq_queue_status_free(snd_seq_queue_status_t *obj)
3203 * \brief copy one #snd_seq_queue_status_t to another
3204 * \param dst pointer to destination
3205 * \param src pointer to source
3207 void snd_seq_queue_status_copy(snd_seq_queue_status_t *dst, const snd_seq_queue_status_t *src)
3215 * \brief Get the queue id of a queue_status container
3216 * \param info queue_status container
3219 * \sa snd_seq_get_queue_status()
3221 int snd_seq_queue_status_get_queue(const snd_seq_queue_status_t *info)
3228 * \brief Get the number of events of a queue_status container
3229 * \param info queue_status container
3230 * \return number of events
3232 * \sa snd_seq_get_queue_status()
3234 int snd_seq_queue_status_get_events(const snd_seq_queue_status_t *info)
3237 return info->events;
3241 * \brief Get the tick time of a queue_status container
3242 * \param info queue_status container
3245 * \sa snd_seq_get_queue_status()
3247 snd_seq_tick_time_t snd_seq_queue_status_get_tick_time(const snd_seq_queue_status_t *info)
3254 * \brief Get the real time of a queue_status container
3255 * \param info queue_status container
3257 * \sa snd_seq_get_queue_status()
3259 const snd_seq_real_time_t *snd_seq_queue_status_get_real_time(const snd_seq_queue_status_t *info)
3266 * \brief Get the running status bits of a queue_status container
3267 * \param info queue_status container
3268 * \return running status bits
3270 * \sa snd_seq_get_queue_status()
3272 unsigned int snd_seq_queue_status_get_status(const snd_seq_queue_status_t *info)
3275 return info->running;
3280 * \brief obtain the running state of the queue
3281 * \param seq sequencer handle
3282 * \param q queue id to query
3283 * \param status pointer to store the current status
3284 * \return 0 on success otherwise a negative error code
3286 * Obtains the running state of the specified queue q.
3288 int snd_seq_get_queue_status(snd_seq_t *seq, int q, snd_seq_queue_status_t * status)
3290 assert(seq && status);
3291 memset(status, 0, sizeof(snd_seq_queue_status_t));
3293 return seq->ops->get_queue_status(seq, status);
3298 * \brief get size of #snd_seq_queue_tempo_t
3299 * \return size in bytes
3301 size_t snd_seq_queue_tempo_sizeof()
3303 return sizeof(snd_seq_queue_tempo_t);
3307 * \brief allocate an empty #snd_seq_queue_tempo_t using standard malloc
3308 * \param ptr returned pointer
3309 * \return 0 on success otherwise negative error code
3311 int snd_seq_queue_tempo_malloc(snd_seq_queue_tempo_t **ptr)
3314 *ptr = calloc(1, sizeof(snd_seq_queue_tempo_t));
3321 * \brief frees a previously allocated #snd_seq_queue_tempo_t
3322 * \param obj pointer to object to free
3324 void snd_seq_queue_tempo_free(snd_seq_queue_tempo_t *obj)
3330 * \brief copy one #snd_seq_queue_tempo_t to another
3331 * \param dst pointer to destination
3332 * \param src pointer to source
3334 void snd_seq_queue_tempo_copy(snd_seq_queue_tempo_t *dst, const snd_seq_queue_tempo_t *src)
3342 * \brief Get the queue id of a queue_status container
3343 * \param info queue_status container
3346 * \sa snd_seq_get_queue_tempo()
3348 int snd_seq_queue_tempo_get_queue(const snd_seq_queue_tempo_t *info)
3355 * \brief Get the tempo of a queue_status container
3356 * \param info queue_status container
3357 * \return tempo value
3359 * \sa snd_seq_get_queue_tempo()
3361 unsigned int snd_seq_queue_tempo_get_tempo(const snd_seq_queue_tempo_t *info)
3368 * \brief Get the ppq of a queue_status container
3369 * \param info queue_status container
3372 * \sa snd_seq_get_queue_tempo()
3374 int snd_seq_queue_tempo_get_ppq(const snd_seq_queue_tempo_t *info)
3381 * \brief Get the timer skew value of a queue_status container
3382 * \param info queue_status container
3383 * \return timer skew value
3385 * \sa snd_seq_get_queue_tempo()
3387 unsigned int snd_seq_queue_tempo_get_skew(const snd_seq_queue_tempo_t *info)
3390 return info->skew_value;
3394 * \brief Get the timer skew base value of a queue_status container
3395 * \param info queue_status container
3396 * \return timer skew base value
3398 * \sa snd_seq_get_queue_tempo()
3400 unsigned int snd_seq_queue_tempo_get_skew_base(const snd_seq_queue_tempo_t *info)
3403 return info->skew_base;
3407 * \brief Set the tempo of a queue_status container
3408 * \param info queue_status container
3409 * \param tempo tempo value
3411 * \sa snd_seq_get_queue_tempo()
3413 void snd_seq_queue_tempo_set_tempo(snd_seq_queue_tempo_t *info, unsigned int tempo)
3416 info->tempo = tempo;
3420 * \brief Set the ppq of a queue_status container
3421 * \param info queue_status container
3422 * \param ppq ppq value
3424 * \sa snd_seq_get_queue_tempo()
3426 void snd_seq_queue_tempo_set_ppq(snd_seq_queue_tempo_t *info, int ppq)
3433 * \brief Set the timer skew value of a queue_status container
3434 * \param info queue_status container
3435 * \param skew timer skew value
3437 * The skew of timer is calculated as skew / base.
3438 * For example, to play with double speed, pass base * 2 as the skew value.
3440 * \sa snd_seq_get_queue_tempo()
3442 void snd_seq_queue_tempo_set_skew(snd_seq_queue_tempo_t *info, unsigned int skew)
3445 info->skew_value = skew;
3449 * \brief Set the timer skew base value of a queue_status container
3450 * \param info queue_status container
3451 * \param base timer skew base value
3453 * \sa snd_seq_get_queue_tempo()
3455 void snd_seq_queue_tempo_set_skew_base(snd_seq_queue_tempo_t *info, unsigned int base)
3458 info->skew_base = base;
3462 * \brief obtain the current tempo of the queue
3463 * \param seq sequencer handle
3464 * \param q queue id to be queried
3465 * \param tempo pointer to store the current tempo
3466 * \return 0 on success otherwise a negative error code
3468 * \sa snd_seq_set_queue_tempo()
3470 int snd_seq_get_queue_tempo(snd_seq_t *seq, int q, snd_seq_queue_tempo_t * tempo)
3472 assert(seq && tempo);
3473 memset(tempo, 0, sizeof(snd_seq_queue_tempo_t));
3475 return seq->ops->get_queue_tempo(seq, tempo);
3479 * \brief set the tempo of the queue
3480 * \param seq sequencer handle
3481 * \param q queue id to change the tempo
3482 * \param tempo tempo information
3483 * \return 0 on success otherwise a negative error code
3485 * \sa snd_seq_get_queue_tempo()
3487 int snd_seq_set_queue_tempo(snd_seq_t *seq, int q, snd_seq_queue_tempo_t * tempo)
3489 assert(seq && tempo);
3491 return seq->ops->set_queue_tempo(seq, tempo);
3495 /*----------------------------------------------------------------*/
3498 * \brief get size of #snd_seq_queue_timer_t
3499 * \return size in bytes
3501 size_t snd_seq_queue_timer_sizeof()
3503 return sizeof(snd_seq_queue_timer_t);
3507 * \brief allocate an empty #snd_seq_queue_timer_t using standard malloc
3508 * \param ptr returned pointer
3509 * \return 0 on success otherwise negative error code
3511 int snd_seq_queue_timer_malloc(snd_seq_queue_timer_t **ptr)
3514 *ptr = calloc(1, sizeof(snd_seq_queue_timer_t));
3521 * \brief frees a previously allocated #snd_seq_queue_timer_t
3522 * \param obj pointer to object to free
3524 void snd_seq_queue_timer_free(snd_seq_queue_timer_t *obj)
3530 * \brief copy one #snd_seq_queue_timer_t to another
3531 * \param dst pointer to destination
3532 * \param src pointer to source
3534 void snd_seq_queue_timer_copy(snd_seq_queue_timer_t *dst, const snd_seq_queue_timer_t *src)
3542 * \brief Get the queue id of a queue_timer container
3543 * \param info queue_timer container
3546 * \sa snd_seq_get_queue_timer()
3548 int snd_seq_queue_timer_get_queue(const snd_seq_queue_timer_t *info)
3555 * \brief Get the timer type of a queue_timer container
3556 * \param info queue_timer container
3557 * \return timer type
3559 * \sa snd_seq_get_queue_timer()
3561 snd_seq_queue_timer_type_t snd_seq_queue_timer_get_type(const snd_seq_queue_timer_t *info)
3564 return (snd_seq_queue_timer_type_t)info->type;
3568 * \brief Get the timer id of a queue_timer container
3569 * \param info queue_timer container
3570 * \return timer id pointer
3572 * \sa snd_seq_get_queue_timer()
3574 const snd_timer_id_t *snd_seq_queue_timer_get_id(const snd_seq_queue_timer_t *info)
3577 return &info->u.alsa.id;
3581 * \brief Get the timer resolution of a queue_timer container
3582 * \param info queue_timer container
3583 * \return timer resolution
3585 * \sa snd_seq_get_queue_timer()
3587 unsigned int snd_seq_queue_timer_get_resolution(const snd_seq_queue_timer_t *info)
3590 return info->u.alsa.resolution;
3594 * \brief Set the timer type of a queue_timer container
3595 * \param info queue_timer container
3596 * \param type timer type
3598 * \sa snd_seq_get_queue_timer()
3600 void snd_seq_queue_timer_set_type(snd_seq_queue_timer_t *info, snd_seq_queue_timer_type_t type)
3603 info->type = (int)type;
3607 * \brief Set the timer id of a queue_timer container
3608 * \param info queue_timer container
3609 * \param id timer id pointer
3611 * \sa snd_seq_get_queue_timer()
3613 void snd_seq_queue_timer_set_id(snd_seq_queue_timer_t *info, const snd_timer_id_t *id)
3616 info->u.alsa.id = *id;
3620 * \brief Set the timer resolution of a queue_timer container
3621 * \param info queue_timer container
3622 * \param resolution timer resolution
3624 * \sa snd_seq_get_queue_timer()
3626 void snd_seq_queue_timer_set_resolution(snd_seq_queue_timer_t *info, unsigned int resolution)
3629 info->u.alsa.resolution = resolution;
3634 * \brief obtain the queue timer information
3635 * \param seq sequencer handle
3636 * \param q queue id to query
3637 * \param timer pointer to store the timer information
3638 * \return 0 on success otherwise a negative error code
3640 * \sa snd_seq_set_queue_timer()
3642 int snd_seq_get_queue_timer(snd_seq_t *seq, int q, snd_seq_queue_timer_t * timer)
3644 assert(seq && timer);
3645 memset(timer, 0, sizeof(snd_seq_queue_timer_t));
3647 return seq->ops->get_queue_timer(seq, timer);
3651 * \brief set the queue timer information
3652 * \param seq sequencer handle
3653 * \param q queue id to change the timer
3654 * \param timer timer information
3655 * \return 0 on success otherwise a negative error code
3657 * \sa snd_seq_get_queue_timer()
3659 int snd_seq_set_queue_timer(snd_seq_t *seq, int q, snd_seq_queue_timer_t * timer)
3661 assert(seq && timer);
3663 return seq->ops->set_queue_timer(seq, timer);
3666 /*----------------------------------------------------------------*/
3670 * \brief (DEPRECATED) create an event cell
3671 * \return the cell pointer allocated
3673 * create an event cell via malloc. the returned pointer must be released
3674 * by the application itself via normal free() call,
3675 * not via snd_seq_free_event().
3677 snd_seq_event_t *snd_seq_create_event(void)
3679 return (snd_seq_event_t *) calloc(1, sizeof(snd_seq_event_t));
3684 * \brief (DEPRECATED) free an event
3686 * In the former version, this function was used to
3687 * release the event pointer which was allocated by snd_seq_event_input().
3688 * In the current version, the event record is not allocated, so
3689 * you don't have to call this function any more.
3692 int snd_seq_free_event(snd_seq_event_t *ev ATTRIBUTE_UNUSED)
3694 int snd_seq_free_event(snd_seq_event_t *ev)
3701 * \brief calculates the (encoded) byte-stream size of the event
3702 * \param ev the event
3703 * \return the size of decoded bytes
3705 ssize_t snd_seq_event_length(snd_seq_event_t *ev)
3707 ssize_t len = sizeof(snd_seq_event_t);
3709 if (snd_seq_ev_is_variable(ev))
3710 len += ev->data.ext.len;
3714 /*----------------------------------------------------------------*/
3717 * output to sequencer
3721 * \brief output an event
3722 * \param seq sequencer handle
3723 * \param ev event to be output
3724 * \return the number of remaining events or a negative error code
3726 * An event is once expanded on the output buffer.
3727 * The output buffer will be drained automatically if it becomes full.
3729 * If events remain unprocessed on output buffer before drained,
3730 * the size of total byte data on output buffer is returned.
3731 * If the output buffer is empty, this returns zero.
3733 * \sa snd_seq_event_output_direct(), snd_seq_event_output_buffer(),
3734 * snd_seq_event_output_pending(), snd_seq_drain_output(),
3735 * snd_seq_drop_output(), snd_seq_extract_output(),
3736 * snd_seq_remove_events()
3738 int snd_seq_event_output(snd_seq_t *seq, snd_seq_event_t *ev)
3742 result = snd_seq_event_output_buffer(seq, ev);
3743 if (result == -EAGAIN) {
3744 result = snd_seq_drain_output(seq);
3747 return snd_seq_event_output_buffer(seq, ev);
3753 * \brief output an event onto the lib buffer without draining buffer
3754 * \param seq sequencer handle
3755 * \param ev event to be output
3756 * \return the byte size of remaining events. \c -EAGAIN if the buffer becomes full.
3758 * This function doesn't drain buffer unlike snd_seq_event_output().
3760 * \sa snd_seq_event_output()
3762 int snd_seq_event_output_buffer(snd_seq_t *seq, snd_seq_event_t *ev)
3766 len = snd_seq_event_length(ev);
3769 if ((size_t) len >= seq->obufsize)
3771 if ((seq->obufsize - seq->obufused) < (size_t) len)
3773 memcpy(seq->obuf + seq->obufused, ev, sizeof(snd_seq_event_t));
3774 seq->obufused += sizeof(snd_seq_event_t);
3775 if (snd_seq_ev_is_variable(ev)) {
3776 memcpy(seq->obuf + seq->obufused, ev->data.ext.ptr, ev->data.ext.len);
3777 seq->obufused += ev->data.ext.len;
3779 return seq->obufused;
3783 * allocate the temporary buffer
3785 static int alloc_tmpbuf(snd_seq_t *seq, size_t len)
3787 size_t size = ((len + sizeof(snd_seq_event_t) - 1) / sizeof(snd_seq_event_t));
3788 if (seq->tmpbuf == NULL) {
3789 if (size > DEFAULT_TMPBUF_SIZE)
3790 seq->tmpbufsize = size;
3792 seq->tmpbufsize = DEFAULT_TMPBUF_SIZE;
3793 seq->tmpbuf = malloc(seq->tmpbufsize * sizeof(snd_seq_event_t));
3794 if (seq->tmpbuf == NULL)
3796 } else if (len > seq->tmpbufsize) {
3797 seq->tmpbuf = realloc(seq->tmpbuf, size * sizeof(snd_seq_event_t));
3798 if (seq->tmpbuf == NULL)
3800 seq->tmpbufsize = size;
3806 * \brief output an event directly to the sequencer NOT through output buffer
3807 * \param seq sequencer handle
3808 * \param ev event to be output
3809 * \return the byte size sent to sequencer or a negative error code
3811 * This function sends an event to the sequencer directly not through the
3812 * output buffer. When the event is a variable length event, a temporary
3813 * buffer is allocated inside alsa-lib and the data is copied there before
3816 * \sa snd_seq_event_output()
3818 int snd_seq_event_output_direct(snd_seq_t *seq, snd_seq_event_t *ev)
3823 len = snd_seq_event_length(ev);
3826 else if (len == sizeof(*ev)) {
3829 if (alloc_tmpbuf(seq, (size_t)len) < 0)
3832 memcpy(seq->tmpbuf + 1, ev->data.ext.ptr, ev->data.ext.len);
3835 return seq->ops->write(seq, buf, (size_t) len);
3839 * \brief return the size of pending events on output buffer
3840 * \param seq sequencer handle
3841 * \return the byte size of total of pending events
3843 * \sa snd_seq_event_output()
3845 int snd_seq_event_output_pending(snd_seq_t *seq)
3848 return seq->obufused;
3852 * \brief drain output buffer to sequencer
3853 * \param seq sequencer handle
3854 * \return 0 when all events are drained and sent to sequencer.
3855 * When events still remain on the buffer, the byte size of remaining
3856 * events are returned. On error a negative error code is returned.
3858 * This function drains all pending events on the output buffer.
3859 * The function returns immediately after the events are sent to the queues
3860 * regardless whether the events are processed or not.
3861 * To get synchronization with the all event processes, use
3862 * #snd_seq_sync_output_queue() after calling this function.
3864 * \sa snd_seq_event_output(), snd_seq_sync_output_queue()
3866 int snd_seq_drain_output(snd_seq_t *seq)
3868 ssize_t result, processed = 0;
3870 while (seq->obufused > 0) {
3871 result = seq->ops->write(seq, seq->obuf, seq->obufused);
3873 if (result == -EAGAIN && processed)
3874 return seq->obufused;
3877 if ((size_t)result < seq->obufused)
3878 memmove(seq->obuf, seq->obuf + result, seq->obufused - result);
3879 seq->obufused -= result;
3885 * \brief extract the first event in output buffer
3886 * \param seq sequencer handle
3887 * \param ev_res event pointer to be extracted
3888 * \return 0 on success otherwise a negative error code
3890 * Extracts the first event in output buffer.
3891 * If ev_res is NULL, just remove the event.
3893 * \sa snd_seq_event_output()
3895 int snd_seq_extract_output(snd_seq_t *seq, snd_seq_event_t **ev_res)
3902 if ((olen = seq->obufused) < sizeof(snd_seq_event_t))
3904 memcpy(&ev, seq->obuf, sizeof(snd_seq_event_t));
3905 len = snd_seq_event_length(&ev);
3907 /* extract the event */
3908 if (alloc_tmpbuf(seq, len) < 0)
3910 memcpy(seq->tmpbuf, seq->obuf, len);
3911 *ev_res = seq->tmpbuf;
3913 seq->obufused = olen - len;
3914 memmove(seq->obuf, seq->obuf + len, seq->obufused);
3918 /*----------------------------------------------------------------*/
3921 * input from sequencer
3925 * read from sequencer to input buffer
3927 static ssize_t snd_seq_event_read_buffer(snd_seq_t *seq)
3930 len = (seq->ops->read)(seq, seq->ibuf, seq->ibufsize * sizeof(snd_seq_event_t));
3933 seq->ibuflen = len / sizeof(snd_seq_event_t);
3935 return seq->ibuflen;
3938 static int snd_seq_event_retrieve_buffer(snd_seq_t *seq, snd_seq_event_t **retp)
3941 snd_seq_event_t *ev;
3943 *retp = ev = &seq->ibuf[seq->ibufptr];
3946 if (! snd_seq_ev_is_variable(ev))
3948 ncells = (ev->data.ext.len + sizeof(snd_seq_event_t) - 1) / sizeof(snd_seq_event_t);
3949 if (seq->ibuflen < ncells) {
3950 seq->ibuflen = 0; /* clear buffer */
3954 ev->data.ext.ptr = ev + 1;
3955 seq->ibuflen -= ncells;
3956 seq->ibufptr += ncells;
3961 * \brief retrieve an event from sequencer
3962 * \param seq sequencer handle
3963 * \param ev event pointer to be stored
3966 * Obtains an input event from sequencer.
3967 * The event is created via snd_seq_create_event(), and its pointer is stored on
3970 * This function firstly receives the event byte-stream data from sequencer
3971 * as much as possible at once. Then it retrieves the first event record
3972 * and store the pointer on ev.
3973 * By calling this function sequentially, events are extracted from the input buffer.
3975 * If there is no input from sequencer, function falls into sleep
3976 * in blocking mode until an event is received,
3977 * or returns \c -EAGAIN error in non-blocking mode.
3978 * Occasionally, this function may return \c -ENOSPC error.
3979 * This means that the input FIFO of sequencer overran, and some events are
3981 * Once this error is returned, the input FIFO is cleared automatically.
3983 * Function returns the byte size of remaining events on the input buffer
3984 * if an event is successfully received.
3985 * Application can determine from the returned value whether to call
3986 * input once more or not.
3988 * \sa snd_seq_event_input_pending(), snd_seq_drop_input()
3990 int snd_seq_event_input(snd_seq_t *seq, snd_seq_event_t **ev)
3995 if (seq->ibuflen <= 0) {
3996 if ((err = snd_seq_event_read_buffer(seq)) < 0)
4000 return snd_seq_event_retrieve_buffer(seq, ev);
4004 * read input data from sequencer if available
4006 static int snd_seq_event_input_feed(snd_seq_t *seq, int timeout)
4010 pfd.fd = seq->poll_fd;
4011 pfd.events = POLLIN;
4012 err = poll(&pfd, 1, timeout);
4017 if (pfd.revents & POLLIN)
4018 return snd_seq_event_read_buffer(seq);
4019 return seq->ibuflen;
4023 * \brief check events in input buffer
4024 * \return the byte size of remaining input events on input buffer.
4026 * If events remain on the input buffer of user-space, function returns
4027 * the total byte size of events on it.
4028 * If fetch_sequencer argument is non-zero,
4029 * this function checks the presence of events on sequencer FIFO
4030 * When events exist, they are transferred to the input buffer,
4031 * and the number of received events are returned.
4032 * If fetch_sequencer argument is zero and
4033 * no events remain on the input buffer, function simply returns zero.
4035 * \sa snd_seq_event_input()
4037 int snd_seq_event_input_pending(snd_seq_t *seq, int fetch_sequencer)
4039 if (seq->ibuflen == 0 && fetch_sequencer) {
4040 return snd_seq_event_input_feed(seq, 0);
4042 return seq->ibuflen;
4045 /*----------------------------------------------------------------*/
4048 * clear event buffers
4052 * \brief remove all events on user-space output buffer
4053 * \param seq sequencer handle
4055 * Removes all events on user-space output buffer.
4056 * Unlike snd_seq_drain_output(), this function doesn't remove
4057 * events on output memory pool of sequencer.
4059 * \sa snd_seq_drop_output()
4061 int snd_seq_drop_output_buffer(snd_seq_t *seq)
4069 * \brief remove all events on user-space input FIFO
4070 * \param seq sequencer handle
4072 * \sa snd_seq_drop_input()
4074 int snd_seq_drop_input_buffer(snd_seq_t *seq)
4083 * \brief remove all events on output buffer
4084 * \param seq sequencer handle
4086 * Removes all events on both user-space output buffer and
4087 * output memory pool on kernel.
4089 * \sa snd_seq_drain_output(), snd_seq_drop_output_buffer(), snd_seq_remove_events()
4091 int snd_seq_drop_output(snd_seq_t *seq)
4093 snd_seq_remove_events_t rminfo;
4096 memset(&rminfo, 0, sizeof(rminfo));
4097 rminfo.remove_mode = SNDRV_SEQ_REMOVE_OUTPUT;
4099 return snd_seq_remove_events(seq, &rminfo);
4103 * \brief clear input buffer and and remove events in sequencer queue
4104 * \param seq sequencer handle
4106 * \sa snd_seq_drop_input_buffer(), snd_seq_remove_events()
4108 int snd_seq_drop_input(snd_seq_t *seq)
4110 snd_seq_remove_events_t rminfo;
4113 memset(&rminfo, 0, sizeof(rminfo));
4114 rminfo.remove_mode = SNDRV_SEQ_REMOVE_INPUT;
4116 return snd_seq_remove_events(seq, &rminfo);
4121 * \brief get size of #snd_seq_remove_events_t
4122 * \return size in bytes
4124 size_t snd_seq_remove_events_sizeof()
4126 return sizeof(snd_seq_remove_events_t);
4130 * \brief allocate an empty #snd_seq_remove_events_t using standard malloc
4131 * \param ptr returned pointer
4132 * \return 0 on success otherwise negative error code
4134 int snd_seq_remove_events_malloc(snd_seq_remove_events_t **ptr)
4137 *ptr = calloc(1, sizeof(snd_seq_remove_events_t));
4144 * \brief frees a previously allocated #snd_seq_remove_events_t
4145 * \param obj pointer to object to free
4147 void snd_seq_remove_events_free(snd_seq_remove_events_t *obj)
4153 * \brief copy one #snd_seq_remove_events_t to another
4154 * \param dst pointer to destination
4155 * \param src pointer to source
4157 void snd_seq_remove_events_copy(snd_seq_remove_events_t *dst, const snd_seq_remove_events_t *src)
4165 * \brief Get the removal condition bits
4166 * \param info remove_events container
4167 * \return removal condition bits
4169 * \sa snd_seq_remove_events()
4171 unsigned int snd_seq_remove_events_get_condition(const snd_seq_remove_events_t *info)
4174 return info->remove_mode;
4178 * \brief Get the queue as removal condition
4179 * \param info remove_events container
4182 * \sa snd_seq_remove_events()
4184 int snd_seq_remove_events_get_queue(const snd_seq_remove_events_t *info)
4191 * \brief Get the event timestamp as removal condition
4192 * \param info remove_events container
4193 * \return time stamp
4195 * \sa snd_seq_remove_events()
4197 const snd_seq_timestamp_t *snd_seq_remove_events_get_time(const snd_seq_remove_events_t *info)
4204 * \brief Get the event destination address as removal condition
4205 * \param info remove_events container
4206 * \return destination address
4208 * \sa snd_seq_remove_events()
4210 const snd_seq_addr_t *snd_seq_remove_events_get_dest(const snd_seq_remove_events_t *info)
4217 * \brief Get the event channel as removal condition
4218 * \param info remove_events container
4219 * \return channel number
4221 * \sa snd_seq_remove_events()
4223 int snd_seq_remove_events_get_channel(const snd_seq_remove_events_t *info)
4226 return info->channel;
4230 * \brief Get the event type as removal condition
4231 * \param info remove_events container
4232 * \return event type
4234 * \sa snd_seq_remove_events()
4236 int snd_seq_remove_events_get_event_type(const snd_seq_remove_events_t *info)
4243 * \brief Get the event tag id as removal condition
4244 * \param info remove_events container
4247 * \sa snd_seq_remove_events()
4249 int snd_seq_remove_events_get_tag(const snd_seq_remove_events_t *info)
4256 * \brief Set the removal condition bits
4257 * \param info remove_events container
4258 * \param flags removal condition bits
4260 * \sa snd_seq_remove_events()
4262 void snd_seq_remove_events_set_condition(snd_seq_remove_events_t *info, unsigned int flags)
4265 info->remove_mode = flags;
4269 * \brief Set the queue as removal condition
4270 * \param info remove_events container
4271 * \param queue queue id
4273 * \sa snd_seq_remove_events()
4275 void snd_seq_remove_events_set_queue(snd_seq_remove_events_t *info, int queue)
4278 info->queue = queue;
4282 * \brief Set the timestamp as removal condition
4283 * \param info remove_events container
4284 * \param time timestamp pointer
4286 * \sa snd_seq_remove_events()
4288 void snd_seq_remove_events_set_time(snd_seq_remove_events_t *info, const snd_seq_timestamp_t *time)
4295 * \brief Set the destination address as removal condition
4296 * \param info remove_events container
4297 * \param addr destination address
4299 * \sa snd_seq_remove_events()
4301 void snd_seq_remove_events_set_dest(snd_seq_remove_events_t *info, const snd_seq_addr_t *addr)
4308 * \brief Set the channel as removal condition
4309 * \param info remove_events container
4310 * \param channel channel number
4312 * \sa snd_seq_remove_events()
4314 void snd_seq_remove_events_set_channel(snd_seq_remove_events_t *info, int channel)
4317 info->channel = channel;
4321 * \brief Set the event type as removal condition
4322 * \param info remove_events container
4323 * \param type event type
4325 * \sa snd_seq_remove_events()
4327 void snd_seq_remove_events_set_event_type(snd_seq_remove_events_t *info, int type)
4334 * \brief Set the event tag as removal condition
4335 * \param info remove_events container
4338 * \sa snd_seq_remove_events()
4340 void snd_seq_remove_events_set_tag(snd_seq_remove_events_t *info, int tag)
4347 /* compare timestamp between events */
4348 /* return 1 if a >= b; otherwise return 0 */
4349 static inline int snd_seq_compare_tick_time(snd_seq_tick_time_t *a, snd_seq_tick_time_t *b)
4355 static inline int snd_seq_compare_real_time(snd_seq_real_time_t *a, snd_seq_real_time_t *b)
4357 /* compare real time */
4358 if (a->tv_sec > b->tv_sec)
4360 if ((a->tv_sec == b->tv_sec) && (a->tv_nsec >= b->tv_nsec))
4365 /* Routine to match events to be removed */
4366 static int remove_match(snd_seq_remove_events_t *info, snd_seq_event_t *ev)
4370 if (info->remove_mode & SNDRV_SEQ_REMOVE_DEST) {
4371 if (ev->dest.client != info->dest.client ||
4372 ev->dest.port != info->dest.port)
4375 if (info->remove_mode & SNDRV_SEQ_REMOVE_DEST_CHANNEL) {
4376 if (! snd_seq_ev_is_channel_type(ev))
4378 /* data.note.channel and data.control.channel are identical */
4379 if (ev->data.note.channel != info->channel)
4382 if (info->remove_mode & SNDRV_SEQ_REMOVE_TIME_AFTER) {
4383 if (info->remove_mode & SNDRV_SEQ_REMOVE_TIME_TICK)
4384 res = snd_seq_compare_tick_time(&ev->time.tick, &info->time.tick);
4386 res = snd_seq_compare_real_time(&ev->time.time, &info->time.time);
4390 if (info->remove_mode & SNDRV_SEQ_REMOVE_TIME_BEFORE) {
4391 if (info->remove_mode & SNDRV_SEQ_REMOVE_TIME_TICK)
4392 res = snd_seq_compare_tick_time(&ev->time.tick, &info->time.tick);
4394 res = snd_seq_compare_real_time(&ev->time.time, &info->time.time);
4398 if (info->remove_mode & SNDRV_SEQ_REMOVE_EVENT_TYPE) {
4399 if (ev->type != info->type)
4402 if (info->remove_mode & SNDRV_SEQ_REMOVE_IGNORE_OFF) {
4403 /* Do not remove off events */
4405 case SND_SEQ_EVENT_NOTEOFF:
4406 /* case SND_SEQ_EVENT_SAMPLE_STOP: */
4412 if (info->remove_mode & SNDRV_SEQ_REMOVE_TAG_MATCH) {
4413 if (info->tag != ev->tag)
4421 * \brief remove events on input/output buffers and pools
4422 * \param seq sequencer handle
4423 * \param rmp remove event container
4425 * Removes matching events with the given condition from input/output buffers
4427 * The removal condition is specified in \a rmp argument.
4429 * \sa snd_seq_event_output(), snd_seq_drop_output(), snd_seq_reset_pool_output()
4431 int snd_seq_remove_events(snd_seq_t *seq, snd_seq_remove_events_t *rmp)
4433 if (rmp->remove_mode & SNDRV_SEQ_REMOVE_INPUT) {
4435 * First deal with any events that are still buffered
4438 snd_seq_drop_input_buffer(seq);
4441 if (rmp->remove_mode & SNDRV_SEQ_REMOVE_OUTPUT) {
4443 * First deal with any events that are still buffered
4446 if (! (rmp->remove_mode & ~(SNDRV_SEQ_REMOVE_INPUT|SNDRV_SEQ_REMOVE_OUTPUT))) {
4447 /* The simple case - remove all */
4448 snd_seq_drop_output_buffer(seq);
4452 snd_seq_event_t *ev;
4455 while (ep - seq->obuf < (ssize_t)seq->obufused) {
4457 ev = (snd_seq_event_t *)ep;
4458 len = snd_seq_event_length(ev);
4460 if (remove_match(rmp, ev)) {
4462 seq->obufused -= len;
4463 memmove(ep, ep + len, seq->obufused - (ep - seq->obuf));
4471 return seq->ops->remove_events(seq, rmp);
4474 /*----------------------------------------------------------------*/
4477 * client memory pool
4481 * \brief get size of #snd_seq_client_pool_t
4482 * \return size in bytes
4484 size_t snd_seq_client_pool_sizeof()
4486 return sizeof(snd_seq_client_pool_t);
4490 * \brief allocate an empty #snd_seq_client_pool_t using standard malloc
4491 * \param ptr returned pointer
4492 * \return 0 on success otherwise negative error code
4494 int snd_seq_client_pool_malloc(snd_seq_client_pool_t **ptr)
4497 *ptr = calloc(1, sizeof(snd_seq_client_pool_t));
4504 * \brief frees a previously allocated #snd_seq_client_pool_t
4505 * \param obj pointer to object to free
4507 void snd_seq_client_pool_free(snd_seq_client_pool_t *obj)
4513 * \brief copy one #snd_seq_client_pool_t to another
4514 * \param dst pointer to destination
4515 * \param src pointer to source
4517 void snd_seq_client_pool_copy(snd_seq_client_pool_t *dst, const snd_seq_client_pool_t *src)
4525 * \brief Get the client id of a queue_info container
4526 * \param info client_pool container
4529 int snd_seq_client_pool_get_client(const snd_seq_client_pool_t *info)
4532 return info->client;
4536 * \brief Get the output pool size of a queue_info container
4537 * \param info client_pool container
4538 * \return output pool size
4540 size_t snd_seq_client_pool_get_output_pool(const snd_seq_client_pool_t *info)
4543 return info->output_pool;
4547 * \brief Get the input pool size of a queue_info container
4548 * \param info client_pool container
4549 * \return input pool size
4551 size_t snd_seq_client_pool_get_input_pool(const snd_seq_client_pool_t *info)
4554 return info->input_pool;
4558 * \brief Get the output room size of a queue_info container
4559 * \param info client_pool container
4560 * \return output room size
4562 size_t snd_seq_client_pool_get_output_room(const snd_seq_client_pool_t *info)
4565 return info->output_room;
4569 * \brief Get the available size on output pool of a queue_info container
4570 * \param info client_pool container
4571 * \return available output size
4573 size_t snd_seq_client_pool_get_output_free(const snd_seq_client_pool_t *info)
4576 return info->output_free;
4580 * \brief Get the available size on input pool of a queue_info container
4581 * \param info client_pool container
4582 * \return available input size
4584 size_t snd_seq_client_pool_get_input_free(const snd_seq_client_pool_t *info)
4587 return info->input_free;
4591 * \brief Set the output pool size of a queue_info container
4592 * \param info client_pool container
4593 * \param size output pool size
4595 void snd_seq_client_pool_set_output_pool(snd_seq_client_pool_t *info, size_t size)
4598 info->output_pool = size;
4602 * \brief Set the input pool size of a queue_info container
4603 * \param info client_pool container
4604 * \param size input pool size
4606 void snd_seq_client_pool_set_input_pool(snd_seq_client_pool_t *info, size_t size)
4609 info->input_pool = size;
4613 * \brief Set the output room size of a queue_info container
4614 * \param info client_pool container
4615 * \param size output room size
4617 void snd_seq_client_pool_set_output_room(snd_seq_client_pool_t *info, size_t size)
4620 info->output_room = size;
4625 * \brief obtain the pool information of the current client
4626 * \param seq sequencer handle
4627 * \param info information to be stored
4629 int snd_seq_get_client_pool(snd_seq_t *seq, snd_seq_client_pool_t *info)
4631 assert(seq && info);
4632 info->client = seq->client;
4633 return seq->ops->get_client_pool(seq, info);
4637 * \brief set the pool information
4638 * \param seq sequencer handle
4639 * \param info information to update
4641 * Sets the pool information of the current client.
4642 * The client field in \a info is replaced automatically with the current id.
4644 int snd_seq_set_client_pool(snd_seq_t *seq, snd_seq_client_pool_t *info)
4646 assert(seq && info);
4647 info->client = seq->client;
4648 return seq->ops->set_client_pool(seq, info);
4651 /*----------------------------------------------------------------*/
4658 * \brief set a bit flag
4660 void snd_seq_set_bit(int nr, void *array)
4662 ((unsigned int *)array)[nr >> 5] |= 1UL << (nr & 31);
4666 * \brief unset a bit flag
4668 void snd_seq_unset_bit(int nr, void *array)
4670 ((unsigned int *)array)[nr >> 5] &= ~(1UL << (nr & 31));
4674 * \brief change a bit flag
4676 int snd_seq_change_bit(int nr, void *array)
4680 result = ((((unsigned int *)array)[nr >> 5]) & (1UL << (nr & 31))) ? 1 : 0;
4681 ((unsigned int *)array)[nr >> 5] ^= 1UL << (nr & 31);
4686 * \brief get a bit flag state
4688 int snd_seq_get_bit(int nr, void *array)
4690 return ((((unsigned int *)array)[nr >> 5]) & (1UL << (nr & 31))) ? 1 : 0;