jack.h File Reference

#include <pthread.h>
#include <jack/types.h>
#include <jack/transport.h>

Go to the source code of this file.

Functions

jack_client_tjack_client_new (const char *client_name)
int jack_client_close (jack_client_t *client)
int jack_internal_client_new (const char *client_name, const char *so_name, const char *so_data)
void jack_internal_client_close (const char *client_name)
int jack_is_realtime (jack_client_t *client)
void jack_on_shutdown (jack_client_t *client, void(*function)(void *arg), void *arg)
int jack_set_process_callback (jack_client_t *client, JackProcessCallback process_callback, void *arg)
int jack_set_freewheel_callback (jack_client_t *client, JackFreewheelCallback freewheel_callback, void *arg)
int jack_set_freewheel (jack_client_t *client, int onoff)
int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes)
int jack_set_buffer_size_callback (jack_client_t *client, JackBufferSizeCallback bufsize_callback, void *arg)
int jack_set_sample_rate_callback (jack_client_t *client, JackSampleRateCallback srate_callback, void *arg)
int jack_set_port_registration_callback (jack_client_t *, JackPortRegistrationCallback registration_callback, void *arg)
int jack_set_graph_order_callback (jack_client_t *, JackGraphOrderCallback graph_callback, void *)
int jack_set_xrun_callback (jack_client_t *, JackXRunCallback xrun_callback, void *arg)
int jack_activate (jack_client_t *client)
int jack_deactivate (jack_client_t *client)
jack_port_tjack_port_register (jack_client_t *, const char *port_name, const char *port_type, unsigned long flags, unsigned long buffer_size)
int jack_port_unregister (jack_client_t *, jack_port_t *)
void * jack_port_get_buffer (jack_port_t *, jack_nframes_t)
const char * jack_port_name (const jack_port_t *port)
const char * jack_port_short_name (const jack_port_t *port)
int jack_port_flags (const jack_port_t *port)
const char * jack_port_type (const jack_port_t *port)
int jack_port_is_mine (const jack_client_t *, const jack_port_t *port)
int jack_port_connected (const jack_port_t *port)
int jack_port_connected_to (const jack_port_t *port, const char *portname)
const char ** jack_port_get_connections (const jack_port_t *port)
const char ** jack_port_get_all_connections (const jack_client_t *client, const jack_port_t *port)
int jack_port_tie (jack_port_t *src, jack_port_t *dst)
int jack_port_untie (jack_port_t *port)
int jack_port_lock (jack_client_t *, jack_port_t *)
int jack_port_unlock (jack_client_t *, jack_port_t *)
jack_nframes_t jack_port_get_latency (jack_port_t *port)
jack_nframes_t jack_port_get_total_latency (jack_client_t *, jack_port_t *port)
void jack_port_set_latency (jack_port_t *, jack_nframes_t)
int jack_port_set_name (jack_port_t *port, const char *name)
int jack_port_request_monitor (jack_port_t *port, int onoff)
int jack_port_request_monitor_by_name (jack_client_t *client, const char *port_name, int onoff)
int jack_port_ensure_monitor (jack_port_t *port, int onoff)
int jack_port_monitoring_input (jack_port_t *port)
int jack_connect (jack_client_t *, const char *source_port, const char *destination_port)
int jack_disconnect (jack_client_t *, const char *source_port, const char *destination_port)
int jack_port_connect (jack_client_t *, jack_port_t *src, jack_port_t *dst)
int jack_port_disconnect (jack_client_t *, jack_port_t *)
jack_nframes_t jack_get_sample_rate (jack_client_t *)
jack_nframes_t jack_get_buffer_size (jack_client_t *)
const char ** jack_get_ports (jack_client_t *, const char *port_name_pattern, const char *type_name_pattern, unsigned long flags)
jack_port_tjack_port_by_name (jack_client_t *, const char *portname)
jack_port_tjack_port_by_id (const jack_client_t *client, jack_port_id_t id)
int jack_engine_takeover_timebase (jack_client_t *)
jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *)
jack_nframes_t jack_frame_time (const jack_client_t *)
float jack_cpu_load (jack_client_t *client)
void jack_set_server_dir (const char *path)
pthread_t jack_client_thread_id (jack_client_t *)
void jack_set_error_function (void(*func)(const char *))

Variables

void(* jack_error_callback )(const char *msg)


Function Documentation

