JACK-AUDIO-CONNECTION-KIT: for dealing with ports

# for dealing with ports

## Functions
jack_client_t * | jack_client_open (const char *client_name, jack_options_t options, jack_status_t *status,...)
jack_client_t * | jack_client_new (const char *client_name)
int | jack_client_close (jack_client_t *client)
int | jack_client_name_size (void)
char * | jack_get_client_name (jack_client_t *client)
int | jack_internal_client_new (const char *client_name, const char *load_name, const char *load_init)
void | jack_internal_client_close (const char *client_name)
jack_port_t * | jack_port_register (jack_client_t *client, 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 *port_name)
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)
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_recompute_total_latency (jack_client_t *, jack_port_t *port)
int | jack_recompute_total_latencies (jack_client_t *)
int | jack_port_set_name (jack_port_t *port, const char *port_name)
int | jack_port_set_alias (jack_port_t *port, const char *alias)
int | jack_port_unset_alias (jack_port_t *port, const char *alias)
int | jack_port_get_aliases (const jack_port_t *port, char *const aliases[2])
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_disconnect (jack_client_t *, jack_port_t *)
int | jack_port_name_size (void)
int | jack_port_type_size (void)
void | jack_set_error_function (void(*func)(const char *))
void | jack_set_info_function (void(*func)(const char *))
## Variables
void(* | jack_error_callback )(const char *msg)
void(* | jack_info_callback )(const char *msg)

## Detailed Description

Note: More documentation can be found in jack/types.h.

## Function Documentation

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

Referenced by main().

int jack_client_name_size | ( | void |  | ) |

Returns:
  the maximum number of characters in a JACK client name including the final NULL character. This value is a constant.

jack_client_t* jack_client_new | ( | const char * | client_name | ) |

THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN NEW JACK CLIENTS

jack_client_t* jack_client_open | ( | const char * | client_name,
|  | jack_options_t | options,
|  | jack_status_t * | status,
|  |  | ... |
| ) |  |  |

Open an external client session with a JACK server. This interface is more complex but more powerful than jack_client_new(). With it, clients may choose which of several servers to connect, and control whether and how to start the server automatically, if it was not already running. There is also an option for JACK to generate a unique client name, when necessary.

Parameters:

  | client_name | of at most jack_client_name_size() characters. The name scope is local to each server. Unless forbidden by the JackUseExactName option, the server will modify this name to create a unique variant, if needed.
  | options | formed by OR-ing together JackOptions bits. Only the JackOpenOptions bits are allowed.
  | status | (if non-NULL) an address for JACK to return information from the open operation. This status word is formed by OR-ing together the relevant JackStatus bits.

Optional parameters: depending on corresponding [options bits] additional parameters may follow status (in this order).

- [JackServerName] (char *) server_name selects from among several possible concurrent server instances. Server names are unique to each user. If unspecified, use "default" unless $JACK_DEFAULT_SERVER is defined in the process environment.

Returns:
  Opaque client handle if successful. If this is NULL, the open operation failed, *status includes JackFailure and the caller is not a JACK client.

Referenced by main().

int jack_connect | ( | jack_client_t * | ,
|  | const char * | source_port,
|  | const char * | destination_port |
| ) |  |  |

Establish 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 port types must be identical.

  The JackPortFlags of the source_port must include JackPortIsOutput.

  The JackPortFlags of the destination_port must include JackPortIsInput.

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

Referenced by jack_initialize(), and main().

int jack_disconnect | ( | jack_client_t * | ,
|  | const char * | source_port,
|  | const char * | destination_port |
| ) |  |  |

Remove a connection between two ports.

Precondition:
  The port types must be identical.

  The JackPortFlags of the source_port must include JackPortIsOutput.

  The JackPortFlags of the destination_port must include JackPortIsInput.

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

char* jack_get_client_name | ( | jack_client_t * | client | ) |

