Detailed Description

The most important purpose of functions in this group is to create, destroy and rename audio & MIDI ports for your application and connect them i.e. with ports of other applications.

You will most probably just use two specific types of ports:

32 bit floating point audio port (JACK_DEFAULT_AUDIO_TYPE)
standard MIDI port (JACK_DEFAULT_MIDI_TYPE)

Ports in JACK were designed to be multi-purpose capable though, to i.e. allow using ports also for other audio formats or completely different purpose with the same functions in future.

MIDI support: Due to the design described above, support for MIDI is provided as extension in a separate API part. That is, creation and lookup of MIDI ports is managed by the same functions listed below, but the MIDI aware functions are handled on top of this API part by separate functions in midiport.h.

See Also: Looking up ports

Functions
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) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_unregister (jack_client_t client, jack_port_t port) JACK_OPTIONAL_WEAK_EXPORT
void *	jack_port_get_buffer (jack_port_t *port, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT
const char *	jack_port_name (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
const char *	jack_port_short_name (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_flags (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
const char *	jack_port_type (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
jack_port_type_id_t	jack_port_type_id (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_is_mine (const jack_client_t client, const jack_port_t port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_connected (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_connected_to (const jack_port_t port, const char port_name) JACK_OPTIONAL_WEAK_EXPORT
const char **	jack_port_get_connections (const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
const char **	jack_port_get_all_connections (const jack_client_t client, const jack_port_t port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_tie (jack_port_t src, jack_port_t dst) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
int	jack_port_untie (jack_port_t *port) JACK_OPTIONAL_WEAK_DEPRECATED_EXPORT
int	jack_port_set_name (jack_port_t port, const char port_name) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_set_alias (jack_port_t port, const char alias) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_unset_alias (jack_port_t port, const char alias) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_get_aliases (const jack_port_t port, char const aliases[2]) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_request_monitor (jack_port_t *port, int onoff) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_request_monitor_by_name (jack_client_t client, const char port_name, int onoff) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_ensure_monitor (jack_port_t *port, int onoff) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_monitoring_input (jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_connect (jack_client_t client, const char source_port, const char *destination_port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_disconnect (jack_client_t client, const char source_port, const char *destination_port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_disconnect (jack_client_t client, jack_port_t port) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_name_size (void) JACK_OPTIONAL_WEAK_EXPORT
int	jack_port_type_size (void) JACK_OPTIONAL_WEAK_EXPORT
size_t	jack_port_type_get_buffer_size (jack_client_t client, const char port_type) JACK_WEAK_EXPORT

Function Documentation

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.

The port_name must be unique among all ports owned by this client. If the name is not unique, the registration will fail.

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, currently only JACK_DEFAULT_AUDIO_TYPE.

Parameters

client	pointer to JACK client structure.
port_name	non-empty short name for the new port (not including the leading "client_name:"). Must be unique.
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.

int jack_port_unregister	(	jack_client_t *	client,
		jack_port_t *	port
	)

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

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

void* jack_port_get_buffer	(	jack_port_t *	port,
		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 : 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.

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

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_flags ( const jack_port_t * port )

Returns: the JackPortFlags of the jack_port_t.

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.

jack_port_type_id_t jack_port_type_id ( const jack_port_t * port )

Returns: the port type id.

int jack_port_is_mine	(	const jack_client_t *	client,
		const jack_port_t *	port
	)

Returns: TRUE if the jack_port_t belongs to the jack_client_t.

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

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

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

int jack_port_tie	(	jack_port_t *	src,
		jack_port_t *	dst
	)

Deprecated:: This function will be removed from a future version of JACK. Do not use it. There is no replacement. It has turned out to serve essentially no purpose in real-life JACK clients.

int jack_port_untie ( jack_port_t * port )

Deprecated:: This function will be removed from a future version of JACK. Do not use it. There is no replacement. It has turned out to serve essentially no purpose in real-life JACK clients.

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.

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.

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_get_aliases	(	const jack_port_t *	port,
		char *const	aliases[2]
	)

Get any aliases known for .

Returns: the number of aliases discovered for the port

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_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_monitoring_input ( jack_port_t * port )

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

int jack_connect	(	jack_client_t *	client,
		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

int jack_disconnect	(	jack_client_t *	client,
		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

int jack_port_disconnect	(	jack_client_t *	client,
		jack_port_t *	port
	)

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

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.

size_t jack_port_type_get_buffer_size	(	jack_client_t *	client,
		const char *	port_type
	)

Returns

the buffersize of a port of type

port_type.

this function may only be called in a buffer_size callback.

Detailed Description

Functions

Function Documentation

FOR OUTPUT PORTS ONLY : DEPRECATED in Jack 2.0 !!