int jack_activate jack_client_t client  ) 
 

Tell the Jack server that the program is ready to start processing audio.

Returns:
0 on success, otherwise a non-zero error code

int jack_client_close jack_client_t client  ) 
 

Disconnects an external client from a JACK server.

Returns:
0 on success, otherwise a non-zero error code

jack_client_t* jack_client_new const char *  client_name  ) 
 

Attempts to become an external client of the Jack server.

Returns:
opaque client handle if successful, otherwise NULL.
Note: failure generally means that the JACK server is not running. If there was some other problem, it will be reported via the jack_error_callback mechanism.

pthread_t jack_client_thread_id jack_client_t  ) 
 

Return the pthread ID of the thread running the JACK client side code.

int jack_connect jack_client_t ,
const char *  source_port,
const char *  destination_port
 

Establishes a connection between two ports.

When a connection exists, data written to the source port will be available to be read at the destination port.

Precondition:
The types of both ports must be identical to establish a connection.

The flags of the source port must include PortIsOutput.

The flags of the destination port must include PortIsInput.

Returns:
0 on success, EEXIST if the connection is allready made, otherwise a non-zero error code

float jack_cpu_load jack_client_t client  ) 
 

This returns the current CPU load estimated by JACK as a percentage. The load is computed by measuring the amount of time it took to execute all clients as a fraction of the total amount of time represented by the data that was processed.

int jack_deactivate jack_client_t client  ) 
 

Tells the Jack server that the program should be removed from the processing graph. As a side effect, this will disconnect any and all ports belonging to the client, since inactive clients are not allowed to be connected to any other ports.

Returns:
0 on success, otherwise a non-zero error code

int jack_disconnect jack_client_t ,
const char *  source_port,
const char *  destination_port
 

Removes a connection between two ports.

Precondition:
The types of both ports must be identical to establish a connection.

The flags of the source port must include PortIsOutput.

The flags of the destination port must include PortIsInput.

Returns:
0 on success, otherwise a non-zero error code

int jack_engine_takeover_timebase jack_client_t  ) 
 

Old-style interface to become the timebase for the entire JACK subsystem.

Deprecated:
This function still exists for compatibility with the earlier transport interface, but it does nothing. Instead, see <jack/transport.h> and use jack_set_timebase_callback().
Returns:
ENOSYS, function not implemented.

jack_nframes_t jack_frame_time const jack_client_t  ) 
 

Return an estimate of the current time in frames. It is a running counter - no significance should be attached to the return value. it should be used to compute the difference between a previously returned value.

jack_nframes_t jack_frames_since_cycle_start const jack_client_t  ) 
 

This estimates the time that has passed since the JACK server started calling the process callbacks of all its clients.

jack_nframes_t jack_get_buffer_size jack_client_t  ) 
 

This returns the current maximum size that will ever be passed to the process_callback. It should only be used *before* the client has been activated. This size may change, clients that depend on it must register a bufsize_callback so they will be notified if it does.

See also:
jack_set_buffer_size_callback()

const char** jack_get_ports jack_client_t ,
const char *  port_name_pattern,
const char *  type_name_pattern,
unsigned long  flags
 

Parameters:
port_name_pattern A regular expression used to select ports by name. If NULL or of zero length, no selection based on name will be carried out.
type_name_pattern A regular expression used to select ports by type. If NULL or of zero length, no selection based on type will be carried out.
flags A value used to select ports by their flags. If zero, no selection based on flags will be carried out.
This function returns a NULL-terminated array of ports that match the specified arguments. The caller is responsible for calling free(3) any non-NULL returned value.

jack_nframes_t jack_get_sample_rate jack_client_t  ) 
 

This returns the sample rate of the jack system, as set by the user when jackd was started.

void jack_internal_client_close const char *  client_name  ) 
 

Removes an internal client from a JACK server.

Returns:
0 on success, otherwise a non-zero error code

int jack_internal_client_new const char *  client_name,
const char *  so_name,
const char *  so_data
 

Parameters:
client_name The name for the new client
so_name A path to a shared object file containing the code for the new client
so_data An arbitary string containing information to be passed to the init() routine of the new client
Attemps to load an internal client into the Jack server.

int jack_is_realtime jack_client_t client  ) 
 

Parameters:
client The Jack client structure.
Check if the JACK subsystem is running with -R (--realtime).