Returns:
  pointer to actual client name. This is useful when JackUseExactName is not specified on open and JackNameNotUnique status was returned. In that case, the actual name will differ from the client_name requested.

Referenced by main().

void jack_internal_client_close | ( | const char * | client_name | ) |

Remove an internal client from a JACK server.

Deprecated:
  Please use jack_internal_client_load().

int jack_internal_client_new | ( | const char * | client_name,
|  | const char * | load_name,
|  | const char * | load_init |
| ) |  |  |

Load an internal client into the Jack server.

Internal clients run inside the JACK server process. They can use most of the same functions as external clients. Each internal client must declare jack_initialize() and jack_finish() entry points, called at load and unload times. See inprocess.c for an example of how to write an internal client.

Deprecated:
  Please use jack_internal_client_load().

Parameters:

  | client_name | of at most jack_client_name_size() characters.
  | load_name | of a shared object file containing the code for the new client.
  | load_init | an arbitary string passed to the jack_initialize() routine of the new client (may be NULL).

Returns:
  0 if successful.

int jack_port_connected | ( | const jack_port_t * | port | ) |

Returns:
  number of connections to or from port.

Precondition:
  The calling client must own port.

int jack_port_connected_to | ( | const jack_port_t * | port,
|  | const char * | port_name |
| ) |  |  |

Returns:
  TRUE if the locally-owned port is directly connected to the port_name.

See also:
  jack_port_name_size()

int jack_port_disconnect | ( | jack_client_t * | ,
|  | jack_port_t * |  |
| ) |  |  |

Perform the same function as jack_disconnect() using port handles rather than names. This avoids the name lookup inherent in the name-based version.

Clients connecting their own ports are likely to use this function, while generic connection clients (e.g. patchbays) would use jack_disconnect().

int jack_port_ensure_monitor | ( | jack_port_t * | port,
|  | int | onoff |
| ) |  |  |

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

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

int jack_port_flags | ( | const jack_port_t * | port | ) |

Returns:
  the JackPortFlags of the jack_port_t.

int jack_port_get_aliases | ( | const jack_port_t * | port,
|  | char *const | aliases[2] |
| ) |  |  |

const char** jack_port_get_all_connections | ( | const jack_client_t * | client,
|  | const jack_port_t * | port |
| ) |  |  |

Returns:
  a null-terminated array of full port names to which the port is connected. If none, returns NULL.

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

This 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.

See also:
  jack_port_name_size()

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 : WILL BE DEPRECATED in Jack 2.0 !! --------------------------------------------------------- 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.

Caching output ports is DEPRECATED in Jack 2.0, due to some new optimization (like "pipelining"). Port buffers have to be retrieved in each callback for proper functionning.

Referenced by inprocess(), and process().

const char** jack_port_get_connections | ( | const jack_port_t * | port | ) |

Returns:
  a null-terminated array of full port names to which the port is connected. If none, returns NULL.

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

Parameters:

  | port | locally owned jack_port_t pointer.

See also:
  jack_port_name_size(), jack_port_get_all_connections()

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:
  TRUE if the jack_port_t belongs to the jack_client_t.

int jack_port_monitoring_input | ( | jack_port_t * | port | ) |

Returns:
  TRUE if input monitoring has been requested for port.

const char* jack_port_name | ( | const jack_port_t * | port | ) |

Returns:
  the full name of the jack_port_t (including the "client_name:" prefix).

See also:
  jack_port_name_size().

Referenced by jack_initialize(), and main().

int jack_port_name_size | ( | void |  | ) |

Returns:
  the maximum number of characters in a full JACK port name including the final NULL character. This value is a constant.

A port's full name contains the owning client name concatenated with a colon (:) followed by its short name and a NULL character.

jack_port_t* jack_port_register | ( | jack_client_t * | client,
|  | const char * | port_name,
|  | const char * | port_type,
|  | unsigned long | flags,
|  | unsigned long | buffer_size |
| ) |  |  |

Create a new port for the client. This is an object used for moving data of any type in or out of the client. Ports may be connected in various ways.

