** Warning: Cannot open xref database.
1 /*
2 Copyright (C) 2001 Paul Davis
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU Lesser General Public License as published by
6 the Free Software Foundation; either version 2.1 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU Lesser General Public License for more details.
13
14 You should have received a copy of the GNU Lesser General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
17
18 $Id: jack.h,v 1.54 2003/12/01 19:45:14 pbd Exp $
19 */
20
21 #ifndef __jack_h__
22 #define __jack_h__
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 #include <pthread.h>
29
30 #include <jack/types.h>
31 #include <jack/transport.h>
32
33 /**
34 * Note: More documentation can be found in jack/types.h.
35 */
36
37 /**
38 * Attemps to become an external client of the Jack server.
39 */
40 jack_client_t *jack_client_new (const char *client_name);
41
42 /**
43 * Disconnects an external client from a JACK server.
44 *
45 * @return 0 on success, otherwise a non-zero error code
46 */
47 int jack_client_close (jack_client_t *client);
48
49 /**
50 * @param client_name The name for the new client
51 * @param so_name A path to a shared object file containing the code for the new client
52 * @param so_data An arbitary string containing information to be passed to the init() routine of the new client
53 *
54 * Attemps to load an internal client into the Jack server.
55 */
56 int jack_internal_client_new (const char *client_name, const char *so_name, const char *so_data);
57
58 /**
59 * Removes an internal client from a JACK server.
60 *
61 * @return 0 on success, otherwise a non-zero error code
62 */
63 void jack_internal_client_close (const char *client_name);
64
65 /**
66 * @param client The Jack client structure.
67 *
68 * Check if the JACK subsystem is running with -R (--realtime).
69 *
70 * @return 1 if JACK is running realtime, 0 otherwise
71 */
72 int jack_is_realtime (jack_client_t *client);
73
74 /**
75 * @param client The Jack client structure.
76 * @param function The jack_shutdown function pointer.
77 * @param arg The arguments for the jack_shutdown function.
78 *
79 * Register a function (and argument) to be called if and when the
80 * JACK server shuts down the client thread. The function must
81 * be written as if it were an asynchonrous POSIX signal
82 * handler --- use only async-safe functions, and remember that it
83 * is executed from another thread. A typical function might
84 * set a flag or write to a pipe so that the rest of the
85 * application knows that the JACK client thread has shut
86 * down.
87 *
88 * NOTE: clients do not need to call this. It exists only
89 * to help more complex clients understand what is going
90 * on. It should be called before jack_client_activate().
91 */
92 void jack_on_shutdown (jack_client_t *client, void (*function)(void *arg), void *arg);
93
94 /**
95 * Tell the Jack server to call @a process_callback whenever there is
96 * work be done, passing @a arg as the second argument.
97 *
98 * The code in the supplied function must be suitable for real-time
99 * execution. That means that it cannot call functions that might
100 * block for a long time. This includes malloc, free, printf,
101 * pthread_mutex_lock, sleep, wait, poll, select, pthread_join,
102 * pthread_cond_wait, etc, etc. See
103 * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000
104 * for more information.
105 *
106 * @return 0 on success, otherwise a non-zero error code, causing JACK
107 * to remove that client from the process() graph.
108 */
109 int jack_set_process_callback (jack_client_t *client,
110 JackProcessCallback process_callback,
111 void *arg);
112
113 /**
114 * Tell the Jack server to call @a freewheel_callback
115 * whenever we enter or leave "freewheel" mode, passing @a
116 * arg as the second argument. The first argument to the
117 * callback will be non-zero if JACK is entering freewheel
118 * mode, and zero otherwise.
119 *
120 * @return 0 on success, otherwise a non-zero error code.
121 */
122 int jack_set_freewheel_callback (jack_client_t *client,
123 JackFreewheelCallback freewheel_callback,
124 void *arg);
125
126 /**
127 * Start/Stop JACK's "freewheel" mode.
128 *
129 * When in "freewheel" mode, JACK no longer waits for
130 * any external event to begin the start of the next process
131 * cycle.
132 *
133 * As a result, freewheel mode causes "faster than realtime"
134 * execution of a JACK graph. If possessed, real-time
135 * scheduling is dropped when entering freewheel mode, and
136 * if appropriate it is reacquired when stopping.
137 *
138 * @param client pointer to JACK client structure
139 * @param onoff if non-zero, freewheel mode starts. Otherwise
140 * freewheel mode ends.
141 *
142 * @return 0 on success, otherwise a non-zero error code.
143 */
144 int jack_set_freewheel(jack_client_t* client, int onoff);
145
146 /**
147 * Change the buffer size passed to the @a process_callback.
148 *
149 * This operation stops the JACK engine process cycle, then calls all
150 * registered @a bufsize_callback functions before restarting the
151 * process cycle. This will cause a gap in the audio flow, so it
152 * should only be done at appropriate stopping points.
153 *
154 * @see jack_set_buffer_size_callback()
155 *
156 * @param client pointer to JACK client structure.
157 * @param nframes new buffer size. Must be a power of two.
158 *
159 * @return 0 on success, otherwise a non-zero error code
160 */
161 int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes);
162
163 /**
164 * Tell JACK to call @a bufsize_callback whenever the size of the the
165 * buffer that will be passed to the @a process_callback is about to
166 * change. Clients that depend on knowing the buffer size must supply
167 * a @a bufsize_callback before activating themselves.
168 *
169 * @param client pointer to JACK client structure.
170 * @param bufsize_callback function to call when the buffer size changes.
171 * @param arg argument for @a bufsize_callback.
172 *
173 * @return 0 on success, otherwise a non-zero error code
174 */
175 int jack_set_buffer_size_callback (jack_client_t *client,
176 JackBufferSizeCallback bufsize_callback,
177 void *arg);
178
179 /**
180 * Tell the Jack server to call @a srate_callback whenever the system
181 * sample rate changes.
182 *
183 * @return 0 on success, otherwise a non-zero error code
184 */
185 int jack_set_sample_rate_callback (jack_client_t *client,
186 JackSampleRateCallback srate_callback,
187 void *arg);
188
189 /**
190 * Tell the Jack server to call 'registration_callback' whenever a port is registered
191 * or unregistered, passing 'arg' as a second argument.
192 *
193 * @return 0 on success, otherwise a non-zero error code
194 */
195 int jack_set_port_registration_callback (jack_client_t *, JackPortRegistrationCallback registration_callback, void *arg);
196
197 /**
198 * Tell the Jack server to call 'registration_callback' whenever the processing
199 * graph is reordered, passing 'arg' as an argument.
200 *
201 * @return 0 on success, otherwise a non-zero error code
202 */
203 int jack_set_graph_order_callback (jack_client_t *, JackGraphOrderCallback graph_callback, void *);
204
205 /**
206 * Tell the Jack server to call 'xrun_callback' whenever there is a xrun, passing
207 * 'arg' as an argument.
208 *
209 * @return 0 on success, otherwise a non-zero error code
210 */
211 int jack_set_xrun_callback (jack_client_t *, JackXRunCallback xrun_callback, void *arg);
212
213 /**
214 * Tell the Jack server that the program is ready to start processing
215 * audio.
216 *
217 * @return 0 on success, otherwise a non-zero error code
218 */
219 int jack_activate (jack_client_t *client);
220
221 /**
222 * Tells the Jack server that the program should be removed from the
223 * processing graph. As a side effect, this will disconnect any
224 * and all ports belonging to the client, since inactive clients
225 * are not allowed to be connected to any other ports.
226 *
227 * @return 0 on success, otherwise a non-zero error code
228 */
229 int jack_deactivate (jack_client_t *client);
230
231 /**
232 * This creates a new port for the client.
233 *
234 * A port is an object used for moving data in or out of the client.
235 * the data may be of any type. Ports may be connected to each other
236 * in various ways.
237 *
238 * A port has a short name, a non-NULL and non-zero length string, and
239 * is passed as the first argument. A port's full name is the name of
240 * the client concatenated with a colon (:) and then its short
241 * name. There are limits to the length of the name, and exceeding
242 * them will cause registration of the port to fail and the function
243 * to return NULL. The limit is derived from the size of a full port
244 * name, which also has to include the client name and a separator
245 * character.
246 *
247 * A port has a type, which may be any non-NULL and non-zero length
248 * string, and is passed as the second argument. Some port types are
249 * built into the JACK API (currently only JACK_DEFAULT_AUDIO_TYPE).
250 * For other types, the client must supply a non-zero @a buffer_size.
251 * For builtin types, @a buffer_size is ignored.
252 *
253 * The @a flags argument is formed from a bitmask of JackPortFlags values.
254 *
255 * @return a valid jack_port_t* on success, NULL otherwise.
256 */
257 jack_port_t *jack_port_register (jack_client_t *,
258 const char *port_name,
259 const char *port_type,
260 unsigned long flags,
261 unsigned long buffer_size);
262
263 /**
264 * This removes the port from the client, disconnecting
265 * any existing connections at the same time.
266 *
267 * @return 0 on success, otherwise a non-zero error code
268 */
269 int jack_port_unregister (jack_client_t *, jack_port_t *);
270
271 /**
272 * This returns a pointer to the memory area associated with the
273 * specified port. For an output port, it will be a memory area
274 * that can be written to; for an input port, it will be an area
275 * containing the data from the port's connection(s), or
276 * zero-filled. if there are multiple inbound connections, the data
277 * will be mixed appropriately.
278 *
279 * FOR OUTPUT PORTS ONLY
280 * ---------------------
281 * You may cache the value returned, but only between calls to
282 * your "blocksize" callback. For this reason alone, you should
283 * either never cache the return value or ensure you have
284 * a "blocksize" callback and be sure to invalidate the cached
285 * address from there.
286 */
287 void *jack_port_get_buffer (jack_port_t *, jack_nframes_t);
288
289 /**
290 * Returns the name of the jack_port_t.
291 */
292 const char * jack_port_name (const jack_port_t *port);
293
294 /**
295 * Returns the short name of the jack_port_t.
296 */
297 const char * jack_port_short_name (const jack_port_t *port);
298
299 /**
300 * Returns the flags of the jack_port_t.
301 */
302 int jack_port_flags (const jack_port_t *port);
303
304 /**
305 * Returns the type of the jack_port_t.
306 */
307 const char * jack_port_type (const jack_port_t *port);
308
309 /**
310 * Returns 1 if the jack_port_t belongs to the jack_client_t.
311 */
312 int jack_port_is_mine (const jack_client_t *, const jack_port_t *port);
313
314 /**
315 * This returns a positive integer indicating the number
316 * of connections to or from 'port'.
317 *
318 * Ūpre The calling client must own 'port'.
319 */
320 int jack_port_connected (const jack_port_t *port);
321
322 /**
323 * This returns TRUE or FALSE if the port argument is
324 * DIRECTLY connected to the port with the name given in 'portname'
325 *
326 * @pre The calling client must own 'port'.
327 */
328 int jack_port_connected_to (const jack_port_t *port, const char *portname);
329
330 /**
331 * This returns a null-terminated array of port names to which
332 * the argument port is connected. if there are no connections, it
333 * returns NULL.
334 *
335 * The caller is responsible for calling free(3) on any
336 * non-NULL returned value.
337 *
338 * @pre The calling client must own 'port'.
339 *
340 * See jack_port_get_all_connections() for an alternative.
341 */
342 const char ** jack_port_get_connections (const jack_port_t *port);
343
344 /**
345 * This returns a null-terminated array of port names to which
346 * the argument port is connected. if there are no connections, it
347 * returns NULL.
348 *
349 * The caller is responsible for calling free(3) on any
350 * non-NULL returned value.
351 *
352 * It differs from jack_port_get_connections() in two important
353 * respects:
354 *
355 * 1) You may not call this function from code that is
356 * executed in response to a JACK event. For example,
357 * you cannot use it in a GraphReordered handler.
358 *
359 * 2) You need not be the owner of the port to get information
360 * about its connections.
361 */
362 const char ** jack_port_get_all_connections (const jack_client_t *client, const jack_port_t *port);
363
364 /**
365 * A client may call this on a pair of its own ports to
366 * semi-permanently wire them together. This means that
367 * a client that wants to direct-wire an input port to
368 * an output port can call this and then no longer
369 * have to worry about moving data between them. Any data
370 * arriving at the input port will appear automatically
371 * at the output port.
372 *
373 * The 'destination' port must be an output port. The 'source'
374 * port must be an input port. Both ports must belong to
375 * the same client. You cannot use this to tie ports between
376 * clients. That is what a connection is for.
377 *
378 * @return 0 on success, otherwise a non-zero error code
379 */
380 int jack_port_tie (jack_port_t *src, jack_port_t *dst);
381
382 /**
383 * This undoes the effect of jack_port_tie(). The port
384 * should be same as the 'destination' port passed to
385 * jack_port_tie().
386 *
387 * @return 0 on success, otherwise a non-zero error code
388 */
389 int jack_port_untie (jack_port_t *port);
390
391 /**
392 * A client may call this function to prevent other objects
393 * from changing the connection status of a port. The port
394 * must be owned by the calling client.
395 *
396 * @return 0 on success, otherwise a non-zero error code
397 */
398 int jack_port_lock (jack_client_t *, jack_port_t *);
399
400 /**
401 * This allows other objects to change the connection status of a port.
402 *
403 * @return 0 on success, otherwise a non-zero error code
404 */
405 int jack_port_unlock (jack_client_t *, jack_port_t *);
406
407 /**
408 * Returns the time (in frames) between data being
409 * available or delivered at/to a port, and the time at
410 * which it arrived at or is delivered to the "other side"
411 * of the port. E.g. for a physical audio output port, this
412 * is the time between writing to the port and when the
413 * signal will leave the connector. For a physical audio
414 * input port, this is the time between the sound arriving
415 * at the connector and the corresponding frames being
416 * readable from the port.
417 */
418 jack_nframes_t jack_port_get_latency (jack_port_t *port);
419
420 /**
421 * The maximum of the sum of the latencies in every
422 * connection path that can be drawn between the port and other
423 * ports with the JackPortIsTerminal flag set.
424 */
425 jack_nframes_t jack_port_get_total_latency (jack_client_t *, jack_port_t *port);
426
427 /**
428 * The port latency is zero by default. Clients that control
429 * physical hardware with non-zero latency should call this
430 * to set the latency to its correct value. Note that the value
431 * should include any systemic latency present "outside" the
432 * physical hardware controlled by the client. For example,
433 * for a client controlling a digital audio interface connected
434 * to an external digital converter, the latency setting should
435 * include both buffering by the audio interface *and* the converter.
436 */
437 void jack_port_set_latency (jack_port_t *, jack_nframes_t);
438
439 /**
440 * This modifies a port's name, and may be called at any time.
441 *
442 * @return 0 on success, otherwise a non-zero error code
443 */
444 int jack_port_set_name (jack_port_t *port, const char *name);
445
446 /**
447 * If JackPortCanMonitor is set for a port, then these 2 functions will
448 * turn on/off input monitoring for the port. If JackPortCanMonitor
449 * is not set, then these functions will have no effect.
450 */
451 int jack_port_request_monitor (jack_port_t *port, int onoff);
452
453 /**
454 * If JackPortCanMonitor is set for a port, then these 2 functions will
455 * turn on/off input monitoring for the port. If JackPortCanMonitor
456 * is not set, then these functions will have no effect.
457 *
458 * @return 0 on success, otherwise a non-zero error code
459 */
460 int jack_port_request_monitor_by_name (jack_client_t *client, const char *port_name, int onoff);
461
462 /**
463 * If JackPortCanMonitor is set for a port, then this function will
464 * turn on input monitoring if it was off, and will turn it off it
465 * only one request has been made to turn it on. If JackPortCanMonitor
466 * is not set, then this function will do nothing.
467 *
468 * @return 0 on success, otherwise a non-zero error code
469 */
470 int jack_port_ensure_monitor (jack_port_t *port, int onoff);
471
472 /**
473 * Returns a true or false value depending on whether or not
474 * input monitoring has been requested for 'port'.
475 */
476 int jack_port_monitoring_input (jack_port_t *port);
477
478 /**
479 * Establishes a connection between two ports.
480 *
481 * When a connection exists, data written to the source port will
482 * be available to be read at the destination port.
483 *
484 * @pre The types of both ports must be identical to establish a connection.
485 * @pre The flags of the source port must include PortIsOutput.
486 * @pre The flags of the destination port must include PortIsInput.
487 *
488 * @return 0 on success, EEXIST if the connection is allready made, otherwise
489 * a non-zero error code
490 */
491 int jack_connect (jack_client_t *,
492 const char *source_port,
493 const char *destination_port);
494
495 /**
496 * Removes a connection between two ports.
497 *
498 * @pre The types of both ports must be identical to establish a connection.
499 * @pre The flags of the source port must include PortIsOutput.
500 * @pre The flags of the destination port must include PortIsInput.
501 *
502 * @return 0 on success, otherwise a non-zero error code
503 */
504 int jack_disconnect (jack_client_t *,
505 const char *source_port,
506 const char *destination_port);
507
508 /**
509 * Performs the exact same function as jack_connect(), but it uses
510 * port handles rather than names, which avoids the name lookup inherent
511 * in the name-based version.
512 *
513 * It is envisaged that clients connecting their own ports will use these
514 * two, whereas generic connection clients (e.g. patchbays) will use the
515 * name-based versions.
516 *
517 * @return 0 on success, otherwise a non-zero error code
518 */
519 int jack_port_connect (jack_client_t *, jack_port_t *src, jack_port_t *dst);
520
521 /**
522 * Performs the exact same function as jack_disconnect(), but it uses
523 * port handles rather than names, which avoids the name lookup inherent
524 * in the name-based version.
525 *
526 * It is envisaged that clients disconnecting their own ports will use these
527 * two, whereas generic connection clients (e.g. patchbays) will use the
528 * name-based versions.
529 */
530 int jack_port_disconnect (jack_client_t *, jack_port_t *);
531
532 /**
533 * This returns the sample rate of the jack system, as set by the user when
534 * jackd was started.
535 */
536 jack_nframes_t jack_get_sample_rate (jack_client_t *);
537
538 /**
539 * This returns the current maximum size that will ever be passed to
540 * the @a process_callback. It should only be used *before* the
541 * client has been activated. This size may change, clients that
542 * depend on it must register a @a bufsize_callback so they will be
543 * notified if it does.
544 *
545 * @see jack_set_buffer_size_callback()
546 */
547 jack_nframes_t jack_get_buffer_size (jack_client_t *);
548
549 /**
550 * @param port_name_pattern A regular expression used to select
551 * ports by name. If NULL or of zero length, no selection based
552 * on name will be carried out.
553 * @param type_name_pattern A regular expression used to select
554 * ports by type. If NULL or of zero length, no selection based
555 * on type will be carried out.
556 * @param flags A value used to select ports by their flags.
557 * If zero, no selection based on flags will be carried out.
558 *
559 * This function returns a NULL-terminated array of ports that match
560 * the specified arguments.
561 * The caller is responsible for calling free(3) any non-NULL returned value.
562 */
563 const char ** jack_get_ports (jack_client_t *,
564 const char *port_name_pattern,
565 const char *type_name_pattern,
566 unsigned long flags);
567
568 /**
569 * Searchs for and returns the jack_port_t with the name value
570 * from portname.
571 */
572 jack_port_t *jack_port_by_name (jack_client_t *, const char *portname);
573
574 /**
575 * Searchs for and returns the jack_port_t of id 'id'.
576 */
577 jack_port_t *jack_port_by_id (const jack_client_t *client, jack_port_id_t id);
578
579 /**
580 * Old-style interface to become the timebase for the entire JACK
581 * subsystem.
582 *
583 * @deprecated This function still exists for compatibility with the
584 * earlier transport interface, but it does nothing. Instead, see
585 * <jack/transport.h> and use jack_set_timebase_callback().
586 *
587 * @return ENOSYS, function not implemented.
588 */
589 int jack_engine_takeover_timebase (jack_client_t *);
590
591 /**
592 * This estimates the time that has passed since the JACK server
593 * started calling the process callbacks of all its clients.
594 */
595 jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *);
596
597 /**
598 * Return an estimate of the current time in frames. It is a running
599 * counter - no significance should be attached to the return
600 * value. it should be used to compute the difference between
601 * a previously returned value.
602 */
603 jack_nframes_t jack_frame_time (const jack_client_t *);
604
605 /**
606 * This returns the current CPU load estimated by JACK
607 * as a percentage. The load is computed by measuring
608 * the amount of time it took to execute all clients
609 * as a fraction of the total amount of time
610 * represented by the data that was processed.
611 */
612 float jack_cpu_load (jack_client_t *client);
613
614 /**
615 * Set the directory in which the server is expected
616 * to have put its communication FIFOs. A client
617 * will need to call this before calling
618 * jack_client_new() if the server was started
619 * with arguments telling it to use a non-standard
620 * directory.
621 *
622 * @deprecated This function is deprecated. Don't use in new programs
623 * and remove it in old programs.
624 */
625 void jack_set_server_dir (const char *path);
626
627 /**
628 * Return the pthread ID of the thread running the JACK client
629 * side code.
630 */
631 pthread_t jack_client_thread_id (jack_client_t *);
632
633 extern void (*jack_error_callback)(const char *desc);
634
635 /**
636 * Sets callback to be called to print error messages.
637 */
638 void jack_set_error_function (void (*func)(const char *));
639
640 #ifdef __cplusplus
641 }
642 #endif
643
644 #endif /* __jack_h__ */
645
646
647
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.