Returns:
1 if JACK is running realtime, 0 otherwise

void jack_on_shutdown jack_client_t client,
void(*  function)(void *arg),
void *  arg
 

Parameters:
client The Jack client structure.
function The jack_shutdown function pointer.
arg The arguments for the jack_shutdown function.
Register a function (and argument) to be called if and when the JACK server shuts down the client thread. The function must be written as if it were an asynchonrous POSIX signal handler --- use only async-safe functions, and remember that it is executed from another thread. A typical function might set a flag or write to a pipe so that the rest of the application knows that the JACK client thread has shut down.

NOTE: clients do not need to call this. It exists only to help more complex clients understand what is going on. It should be called before jack_client_activate().

jack_port_t* jack_port_by_id const jack_client_t client,
jack_port_id_t  id
 

Searchs for and returns the jack_port_t of id 'id'.

jack_port_t* jack_port_by_name jack_client_t ,
const char *  portname
 

Searchs for and returns the jack_port_t with the name value from portname.

int jack_port_connect jack_client_t ,
jack_port_t src,
jack_port_t dst
 

Performs the exact same function as jack_connect(), but it uses port handles rather than names, which avoids the name lookup inherent in the name-based version.

It is envisaged that clients connecting their own ports will use these two, whereas generic connection clients (e.g. patchbays) will use the name-based versions.

Returns:
0 on success, otherwise a non-zero error code

int jack_port_connected const jack_port_t port  ) 
 

This returns a positive integer indicating the number of connections to or from 'port'.

Ūpre The calling client must own 'port'.

int jack_port_connected_to const jack_port_t port,
const char *  portname
 

This returns TRUE or FALSE if the port argument is DIRECTLY connected to the port with the name given in 'portname'

Precondition:
The calling client must own 'port'.

int jack_port_disconnect jack_client_t ,
jack_port_t
 

Performs the exact same function as jack_disconnect(), but it uses port handles rather than names, which avoids the name lookup inherent in the name-based version.

It is envisaged that clients disconnecting their own ports will use these two, whereas generic connection clients (e.g. patchbays) will use the name-based versions.

int jack_port_ensure_monitor jack_port_t port,
int  onoff
 

If JackPortCanMonitor is set for a port, then this function will turn on input monitoring if it was off, and will turn it off it only one request has been made to turn it on. If JackPortCanMonitor is not set, then this function will do nothing.

Returns:
0 on success, otherwise a non-zero error code

int jack_port_flags const jack_port_t port  ) 
 

Returns the flags of the jack_port_t.

const char** jack_port_get_all_connections const jack_client_t client,
const jack_port_t port
 

This returns a null-terminated array of port names to which the argument port is connected. if there are no connections, it returns NULL.

The caller is responsible for calling free(3) on any non-NULL returned value.

It differs from jack_port_get_connections() in two important respects:

1) You may not call this function from code that is executed in response to a JACK event. For example, you cannot use it in a GraphReordered handler.

2) You need not be the owner of the port to get information about its connections.

void* jack_port_get_buffer jack_port_t ,
jack_nframes_t 
 

This returns a pointer to the memory area associated with the specified port. For an output port, it will be a memory area that can be written to; for an input port, it will be an area containing the data from the port's connection(s), or zero-filled. if there are multiple inbound connections, the data will be mixed appropriately.

FOR OUTPUT PORTS ONLY --------------------- You may cache the value returned, but only between calls to your "blocksize" callback. For this reason alone, you should either never cache the return value or ensure you have a "blocksize" callback and be sure to invalidate the cached address from there.

const char** jack_port_get_connections const jack_port_t port  ) 
 

This returns a null-terminated array of port names to which the argument port is connected. if there are no connections, it returns NULL.

The caller is responsible for calling free(3) on any non-NULL returned value.

Precondition:
The calling client must own 'port'.
See jack_port_get_all_connections() for an alternative.

jack_nframes_t jack_port_get_latency jack_port_t port  ) 
 

Returns the time (in frames) between data being available or delivered at/to a port, and the time at which it arrived at or is delivered to the "other side" of the port. E.g. for a physical audio output port, this is the time between writing to the port and when the signal will leave the connector. For a physical audio input port, this is the time between the sound arriving at the connector and the corresponding frames being readable from the port.

jack_nframes_t jack_port_get_total_latency jack_client_t ,
jack_port_t port
 