Each port has a short name. The port's full name contains the name of the client concatenated with a colon (:) followed by its short name. The jack_port_name_size() is the maximum length of this full name. Exceeding that will cause the port registration to fail and return NULL.

All ports have a type, which may be any non-NULL and non-zero length string, passed as an argument. Some port types are built into the JACK API, like JACK_DEFAULT_AUDIO_TYPE or JACK_DEFAULT_MIDI_TYPE

Parameters:

  | client | pointer to JACK client structure.
  | port_name | non-empty short name for the new port (not including the leading "client_name:").
  | port_type | port type name. If longer than jack_port_type_size(), only that many characters are significant.
  | flags | JackPortFlags bit mask.
  | buffer_size | must be non-zero if this is not a built-in port_type. Otherwise, it is ignored.

Returns:
  jack_port_t pointer on success, otherwise NULL.

Referenced by jack_initialize(), and main().

int jack_port_request_monitor | ( | jack_port_t * | port,
|  | int | onoff |
| ) |  |  |

If JackPortCanMonitor is set for this port, turn input monitoring on or off. Otherwise, do nothing.

int jack_port_request_monitor_by_name | ( | jack_client_t * | client,
|  | const char * | port_name,
|  | int | onoff |
| ) |  |  |

If JackPortCanMonitor is set for this port_name, turn input monitoring on or off. Otherwise, do nothing.

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

See also:
  jack_port_name_size()

int jack_port_set_alias | ( | jack_port_t * | port,
|  | const char * | alias |
| ) |  |  |

Set alias as an alias for port. May be called at any time. If the alias is longer than jack_port_name_size(), it will be truncated.

After a successful call, and until JACK exits or jack_port_unset_alias() is called, may be used as a alternate name for the port.

Ports can have up to two aliases - if both are already set, this function will return an error.

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 * | port_name |
| ) |  |  |

Modify a port's short name. May be called at any time. If the resulting full name (including the "client_name:" prefix) is longer than jack_port_name_size(), it will be truncated.

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 (not including the "client_name:" prefix).

See also:
  jack_port_name_size().

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 port type, at most jack_port_type_size() characters including a final NULL.

int jack_port_type_size | ( | void |  | ) |

Returns:
  the maximum number of characters in a JACK port type name including the final NULL character. This value is a constant.

int jack_port_unregister | ( | jack_client_t * | ,
|  | jack_port_t * |  |
| ) |  |  |

Remove the port from the client, disconnecting any existing connections.

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

int jack_port_unset_alias | ( | jack_port_t * | port,
|  | const char * | alias |
| ) |  |  |

Remove alias as an alias for port. May be called at any time.

After a successful call, alias can no longer be used as a alternate name for the port.

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_recompute_total_latencies | ( | jack_client_t * |  | ) |

Request a complete recomputation of all port latencies. This can be called by a client that has just changed the internal latency of its port using jack_port_set_latency and wants to ensure that all signal pathways in the graph are updated with respect to the values that will be returned by jack_port_get_total_latency. It allows a client to change multiple port latencies without triggering a recompute for each change.

Returns:
  zero for successful execution of the request. non-zero otherwise.

int jack_recompute_total_latency | ( | jack_client_t * | ,
|  | jack_port_t * | port |
| ) |  |  |

Request a complete recomputation of a port's total latency. This can be called by a client that has just changed the internal latency of its port using jack_port_set_latency and wants to ensure that all signal pathways in the graph are updated with respect to the values that will be returned by jack_port_get_total_latency.

Returns:
  zero for successful execution of the request. non-zero otherwise.

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

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().

void jack_set_info_function | ( | void(*)(const char *) | func | ) |

Set the jack_info_callback for info message display.

## Variable Documentation

void(* jack_error_callback)(const char *msg)

Display JACK error message.

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).

void(* jack_info_callback)(const char *msg)

Display JACK info message.

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

Parameters:

  | msg | info message text (no newline at end).