root/trunk/jack/jack/jack.h

Revision 4598, 43.8 kB (checked in by paul, 3 years ago)

install jslist.h since its now used by control.h

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1 /*
2     Copyright (C) 2001 Paul Davis
3     Copyright (C) 2004 Jack O'Quin
4    
5     This program is free software; you can redistribute it and/or modify
6     it under the terms of the GNU Lesser General Public License as published by
7     the Free Software Foundation; either version 2.1 of the License, or
8     (at your option) any later version.
9    
10     This program is distributed in the hope that it will be useful,
11     but WITHOUT ANY WARRANTY; without even the implied warranty of
12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13     GNU Lesser General Public License for more details.
14    
15     You should have received a copy of the GNU Lesser General Public License
16     along with this program; if not, write to the Free Software
17     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
18
19 */
20
21 #ifndef __jack_h__
22 #define __jack_h__
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 #include <jack/types.h>
29 #include <jack/transport.h>
30
31 /**
32  * Note: More documentation can be found in jack/types.h.
33
34  */
35
36 /*************************************************************
37  * NOTE: JACK_WEAK_EXPORT ***MUST*** be used on every function
38  * added to the JACK API after the 0.116.2 release.
39  *
40  * Functions that predate this release are marked with
41  * JACK_WEAK_OPTIONAL_EXPORT which can be defined at compile
42  * time in a variety of ways. The default definition is empty,
43  * so that these symbols get normal linkage. If you wish to
44  * use all JACK symbols with weak linkage, include
45  * <jack/weakjack.h> before jack.h.
46  *************************************************************/
47
48 #include <jack/weakmacros.h>
49
50 /**
51  * @defgroup ClientFunctions Creating & manipulating clients
52  * @{
53  */
54
55 /**
56  * Open an external client session with a JACK server.  This interface
57  * is more complex but more powerful than jack_client_new().  With it,
58  * clients may choose which of several servers to connect, and control
59  * whether and how to start the server automatically, if it was not
60  * already running.  There is also an option for JACK to generate a
61  * unique client name, when necessary.
62  *
63  * @param client_name of at most jack_client_name_size() characters.
64  * The name scope is local to each server.  Unless forbidden by the
65  * @ref JackUseExactName option, the server will modify this name to
66  * create a unique variant, if needed.
67  *
68  * @param options formed by OR-ing together @ref JackOptions bits.
69  * Only the @ref JackOpenOptions bits are allowed.
70  *
71  * @param status (if non-NULL) an address for JACK to return
72  * information from the open operation.  This status word is formed by
73  * OR-ing together the relevant @ref JackStatus bits.
74  *
75  *
76  * <b>Optional parameters:</b> depending on corresponding [@a options
77  * bits] additional parameters may follow @a status (in this order).
78  *
79  * @arg [@ref JackServerName] <em>(char *) server_name</em> selects
80  * from among several possible concurrent server instances.  Server
81  * names are unique to each user.  If unspecified, use "default"
82  * unless \$JACK_DEFAULT_SERVER is defined in the process environment.
83  *
84  * @return Opaque client handle if successful.  If this is NULL, the
85  * open operation failed, @a *status includes @ref JackFailure and the
86  * caller is not a JACK client.
87  */
88 jack_client_t *jack_client_open (const char *client_name,
89                                  jack_options_t options,
90                                  jack_status_t *status, ...) JACK_OPTIONAL_WEAK_EXPORT;
91
92 /**
93  * <b>THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
94  *  NEW JACK CLIENTS</b>
95  *
96  */
97 jack_client_t *jack_client_new (const char *client_name) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
98
99 /**
100  * Disconnects an external client from a JACK server.
101  *
102  * @return 0 on success, otherwise a non-zero error code
103  */
104 int jack_client_close (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT;
105
106 /**
107  * @return the maximum number of characters in a JACK client name
108  * including the final NULL character.  This value is a constant.
109  */
110 int jack_client_name_size (void) JACK_OPTIONAL_WEAK_EXPORT;
111
112 /**
113  * @return pointer to actual client name.  This is useful when @ref
114  * JackUseExactName is not specified on open and @ref
115  * JackNameNotUnique status was returned.  In that case, the actual
116  * name will differ from the @a client_name requested.
117  */
118 char *jack_get_client_name (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT;
119
120 /**
121  * Load an internal client into the Jack server.
122  *
123  * Internal clients run inside the JACK server process.  They can use
124  * most of the same functions as external clients.  Each internal
125  * client must declare jack_initialize() and jack_finish() entry
126  * points, called at load and unload times.  See inprocess.c for an
127  * example of how to write an internal client.
128  *
129  * @deprecated Please use jack_internal_client_load().
130  *
131  * @param client_name of at most jack_client_name_size() characters.
132  *
133  * @param load_name of a shared object file containing the code for
134  * the new client.
135  *
136  * @param load_init an arbitary string passed to the jack_initialize()
137  * routine of the new client (may be NULL).
138  *
139  * @return 0 if successful.
140  */
141 int jack_internal_client_new (const char *client_name,
142                               const char *load_name,
143                               const char *load_init) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
144
145 /**
146  * Remove an internal client from a JACK server.
147  *
148  * @deprecated Please use jack_internal_client_load().
149  */
150 void jack_internal_client_close (const char *client_name) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
151
152 /**
153  * Tell the Jack server that the program is ready to start processing
154  * audio.
155  *
156  * @return 0 on success, otherwise a non-zero error code
157  */
158 int jack_activate (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT;
159
160 /**
161  * Tell the Jack server to remove this @a client from the process
162  * graph.  Also, disconnect all ports belonging to it, since inactive
163  * clients have no port connections.
164  *
165  * @return 0 on success, otherwise a non-zero error code
166  */
167 int jack_deactivate (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT;
168
169 /**
170  * @return the pthread ID of the thread running the JACK client side
171  * code.
172  */
173 jack_native_thread_t jack_client_thread_id (jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT;
174
175 /*@}*/
176
177 /**
178  * @param client pointer to JACK client structure.
179  *
180  * Check if the JACK subsystem is running with -R (--realtime).
181  *
182  * @return 1 if JACK is running realtime, 0 otherwise
183  */
184 int jack_is_realtime (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT;
185
186 /**
187  * @defgroup NonCallbackAPI The non-callback API
188  * @{
189  */
190
191 /**
192  * <b>THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
193  * NEW JACK CLIENTS</b>
194  *
195  * It should be replace by use of @ jack_cycle_wait and @ jack_cycle_signal functions.
196  *
197  */
198 jack_nframes_t jack_thread_wait (jack_client_t*, int status) JACK_OPTIONAL_WEAK_EXPORT;
199
200 /**
201  * Wait until this JACK client should process data.
202  *
203  * @param client - pointer to a JACK client structure
204  *
205  * @return the number of frames of data to process
206  */
207 jack_nframes_t jack_cycle_wait (jack_client_t* client) JACK_OPTIONAL_WEAK_EXPORT;
208        
209 /**
210  * Signal next clients in the graph.
211  *
212  * @param client - pointer to a JACK client structure
213  * @param status - if non-zero, calling thread should exit
214  */
215 void jack_cycle_signal (jack_client_t* client, int status) JACK_OPTIONAL_WEAK_EXPORT;
216        
217 /**
218  * Tell the Jack server to call @a thread_callback in the RT thread.
219  * Typical use are in conjunction with @a jack_cycle_wait and @ jack_cycle_signal functions.
220  * The code in the supplied function must be suitable for real-time
221  * execution. That means that it cannot call functions that might
222  * block for a long time. This includes all I/O functions (disk, TTY, network),
223  * malloc, free, printf, pthread_mutex_lock, sleep, wait, poll, select, pthread_join,
224  * pthread_cond_wait, etc, etc.
225  *
226  * @return 0 on success, otherwise a non-zero error code.
227 */   
228 int jack_set_process_thread(jack_client_t* client, JackThreadCallback fun, void *arg) JACK_OPTIONAL_WEAK_EXPORT;
229
230 /*@}*/
231
232 /**
233  * @defgroup ClientCallbacks Setting Client Callbacks
234  * @{
235  */
236
237 /**
238  * Tell JACK to call @a thread_init_callback once just after
239  * the creation of the thread in which all other callbacks
240  * will be handled.
241  *
242  * The code in the supplied function does not need to be
243  * suitable for real-time execution.
244  *
245  * @return 0 on success, otherwise a non-zero error code, causing JACK
246  * to remove that client from the process() graph.
247  */
248 int jack_set_thread_init_callback (jack_client_t *client,
249                                    JackThreadInitCallback thread_init_callback,
250                                    void *arg) JACK_OPTIONAL_WEAK_EXPORT;
251
252 /**
253  * @param client pointer to JACK client structure.
254  * @param function The jack_shutdown function pointer.
255  * @param arg The arguments for the jack_shutdown function.
256  *
257  * Register a function (and argument) to be called if and when the
258  * JACK server shuts down the client thread.  The function must
259  * be written as if it were an asynchonrous POSIX signal
260  * handler --- use only async-safe functions, and remember that it
261  * is executed from another thread.  A typical function might
262  * set a flag or write to a pipe so that the rest of the
263  * application knows that the JACK client thread has shut
264  * down.
265  *
266  * NOTE: clients do not need to call this.  It exists only
267  * to help more complex clients understand what is going
268  * on.  It should be called before jack_client_activate().
269  *
270  * NOTE: if a client calls this AND jack_on_info_shutdown(), then
271  * the event of a client thread shutdown, the callback
272  * passed to this function will not be called, and the one passed to
273  * jack_on_info_shutdown() will.
274  */
275 void jack_on_shutdown (jack_client_t *client,
276                        JackShutdownCallback function, void *arg) JACK_OPTIONAL_WEAK_EXPORT;
277
278 /**
279  * @param client pointer to JACK client structure.
280  * @param function The jack_shutdown function pointer.
281  * @param arg The arguments for the jack_shutdown function.
282  *
283  * Register a function (and argument) to be called if and when the
284  * JACK server shuts down the client thread.  The function must
285  * be written as if it were an asynchonrous POSIX signal
286  * handler --- use only async-safe functions, and remember that it
287  * is executed from another thread.  A typical function might
288  * set a flag or write to a pipe so that the rest of the
289  * application knows that the JACK client thread has shut
290  * down.
291  *
292  * NOTE: clients do not need to call this.  It exists only
293  * to help more complex clients understand what is going
294  * on.  It should be called before jack_client_activate().
295  *
296  * NOTE: if a client calls this AND jack_on_shutdown(), then in the
297  * event of a client thread shutdown, the callback   passed to
298  * this function will be called, and the one passed to
299  * jack_on_shutdown() will not.
300  */
301 void jack_on_info_shutdown (jack_client_t *client,
302                             JackInfoShutdownCallback function, void *arg) JACK_WEAK_EXPORT;
303
304 /**
305  * Tell the Jack server to call @a process_callback whenever there is
306  * work be done, passing @a arg as the second argument.
307  *
308  * The code in the supplied function must be suitable for real-time
309  * execution. That means that it cannot call functions that might
310  * block for a long time. This includes all I/O functions (disk, TTY, network),
311  * malloc, free, printf, pthread_mutex_lock, sleep, wait, poll, select, pthread_join,
312  * pthread_cond_wait, etc, etc.
313  *
314  * @return 0 on success, otherwise a non-zero error code, causing JACK
315  * to remove that client from the process() graph.
316  */
317 int jack_set_process_callback (jack_client_t *client,
318                                JackProcessCallback process_callback,
319                                void *arg) JACK_OPTIONAL_WEAK_EXPORT;
320
321 /**
322  * Tell the Jack server to call @a freewheel_callback
323  * whenever we enter or leave "freewheel" mode, passing @a
324  * arg as the second argument. The first argument to the
325  * callback will be non-zero if JACK is entering freewheel
326  * mode, and zero otherwise.
327  *
328  * @return 0 on success, otherwise a non-zero error code.
329  */
330 int jack_set_freewheel_callback (jack_client_t *client,
331                                  JackFreewheelCallback freewheel_callback,
332                                  void *arg) JACK_OPTIONAL_WEAK_EXPORT;
333
334 /**
335  * Tell JACK to call @a bufsize_callback whenever the size of the the
336  * buffer that will be passed to the @a process_callback is about to
337  * change.  Clients that depend on knowing the buffer size must supply
338  * a @a bufsize_callback before activating themselves.
339  *
340  * @param client pointer to JACK client structure.
341  * @param bufsize_callback function to call when the buffer size changes.
342  * @param arg argument for @a bufsize_callback.
343  *
344  * @return 0 on success, otherwise a non-zero error code
345  */
346 int jack_set_buffer_size_callback (jack_client_t *client,
347                                    JackBufferSizeCallback bufsize_callback,
348                                    void *arg) JACK_OPTIONAL_WEAK_EXPORT;
349
350 /**
351  * Tell the Jack server to call @a srate_callback whenever the system
352  * sample rate changes.
353  *
354  * @return 0 on success, otherwise a non-zero error code
355  */
356 int jack_set_sample_rate_callback (jack_client_t *client,
357                                    JackSampleRateCallback srate_callback,
358                                    void *arg) JACK_OPTIONAL_WEAK_EXPORT;
359
360 /**
361  * Tell the JACK server to call @a registration_callback whenever a
362  * port is registered or unregistered, passing @a arg as a parameter.
363  *
364  * @return 0 on success, otherwise a non-zero error code
365  */
366 int jack_set_client_registration_callback (jack_client_t *,
367                                            JackClientRegistrationCallback
368                                            registration_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT;
369        
370 /**
371  * Tell the JACK server to call @a registration_callback whenever a
372  * port is registered or unregistered, passing @a arg as a parameter.
373  *
374  * @return 0 on success, otherwise a non-zero error code
375  */
376 int jack_set_port_registration_callback (jack_client_t *,
377                                          JackPortRegistrationCallback
378                                          registration_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT;
379
380 /**
381  * Tell the JACK server to call @a connect_callback whenever a
382  * port is connected or disconnected, passing @a arg as a parameter.
383  *
384  * @return 0 on success, otherwise a non-zero error code
385  */
386 int jack_set_port_connect_callback (jack_client_t *,
387                                     JackPortConnectCallback
388                                     connect_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT;
389 /**
390  * Tell the JACK server to call @a graph_callback whenever the
391  * processing graph is reordered, passing @a arg as a parameter.
392  *
393  * @return 0 on success, otherwise a non-zero error code
394  */
395 int jack_set_graph_order_callback (jack_client_t *,
396                                    JackGraphOrderCallback graph_callback,
397                                    void *) JACK_OPTIONAL_WEAK_EXPORT;
398
399 /**
400  * Tell the JACK server to call @a xrun_callback whenever there is a
401  * xrun, passing @a arg as a parameter.
402  *
403  * @return 0 on success, otherwise a non-zero error code
404  */
405 int jack_set_xrun_callback (jack_client_t *,
406                             JackXRunCallback xrun_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT;
407
408 /**
409  * Tell the Jack server to call @a latency_callback whenever it
410  * is necessary to recompute the latencies for some or all
411  * Jack ports.
412  *
413  * @a latency_callback will be called twice each time it is
414  * needed, once being passed JackCaptureLatency and once
415  * JackPlaybackLatency. See @ref LatencyFunctions for
416  * the definition of each type of latency and related functions.
417  *
418  * <b>IMPORTANT: Most JACK clients do NOT need to register a latency
419  * callback.</b>
420  *
421  * Clients that meet any of the following conditions do NOT
422  * need to register a latency callback:
423  *
424  *    - have only input ports
425  *    - have only output ports
426  *    - their output is totally unrelated to their input
427  *    - their output is not delayed relative to their input
428  *        (i.e. data that arrives in a given process()
429  *         callback is processed and output again in the
430  *         same callback)
431  *
432  * Clients NOT registering a latency callback MUST also
433  * satisfy this condition:
434  *
435  *    - have no multiple distinct internal signal pathways
436  *     
437  * This means that if your client has more than 1 input and
438  * output port, and considers them always "correlated"
439  * (e.g. as a stereo pair), then there is only 1 (e.g. stereo)
440  * signal pathway through the client. This would be true,
441  * for example, of a stereo FX rack client that has a
442  * left/right input pair and a left/right output pair.
443  *
444  * However, this is somewhat a matter of perspective. The
445  * same FX rack client could be connected so that its
446  * two input ports were connected to entirely separate
447  * sources. Under these conditions, the fact that the client
448  * does not register a latency callback MAY result
449  * in port latency values being incorrect.
450  *
451  * Clients that do not meet any of those conditions SHOULD
452  * register a latency callback.
453  *
454  * See the documentation for  @ref jack_port_set_latency_range()
455  * on how the callback should operate. Remember that the @a mode
456  * argument given to the latency callback will need to be
457  * passed into @ref jack_port_set_latency_range()
458  *
459  * @return 0 on success, otherwise a non-zero error code
460  */
461 int jack_set_latency_callback (jack_client_t *,
462                                JackLatencyCallback latency_callback,
463                                void *) JACK_WEAK_EXPORT;
464 /*@}*/
465
466 /**
467  * @defgroup ServerControl Controlling & querying JACK server operation
468  * @{
469  */
470
471 /**
472  * Start/Stop JACK's "freewheel" mode.
473  *
474  * When in "freewheel" mode, JACK no longer waits for
475  * any external event to begin the start of the next process
476  * cycle.
477  *
478  * As a result, freewheel mode causes "faster than realtime"
479  * execution of a JACK graph. If possessed, real-time
480  * scheduling is dropped when entering freewheel mode, and
481  * if appropriate it is reacquired when stopping.
482  *
483  * IMPORTANT: on systems using capabilities to provide real-time
484  * scheduling (i.e. Linux kernel 2.4), if onoff is zero, this function
485  * must be called from the thread that originally called jack_activate().
486  * This restriction does not apply to other systems (e.g. Linux kernel 2.6
487  * or OS X).
488  *
489  * @param client pointer to JACK client structure
490  * @param onoff  if non-zero, freewheel mode starts. Otherwise
491  *                  freewheel mode ends.
492  *
493  * @return 0 on success, otherwise a non-zero error code.
494  */
495 int jack_set_freewheel(jack_client_t* client, int onoff) JACK_OPTIONAL_WEAK_EXPORT;
496
497 /**
498  * Change the buffer size passed to the @a process_callback.
499  *
500  * This operation stops the JACK engine process cycle, then calls all
501  * registered @a bufsize_callback functions before restarting the
502  * process cycle.  This will cause a gap in the audio flow, so it
503  * should only be done at appropriate stopping points.
504  *
505  * @see jack_set_buffer_size_callback()
506  *
507  * @param client pointer to JACK client structure.
508  * @param nframes new buffer size.  Must be a power of two.
509  *
510  * @return 0 on success, otherwise a non-zero error code
511  */
512 int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes) JACK_OPTIONAL_WEAK_EXPORT;
513
514 /**
515  * @return the sample rate of the jack system, as set by the user when
516  * jackd was started.
517  */
518 jack_nframes_t jack_get_sample_rate (jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT;
519
520 /**
521  * @return the current maximum size that will ever be passed to the @a
522  * process_callback.  It should only be used *before* the client has
523  * been activated.  This size may change, clients that depend on it
524  * must register a @a bufsize_callback so they will be notified if it
525  * does.
526  *
527  * @see jack_set_buffer_size_callback()
528  */
529 jack_nframes_t jack_get_buffer_size (jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT;
530
531 /**
532  * Old-style interface to become the timebase for the entire JACK
533  * subsystem.
534  *
535  * @deprecated This function still exists for compatibility with the
536  * earlier transport interface, but it does nothing.  Instead, see
537  * transport.h and use jack_set_timebase_callback().
538  *
539  * @return ENOSYS, function not implemented.
540  */
541 int  jack_engine_takeover_timebase (jack_client_t *) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
542
543 /**
544  * @return the current CPU load estimated by JACK.  This is a running
545  * average of the time it takes to execute a full process cycle for
546  * all clients as a percentage of the real time available per cycle
547  * determined by the buffer size and sample rate.
548  */
549 float jack_cpu_load (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT;
550        
551
552 /*@}*/
553
554 /**
555  * @defgroup PortFunctions Creating & manipulating ports
556  * @{
557  */
558
559 /**
560  * Create a new port for the client. This is an object used for moving
561  * data of any type in or out of the client.  Ports may be connected
562  * in various ways.
563  *
564  * Each port has a short name.  The port's full name contains the name
565  * of the client concatenated with a colon (:) followed by its short
566  * name.  The jack_port_name_size() is the maximum length of this full
567  * name.  Exceeding that will cause the port registration to fail and
568  * return NULL.
569  *
570  * The @a port_name must be unique among all ports owned by this client.
571  * If the name is not unique, the registration will fail.
572  *
573  * All ports have a type, which may be any non-NULL and non-zero
574  * length string, passed as an argument.  Some port types are built
575  * into the JACK API, like JACK_DEFAULT_AUDIO_TYPE or JACK_DEFAULT_MIDI_TYPE
576  *
577  * @param client pointer to JACK client structure.
578  * @param port_name non-empty short name for the new port (not
579  * including the leading @a "client_name:"). Must be unique.
580  * @param port_type port type name.  If longer than
581  * jack_port_type_size(), only that many characters are significant.
582  * @param flags @ref JackPortFlags bit mask.
583  * @param buffer_size must be non-zero if this is not a built-in @a
584  * port_type.  Otherwise, it is ignored.
585  *
586  * @return jack_port_t pointer on success, otherwise NULL.
587  */
588 jack_port_t *jack_port_register (jack_client_t *client,
589                                  const char *port_name,
590                                  const char *port_type,
591                                  unsigned long flags,
592                                  unsigned long buffer_size) JACK_OPTIONAL_WEAK_EXPORT;
593
594 /**
595  * Remove the port from the client, disconnecting any existing
596  * connections.
597  *
598  * @return 0 on success, otherwise a non-zero error code
599  */
600 int jack_port_unregister (jack_client_t *, jack_port_t *) JACK_OPTIONAL_WEAK_EXPORT;
601
602 /**
603  * This returns a pointer to the memory area associated with the
604  * specified port. For an output port, it will be a memory area
605  * that can be written to; for an input port, it will be an area
606  * containing the data from the port's connection(s), or
607  * zero-filled. if there are multiple inbound connections, the data
608  * will be mixed appropriately. 
609  *
610  * Do not cache the returned address across process() callbacks.
611  * Port buffers have to be retrieved in each callback for proper functionning.
612  */
613 void *jack_port_get_buffer (jack_port_t *, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT;
614
615 /**
616  * @return the full name of the jack_port_t (including the @a
617  * "client_name:" prefix).
618  *
619  * @see jack_port_name_size().
620  */
621 const char *jack_port_name (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
622
623 /**
624  * @return the short name of the jack_port_t (not including the @a
625  * "client_name:" prefix).
626  *
627  * @see jack_port_name_size().
628  */
629 const char *jack_port_short_name (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
630
631 /**
632  * @return the @ref JackPortFlags of the jack_port_t.
633  */
634 int jack_port_flags (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
635
636 /**
637  * @return the @a port type, at most jack_port_type_size() characters
638  * including a final NULL.
639  */
640 const char *jack_port_type (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
641
642 /**
643  * @return TRUE if the jack_port_t belongs to the jack_client_t.
644  */
645 int jack_port_is_mine (const jack_client_t *, const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
646
647 /**
648  * @return number of connections to or from @a port.
649  *
650  * @pre The calling client must own @a port.
651  */
652 int jack_port_connected (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
653
654 /**
655  * @return TRUE if the locally-owned @a port is @b directly connected
656  * to the @a port_name.
657  *
658  * @see jack_port_name_size()
659  */
660 int jack_port_connected_to (const jack_port_t *port,
661                             const char *port_name) JACK_OPTIONAL_WEAK_EXPORT;
662
663 /**
664  * @return a null-terminated array of full port names to which the @a
665  * port is connected.  If none, returns NULL.
666  *
667  * The caller is responsible for calling jack_free(3) on any non-NULL
668  * returned value.
669  *
670  * @param port locally owned jack_port_t pointer.
671  *
672  * @see jack_port_name_size(), jack_port_get_all_connections()
673  */   
674 const char **jack_port_get_connections (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
675
676 /**
677  * @return a null-terminated array of full port names to which the @a
678  * port is connected.  If none, returns NULL.
679  *
680  * The caller is responsible for calling jack_free(3) on any non-NULL
681  * returned value.
682  *
683  * This differs from jack_port_get_connections() in two important
684  * respects:
685  *
686  *     1) You may not call this function from code that is
687  *          executed in response to a JACK event. For example,
688  *          you cannot use it in a GraphReordered handler.
689  *
690  *     2) You need not be the owner of the port to get information
691  *          about its connections.
692  *
693  * @see jack_port_name_size()
694  */   
695 const char **jack_port_get_all_connections (const jack_client_t *client,
696                                             const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
697
698 /**
699  *
700  * @deprecated This function will be removed from a future version
701  * of JACK. Do not use it. There is no replacement. It has
702  * turned out to serve essentially no purpose in real-life
703  * JACK clients.
704  */
705 int  jack_port_tie (jack_port_t *src, jack_port_t *dst) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
706
707 /**
708  *
709  * @deprecated This function will be removed from a future version
710  * of JACK. Do not use it. There is no replacement. It has
711  * turned out to serve essentially no purpose in real-life
712  * JACK clients.
713  */
714 int  jack_port_untie (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
715
716 /**
717  * Modify a port's short name.  May be called at any time.  If the
718  * resulting full name (including the @a "client_name:" prefix) is
719  * longer than jack_port_name_size(), it will be truncated.
720  *
721  * @return 0 on success, otherwise a non-zero error code.
722  */
723 int jack_port_set_name (jack_port_t *port, const char *port_name) JACK_OPTIONAL_WEAK_EXPORT;
724
725 /**
726  * Set @a alias as an alias for @a port.  May be called at any time.
727  * If the alias is longer than jack_port_name_size(), it will be truncated.
728  *
729  * After a successful call, and until JACK exits or
730  * jack_port_unset_alias() is called, may be
731  * used as a alternate name for the port.
732  *
733  * Ports can have up to two aliases - if both are already
734  * set, this function will return an error.
735  *
736  * @return 0 on success, otherwise a non-zero error code.
737  */
738 int jack_port_set_alias (jack_port_t *port, const char *alias) JACK_OPTIONAL_WEAK_EXPORT;
739
740 /**
741  * Remove @a alias as an alias for @a port.  May be called at any time.
742  *
743  * After a successful call, @a alias can no longer be
744  * used as a alternate name for the port.
745  *
746  * @return 0 on success, otherwise a non-zero error code.
747  */
748 int jack_port_unset_alias (jack_port_t *port, const char *alias) JACK_OPTIONAL_WEAK_EXPORT;
749
750 /*
751  * Get any aliases known for @port.
752  *
753  * @return the number of aliases discovered for the port
754  */
755 int jack_port_get_aliases (const jack_port_t *port, char* const aliases[2]) JACK_OPTIONAL_WEAK_EXPORT;
756
757 /**
758  * If @ref JackPortCanMonitor is set for this @a port, turn input
759  * monitoring on or off.  Otherwise, do nothing.
760  */
761 int jack_port_request_monitor (jack_port_t *port, int onoff) JACK_OPTIONAL_WEAK_EXPORT;
762
763 /**
764  * If @ref JackPortCanMonitor is set for this @a port_name, turn input
765  * monitoring on or off.  Otherwise, do nothing.
766  *
767  * @return 0 on success, otherwise a non-zero error code.
768  *
769  * @see jack_port_name_size()
770  */
771 int jack_port_request_monitor_by_name (jack_client_t *client,
772                                        const char *port_name, int onoff) JACK_OPTIONAL_WEAK_EXPORT;
773
774 /**
775  * If @ref JackPortCanMonitor is set for a port, this function turns
776  * on input monitoring if it was off, and turns it off if only one
777  * request has been made to turn it on.  Otherwise it does nothing.
778  *
779  * @return 0 on success, otherwise a non-zero error code
780  */
781 int jack_port_ensure_monitor (jack_port_t *port, int onoff) JACK_OPTIONAL_WEAK_EXPORT;
782
783 /**
784  * @return TRUE if input monitoring has been requested for @a port.
785  */
786 int jack_port_monitoring_input (jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT;
787
788 /**
789  * Establish a connection between two ports.
790  *
791  * When a connection exists, data written to the source port will
792  * be available to be read at the destination port.
793  *
794  * @pre The port types must be identical.
795  *
796  * @pre The @ref JackPortFlags of the @a source_port must include @ref
797  * JackPortIsOutput.
798  *
799  * @pre The @ref JackPortFlags of the @a destination_port must include
800  * @ref JackPortIsInput.
801  *
802  * @return 0 on success, EEXIST if the connection is already made,
803  * otherwise a non-zero error code
804  */
805 int jack_connect (jack_client_t *,
806                   const char *source_port,
807                   const char *destination_port) JACK_OPTIONAL_WEAK_EXPORT;
808
809 /**
810  * Remove a connection between two ports.
811  *
812  * @pre The port types must be identical.
813  *
814  * @pre The @ref JackPortFlags of the @a source_port must include @ref
815  * JackPortIsOutput.
816  *
817  * @pre The @ref JackPortFlags of the @a destination_port must include
818  * @ref JackPortIsInput.
819  *
820  * @return 0 on success, otherwise a non-zero error code
821  */
822 int jack_disconnect (jack_client_t *,
823                      const char *source_port,
824                      const char *destination_port) JACK_OPTIONAL_WEAK_EXPORT;
825
826 /**
827  * Perform the same function as jack_disconnect() using port handles
828  * rather than names.  This avoids the name lookup inherent in the
829  * name-based version.
830  *
831  * Clients connecting their own ports are likely to use this function,
832  * while generic connection clients (e.g. patchbays) would use
833  * jack_disconnect().
834  */
835 int jack_port_disconnect (jack_client_t *, jack_port_t *) JACK_OPTIONAL_WEAK_EXPORT;
836
837 /**
838  * @return the maximum number of characters in a full JACK port name
839  * including the final NULL character.  This value is a constant.
840  *
841  * A port's full name contains the owning client name concatenated
842  * with a colon (:) followed by its short name and a NULL
843  * character.
844  */
845 int jack_port_name_size(void) JACK_OPTIONAL_WEAK_EXPORT;
846
847 /**
848  * @return the maximum number of characters in a JACK port type name
849  * including the final NULL character.  This value is a constant.
850  */
851 int jack_port_type_size(void) JACK_OPTIONAL_WEAK_EXPORT;
852
853 /**
854  * @return the buffersize of a port of type @arg port_type.
855  *
856  * this function may only be called in a buffer_size callback.
857  */
858 size_t jack_port_type_get_buffer_size (jack_client_t *client, const char *port_type) JACK_WEAK_EXPORT;
859
860 /*@}*/
861
862 /**
863  * @defgroup LatencyFunctions Managing and determining latency
864  *
865  * The purpose of JACK's latency API is to allow clients to
866  * easily answer two questions:
867  *
868  * - How long has it been since the data read from a port arrived
869  *   at the edge of the JACK graph (either via a physical port
870  *   or being synthesized from scratch)?
871  *
872  * - How long will it be before the data written to a port arrives
873  *   at the edge of a JACK graph?
874
875  * To help answering these two questions, all JACK ports have two
876  * latency values associated with them, both measured in frames:
877  *
878  * <b>capture latency</b>: how long since the data read from
879  *                  the buffer of a port arrived at at
880  *                  a port marked with JackPortIsTerminal.
881  *                  The data will have come from the "outside
882  *                  world" if the terminal port is also
883  *                  marked with JackPortIsPhysical, or
884  *                  will have been synthesized by the client
885  *                  that owns the terminal port.
886  *                 
887  * <b>playback latency</b>: how long until the data
888  *                   written to the buffer of port will reach a port
889  *                   marked with JackPortIsTerminal.
890  *
891  * Both latencies might potentially have more than one value
892  * because there may be multiple pathways to/from a given port
893  * and a terminal port. Latency is therefore generally
894  * expressed a min/max pair.
895  *
896  * In most common setups, the minimum and maximum latency
897  * are the same, but this design accomodates more complex
898  * routing, and allows applications (and thus users) to
899  * detect cases where routing is creating an anomalous
900  * situation that may either need fixing or more
901  * sophisticated handling by clients that care about
902  * latency.
903  *
904  * See also @ref jack_set_latency_callback for details on how
905  * clients that add latency to the signal path should interact
906  * with JACK to ensure that the correct latency figures are
907  * used.
908  * @{
909  */
910
911 /**
912  * The port latency is zero by default. Clients that control
913  * physical hardware with non-zero latency should call this
914  * to set the latency to its correct value. Note that the value
915  * should include any systemic latency present "outside" the
916  * physical hardware controlled by the client. For example,
917  * for a client controlling a digital audio interface connected
918  * to an external digital converter, the latency setting should
919  * include both buffering by the audio interface *and* the converter.
920  *
921  * @deprecated This method will be removed in the next major
922  * release of JACK. It should not be used in new code, and should
923  * be replaced by a latency callback that calls @ref
924  * jack_port_set_latency_range().
925  */
926 void jack_port_set_latency (jack_port_t *, jack_nframes_t) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
927        
928 /**
929  * return the latency range defined by @a mode for
930  * @a port, in frames.
931  * 
932  * See @ref LatencyFunctions for the definition of each latency value.
933  *
934  * This is normally used in the LatencyCallback.
935  * and therefor safe to execute from callbacks.
936  */
937 void jack_port_get_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT;
938
939 /**
940  * set the minimum and maximum latencies defined by
941  * @a mode for @a port, in frames.
942  * 
943  * See @ref LatencyFunctions for the definition of each latency value.
944  *
945  * This function should ONLY be used inside a latency
946  * callback. The client should determine the current
947  * value of the latency using @ref jack_port_get_latency_range()
948  * (called using the same mode as @a mode)
949  * and then add some number of frames to that reflects
950  * latency added by the client.
951  *
952  * How much latency a client adds will vary
953  * dramatically. For most clients, the answer is zero
954  * and there is no reason for them to register a latency
955  * callback and thus they should never call this
956  * function.
957  *
958  * More complex clients that take an input signal,
959  * transform it in some way and output the result but
960  * not during the same process() callback will
961  * generally know a single constant value to add
962  * to the value returned by @ref jack_port_get_latency_range().
963  *
964  * Such clients would register a latency callback (see
965  * @ref jack_set_latency_callback) and must know what input
966  * ports feed which output ports as part of their
967  * internal state. Their latency callback will update
968  * the ports' latency values appropriately.
969  *
970  * A pseudo-code example will help. The @a mode argument to the latency
971  * callback will determine whether playback or capture
972  * latency is being set. The callback will use
973  * @ref jack_port_set_latency_range() as follows:
974  *
975  * \code
976  * jack_latency_range_t range;
977  * if (mode == JackPlaybackLatency) {
978  *  foreach input_port in (all self-registered port) {
979  *   jack_port_get_latency_range (port_feeding_input_port, JackPlaybackLatency, &range);
980  *   range.min += min_delay_added_as_signal_flows_from port_feeding to input_port;
981  *   range.max += max_delay_added_as_signal_flows_from port_feeding to input_port;
982  *   jack_port_set_latency_range (input_port, JackPlaybackLatency, &range);
983  *  }
984  * } else if (mode == JackCaptureLatency) {
985  *  foreach output_port in (all self-registered port) {
986  *   jack_port_get_latency_range (port_fed_by_output_port, JackCaptureLatency, &range);
987  *   range.min += min_delay_added_as_signal_flows_from_output_port_to_fed_by_port;
988  *   range.max += max_delay_added_as_signal_flows_from_output_port_to_fed_by_port;
989  *   jack_port_set_latency_range (output_port, JackCaptureLatency, &range);
990  *  }
991  * }
992  * \endcode
993  *
994  * In this relatively simple pseudo-code example, it is assumed that
995  * each input port or output is connected to only 1 output or input
996  * port respectively.
997  *
998  * If a port is connected to more than 1 other port, then the
999  * range.min and range.max values passed to @ref
1000  * jack_port_set_latency_range() should reflect the minimum and
1001  * maximum values across all connected ports.
1002  *
1003  * See the description of @ref jack_set_latency_callback for more
1004  * information.
1005  */
1006 void jack_port_set_latency_range (jack_port_t *port, jack_latency_callback_mode_t mode, jack_latency_range_t *range) JACK_WEAK_EXPORT;
1007
1008 /**
1009  * Request a complete recomputation of all port latencies. This
1010  * can be called by a client that has just changed the internal
1011  * latency of its port using  jack_port_set_latency
1012  * and wants to ensure that all signal pathways in the graph
1013  * are updated with respect to the values that will be returned
1014  * by  jack_port_get_total_latency. It allows a client
1015  * to change multiple port latencies without triggering a
1016  * recompute for each change.
1017  *
1018  * @return zero for successful execution of the request. non-zero
1019  *         otherwise.
1020  */
1021 int jack_recompute_total_latencies (jack_client_t*) JACK_OPTIONAL_WEAK_EXPORT;
1022
1023 /**
1024  * @return the time (in frames) between data being available or
1025  * delivered at/to a port, and the time at which it arrived at or is
1026  * delivered to the "other side" of the port.  E.g. for a physical
1027  * audio output port, this is the time between writing to the port and
1028  * when the signal will leave the connector.  For a physical audio
1029  * input port, this is the time between the sound arriving at the
1030  * connector and the corresponding frames being readable from the
1031  * port.
1032  *
1033  * @deprecated This method will be removed in the next major
1034  * release of JACK. It should not be used in new code, and should
1035  * be replaced by jack_port_get_latency_range() in any existing
1036  * use cases.
1037  */
1038 jack_nframes_t jack_port_get_latency (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
1039
1040 /**
1041  * The maximum of the sum of the latencies in every
1042  * connection path that can be drawn between the port and other
1043  * ports with the @ref JackPortIsTerminal flag set.
1044  *
1045  * @deprecated This method will be removed in the next major
1046  * release of JACK. It should not be used in new code, and should
1047  * be replaced by jack_port_get_latency_range() in any existing
1048  * use cases.
1049  */
1050 jack_nframes_t jack_port_get_total_latency (jack_client_t *,
1051                                             jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
1052
1053 /**
1054  * Request a complete recomputation of a port's total latency. This
1055  * can be called by a client that has just changed the internal
1056  * latency of its port using  jack_port_set_latency
1057  * and wants to ensure that all signal pathways in the graph
1058  * are updated with respect to the values that will be returned
1059  * by  jack_port_get_total_latency.
1060  *
1061  * @return zero for successful execution of the request. non-zero
1062  *         otherwise.
1063  *
1064  * @deprecated This method will be removed in the next major
1065  * release of JACK. It should not be used in new code, and should
1066  * be replaced by jack_recompute_total_latencies() in any existing
1067  * use cases.
1068  */
1069 int jack_recompute_total_latency (jack_client_t*, jack_port_t* port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT;
1070
1071 /*@}*/
1072
1073 /**
1074  * @defgroup PortSearching Looking up ports
1075  * @{
1076  */
1077
1078 /**
1079  * @param port_name_pattern A regular expression used to select
1080  * ports by name.  If NULL or of zero length, no selection based
1081  * on name will be carried out.
1082  * @param type_name_pattern A regular expression used to select
1083  * ports by type.  If NULL or of zero length, no selection based
1084  * on type will be carried out.
1085  * @param flags A value used to select ports by their flags. 
1086  * If zero, no selection based on flags will be carried out.
1087  *
1088  * @return a NULL-terminated array of ports that match the specified
1089  * arguments.  The caller is responsible for calling jack_free(3) any
1090  * non-NULL returned value.
1091  *
1092  * @see jack_port_name_size(), jack_port_type_size()
1093  */
1094 const char **jack_get_ports (jack_client_t *,
1095                              const char *port_name_pattern,
1096                              const char *type_name_pattern,
1097                              unsigned long flags) JACK_OPTIONAL_WEAK_EXPORT;
1098
1099 /**
1100  * @return address of the jack_port_t named @a port_name.
1101  *
1102  * @see jack_port_name_size()
1103  */
1104 jack_port_t *jack_port_by_name (jack_client_t *, const char *port_name) JACK_OPTIONAL_WEAK_EXPORT;
1105
1106 /**
1107  * @return address of the jack_port_t of a @a port_id.
1108  */
1109 jack_port_t *jack_port_by_id (jack_client_t *client,
1110                               jack_port_id_t port_id) JACK_OPTIONAL_WEAK_EXPORT;
1111
1112 /*@}*/
1113
1114
1115 /**
1116  * @defgroup TimeFunctions Handling time
1117  * @{
1118  *
1119  * JACK time is in units of 'frames', according to the current sample rate.
1120  * The absolute value of frame times is meaningless, frame times have meaning
1121  * only relative to each other.
1122  */
1123
1124 /**
1125  * @return the estimated time in frames that has passed since the JACK
1126  * server began the current process cycle.
1127  */
1128 jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT;
1129
1130 /**
1131  * @return the estimated current time in frames.
1132  * This function is intended for use in other threads (not the process
1133  * callback).  The return value can be compared with the value of
1134  * jack_last_frame_time to relate time in other threads to JACK time.
1135  */
1136 jack_nframes_t jack_frame_time (const jack_client_t *) JACK_OPTIONAL_WEAK_EXPORT;
1137
1138 /**
1139  * @return the precise time at the start of the current process cycle.
1140  * This function may only be used from the process callback, and can
1141  * be used to interpret timestamps generated by jack_frame_time() in
1142  * other threads with respect to the current process cycle.
1143  *
1144  * This is the only jack time function that returns exact time:
1145  * when used during the process callback it always returns the same
1146  * value (until the next process callback, where it will return
1147  * that value + nframes, etc).  The return value is guaranteed to be
1148  * monotonic and linear in this fashion unless an xrun occurs.
1149  * If an xrun occurs, clients must check this value again, as time
1150  * may have advanced in a non-linear way (e.g. cycles may have been skipped).
1151  */
1152 jack_nframes_t jack_last_frame_time (const jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT;
1153
1154 /**
1155  * @return the estimated time in microseconds of the specified frame time
1156  */
1157 jack_time_t jack_frames_to_time(const jack_client_t *client, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT;
1158
1159 /**
1160  * @return the estimated time in frames for the specified system time.
1161  */
1162 jack_nframes_t jack_time_to_frames(const jack_client_t *client, jack_time_t) JACK_OPTIONAL_WEAK_EXPORT;
1163
1164 /**
1165  * @return return JACK's current system time in microseconds,
1166  *         using the JACK clock source.
1167  *
1168  * The value returned is guaranteed to be monotonic, but not linear.
1169  */
1170 jack_time_t jack_get_time() JACK_OPTIONAL_WEAK_EXPORT;
1171
1172 /*@}*/
1173
1174 /**
1175  * @defgroup ErrorOutput Controlling error/information output
1176  */
1177 /*@{*/
1178
1179 /**
1180  * Display JACK error message.
1181  *
1182  * Set via jack_set_error_function(), otherwise a JACK-provided
1183  * default will print @a msg (plus a newline) to stderr.
1184  *
1185  * @param msg error message text (no newline at end).
1186  */
1187 extern void (*jack_error_callback)(const char *msg) JACK_OPTIONAL_WEAK_EXPORT;
1188
1189 /**
1190  * Set the @ref jack_error_callback for error message display.
1191  *
1192  * The JACK library provides two built-in callbacks for this purpose:
1193  * default_jack_error_callback() and silent_jack_error_callback().
1194  */
1195 void jack_set_error_function (void (*func)(const char *)) JACK_OPTIONAL_WEAK_EXPORT;
1196
1197 /**
1198  * Display JACK info message.
1199  *
1200  * Set via jack_set_info_function(), otherwise a JACK-provided
1201  * default will print @a msg (plus a newline) to stdout.
1202  *
1203  * @param msg info message text (no newline at end).
1204  */
1205 extern void (*jack_info_callback)(const char *msg) JACK_OPTIONAL_WEAK_EXPORT;
1206
1207 /**
1208  * Set the @ref jack_info_callback for info message display.
1209  */
1210 void jack_set_info_function (void (*func)(const char *)) JACK_OPTIONAL_WEAK_EXPORT;
1211 /*@}*/
1212
1213 /**
1214  * The free function to be used on memory returned by jack_port_get_connections,
1215  * jack_port_get_all_connections and jack_get_ports functions.
1216  * This is MANDATORY on Windows when otherwise all nasty runtime version related crashes can occur.
1217  * Developers are strongly encouraged to use this function instead of the standard "free" function in new code.
1218  *
1219  */
1220 void jack_free(void* ptr) JACK_OPTIONAL_WEAK_EXPORT;
1221
1222 #ifdef __cplusplus
1223 }
1224 #endif
1225
1226 #endif /* __jack_h__ */
Note: See TracBrowser for help on using the browser.