The maximum of the sum of the latencies in every connection path that can be drawn between the port and other ports with the JackPortIsTerminal flag set.

int jack_port_is_mine const jack_client_t ,
const jack_port_t port
 

Returns 1 if the jack_port_t belongs to the jack_client_t.

int jack_port_lock jack_client_t ,
jack_port_t
 

A client may call this function to prevent other objects from changing the connection status of a port. The port must be owned by the calling client.

Returns:
0 on success, otherwise a non-zero error code

int jack_port_monitoring_input jack_port_t port  ) 
 

Returns a true or false value depending on whether or not input monitoring has been requested for 'port'.

const char* jack_port_name const jack_port_t port  ) 
 

Returns the name of the jack_port_t.

jack_port_t* jack_port_register jack_client_t ,
const char *  port_name,
const char *  port_type,
unsigned long  flags,
unsigned long  buffer_size
 

This creates a new port for the client.

A port is an object used for moving data in or out of the client. the data may be of any type. Ports may be connected to each other in various ways.

A port has a short name, a non-NULL and non-zero length string, and is passed as the first argument. A port's full name is the name of the client concatenated with a colon (:) and then its short name. There are limits to the length of the name, and exceeding them will cause registration of the port to fail and the function to return NULL. The limit is derived from the size of a full port name, which also has to include the client name and a separator character.

A port has a type, which may be any non-NULL and non-zero length string, and is passed as the second argument. Some port types are built into the JACK API (currently only JACK_DEFAULT_AUDIO_TYPE). For other types, the client must supply a non-zero buffer_size. For builtin types, buffer_size is ignored.

The flags argument is formed from a bitmask of JackPortFlags values.

Returns:
a valid jack_port_t* on success, NULL otherwise.

int jack_port_request_monitor jack_port_t port,
int  onoff
 

If JackPortCanMonitor is set for a port, then these 2 functions will turn on/off input monitoring for the port. If JackPortCanMonitor is not set, then these functions will have no effect.

int jack_port_request_monitor_by_name jack_client_t client,
const char *  port_name,
int  onoff
 

If JackPortCanMonitor is set for a port, then these 2 functions will turn on/off input monitoring for the port. If JackPortCanMonitor is not set, then these functions will have no effect.

Returns:
0 on success, otherwise a non-zero error code

void jack_port_set_latency jack_port_t ,
jack_nframes_t 
 

The port latency is zero by default. Clients that control physical hardware with non-zero latency should call this to set the latency to its correct value. Note that the value should include any systemic latency present "outside" the physical hardware controlled by the client. For example, for a client controlling a digital audio interface connected to an external digital converter, the latency setting should include both buffering by the audio interface *and* the converter.

int jack_port_set_name jack_port_t port,
const char *  name
 

This modifies a port's name, and may be called at any time.

Returns:
0 on success, otherwise a non-zero error code

const char* jack_port_short_name const jack_port_t port  ) 
 

Returns the short name of the jack_port_t.

int jack_port_tie jack_port_t src,
jack_port_t dst
 

A client may call this on a pair of its own ports to semi-permanently wire them together. This means that a client that wants to direct-wire an input port to an output port can call this and then no longer have to worry about moving data between them. Any data arriving at the input port will appear automatically at the output port.

The 'destination' port must be an output port. The 'source' port must be an input port. Both ports must belong to the same client. You cannot use this to tie ports between clients. That is what a connection is for.

Returns:
0 on success, otherwise a non-zero error code

const char* jack_port_type const jack_port_t port  ) 
 

Returns the type of the jack_port_t.

int jack_port_unlock jack_client_t ,
jack_port_t
 

This allows other objects to change the connection status of a port.

Returns:
0 on success, otherwise a non-zero error code

int jack_port_unregister jack_client_t ,
jack_port_t
 

This removes the port from the client, disconnecting any existing connections at the same time.

Returns:
0 on success, otherwise a non-zero error code

int jack_port_untie jack_port_t port  ) 
 

This undoes the effect of jack_port_tie(). The port should be same as the 'destination' port passed to jack_port_tie().

Returns:
0 on success, otherwise a non-zero error code

int jack_set_buffer_size jack_client_t client,
jack_nframes_t  nframes
 

Change the buffer size passed to the process_callback.

This operation stops the JACK engine process cycle, then calls all registered bufsize_callback functions before restarting the process cycle. This will cause a gap in the audio flow, so it should only be done at appropriate stopping points.

See also:
jack_set_buffer_size_callback()
Parameters:
client pointer to JACK client structure.
nframes new buffer size. Must be a power of two.
Returns:
0 on success, otherwise a non-zero error code

int jack_set_buffer_size_callback jack_client_t client,
JackBufferSizeCallback  bufsize_callback,
void *  arg
 

Tell JACK to call bufsize_callback whenever the size of the the buffer that will be passed to the process_callback is about to change. Clients that depend on knowing the buffer size must supply a bufsize_callback before activating themselves.

Parameters:
client pointer to JACK client structure.
bufsize_callback function to call when the buffer size changes.
arg argument for bufsize_callback.
Returns:
0 on success, otherwise a non-zero error code

void jack_set_error_function void(*  func)(const char *)  ) 
 

Set the jack_error_callback for error message display.

The JACK library provides two built-in callbacks for this purpose: default_jack_error_callback() and silent_jack_error_callback().

int jack_set_freewheel jack_client_t client,
int  onoff
 

Start/Stop JACK's "freewheel" mode.

When in "freewheel" mode, JACK no longer waits for any external event to begin the start of the next process cycle.

As a result, freewheel mode causes "faster than realtime" execution of a JACK graph. If possessed, real-time scheduling is dropped when entering freewheel mode, and if appropriate it is reacquired when stopping.

Parameters:
client pointer to JACK client structure
onoff if non-zero, freewheel mode starts. Otherwise freewheel mode ends.
Returns:
0 on success, otherwise a non-zero error code.

int jack_set_freewheel_callback jack_client_t client,
JackFreewheelCallback  freewheel_callback,
void *  arg
 

Tell the Jack server to call freewheel_callback whenever we enter or leave "freewheel" mode, passing arg as the second argument. The first argument to the callback will be non-zero if JACK is entering freewheel mode, and zero otherwise.

Returns:
0 on success, otherwise a non-zero error code.

int jack_set_graph_order_callback jack_client_t ,
JackGraphOrderCallback  graph_callback,
void * 
 

Tell the Jack server to call 'registration_callback' whenever the processing graph is reordered, passing 'arg' as an argument.

Returns:
0 on success, otherwise a non-zero error code

int jack_set_port_registration_callback jack_client_t ,
JackPortRegistrationCallback  registration_callback,
void *  arg
 

Tell the Jack server to call 'registration_callback' whenever a port is registered or unregistered, passing 'arg' as a second argument.

Returns:
0 on success, otherwise a non-zero error code

int jack_set_process_callback jack_client_t client,
JackProcessCallback  process_callback,
void *  arg
 

Tell the Jack server to call process_callback whenever there is work be done, passing arg as the second argument.

The code in the supplied function must be suitable for real-time execution. That means that it cannot call functions that might block for a long time.  This includes malloc, free, printf, pthread_mutex_lock, sleep, wait, poll, select, pthread_join, pthread_cond_wait, etc, etc.  See http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 for more information.

Returns:
0 on success, otherwise a non-zero error code, causing JACK to remove that client from the process() graph.

int jack_set_sample_rate_callback jack_client_t client,
JackSampleRateCallback  srate_callback,
void *  arg
 

Tell the Jack server to call srate_callback whenever the system sample rate changes.

Returns:
0 on success, otherwise a non-zero error code

void jack_set_server_dir const char *  path  ) 
 

Set the directory in which the server is expected to have put its communication FIFOs. A client will need to call this before calling jack_client_new() if the server was started with arguments telling it to use a non-standard directory.

Deprecated:
This function is deprecated. Don't use in new programs and remove it in old programs.

int jack_set_xrun_callback jack_client_t ,
JackXRunCallback  xrun_callback,
void *  arg
 

Tell the Jack server to call 'xrun_callback' whenever there is a xrun, passing 'arg' as an argument.

Returns:
0 on success, otherwise a non-zero error code


Variable Documentation

void(* jack_error_callback)(const char *msg)
 

Function called for displaying JACK error messages.

Set via jack_set_error_function(), otherwise a JACK-provided default will print msg (plus a newline) to stderr.

Parameters:
msg error message text (no newline at end).


Generated on Wed Jan 14 23:42:35 2004 for JACK-AUDIO-CONNECTION-KIT by doxygen 1.3.3