Jack Utils Ports API

Functions
JU_API int	ju_port_open (ju_ctx_t *x, ju_cstr_t n, enum ju_port_type t, int f)
	Creates new port, and returns port desriptor. More...
JU_API void	ju_port_close (ju_ctx_t *x, int p)
	Decreases reference counter of port, and destroys it, if refcounter == 0. More...
JU_API void	ju_port_take (ju_ctx_t *x, int p)
	Increases reference counter of port. More...
JU_API int	ju_port_connected (ju_ctx_t *x, int p)
	Returns number of connections to the port (or simply is port connected to anything) More...
JU_API int	ju_port_mine (ju_ctx_t *x, int p)
	Returns is port owned by context. More...
JU_API int	ju_port_next (ju_ctx_t *x, int p, enum ju_port_type t)
	Returns next valid port descriptor, owned by JackUtils context. More...
JU_API int	ju_port_find (ju_ctx_t *x, ju_cstr_t n)
	Finds port by full name. More...
JU_PROC const ju_sample_t *()	ju_port_read (ju_ctx_t *x, int p)
	Gets audio buffer from the port. More...
JU_PROC size_t()	ju_port_write (ju_ctx_t *x, int p, const ju_sample_t *a, size_t l)
	Writes data to port with Output type from sample array. More...
JU_PROC void()	ju_port_write_stream (ju_ctx_t *x, int p, ju_stream_func_t s, void *u)
	Writes data to port with Output type from stream callback. More...
JU_API int	ju_port_rawfind (ju_ctx_t *x, jack_port_t *p, int not_own)
	Finds existed port handle, or takes new port handle from jack_port_t. More...
JU_API jack_port_t *	ju_port_rawget (ju_ctx_t *x, int p)
	Returns jack_port_t, associated with handle. More...

Detailed Description

Function Documentation

ju_port_close()

JU_API void ju_port_close	(	ju_ctx_t *	x,
		int	p
	)

Decreases reference counter of port, and destroys it, if refcounter == 0.

Parameters

x	JackUtils context.
p	port descriptor.

References ju_ctx_s::client, get_port_s(), ju_port_s::not_unregister, ju_port_s::port, ju_ctx_s::ports, and ju_port_s::refcnt.

ju_port_connected()

JU_API int ju_port_connected	(	ju_ctx_t *	x,
		int	p
	)

Returns number of connections to the port (or simply is port connected to anything)

Parameters

x	JackUtils context.
p	port descriptor.

Returns

count of connections to the port (0 if nothing connected)

References get_port_j().

ju_port_find()

JU_API int ju_port_find	(	ju_ctx_t *	x,
		ju_cstr_t	n
	)

Finds port by full name.

This function can find not only ports owned by context.

Parameters

x	context
n	port name

Returns

founded (or new) port descriptor, or -1

WARNING: founded port handle is already TAKEN, so fon't forget to CLOSE it, when you don't need this handle anymore! WARNING: This function CAN ONLY BE CALLED AFTER STARTING JACK AUDIO PROCESSING!

See also

ju_port_close()

ju_start()

ju_port_mine()

References ju_ctx_s::client, and ju_port_rawfind().

ju_port_mine()

JU_API int ju_port_mine	(	ju_ctx_t *	x,
		int	p
	)

Returns is port owned by context.

Parameters

x	JackUtils context
p	port descriptor

Returns

1 if context owns this port.

returns 1 only, and ONLY if port descriptor was not NOT created from RAW jack_port with nonzero not_own!

See also

ju_port_rawfind

References ju_ctx_s::client, and get_port_j().

ju_port_next()

JU_API int ju_port_next	(	ju_ctx_t *	x,
		int	p,
		enum ju_port_type	t
	)

Returns next valid port descriptor, owned by JackUtils context.

Parameters

x	context
p	port descriptor
t	search for input or output port

See also

enum ju_port_type

ju_port_mine()

Returns

next port descriptor, owned by client, or -1 when no ports left.

WARNING: this function CLOSES given port handle before searching for next port! : Call port_take on firstly iteratable port handle! (or pass -1 as port handle)

Returned port descriptor already TAKEN! (refcnt increased). You MUST CLOSE port, when it is not needed for you anymore outside of the searching loop!

See also

ju_port_take()

ju_port_close()

References is_input(), JU_INPUT, JU_OUTPUT, ju_port_close(), ju_port_mine(), ju_port_take(), ju_ctx_s::last_port, ju_port_s::port, and ju_ctx_s::ports.

ju_port_open()

JU_API int ju_port_open	(	ju_ctx_t *	x,
		ju_cstr_t	n,
		enum ju_port_type	t,
		int	f
	)

Creates new port, and returns port desriptor.

Jack ports are input or output points for single-channel audio data.

Ports returned by descriptors are safe abstraction above pointers. Valid ports descriptors are 0 .. JU_MAX_PORTS

Parameters

x	jackUtils context
n	port name. Same port names for single client are not allowed!
t	input or output port type
f	additional port flags (JackPortIsTerminal, for example)

See also

enum ju_port_type

Returns

port descriptor (+0) if port have been opened sucessfully

-1 in case of error

References ju_ctx_s::client, JU_INPUT, JU_OUTPUT, and ju_port_rawfind().

ju_port_rawfind()

JU_API int ju_port_rawfind	(	ju_ctx_t *	x,
		jack_port_t *	p,
		int	not_own
	)

Finds existed port handle, or takes new port handle from jack_port_t.

LOWLEVEL API! Use this function ONLY to deal with another kinds of Jack Libraries.

Parameters

x	JackUtils Context
p	JACK PORT
not_own	if == 1, JackUtils will not close this port and threat it as it's owned port.

Returns

founeded (or new) port descriptor

returned descriptor is already TAKEN! So you must to CLOSE it, when you don't need it anymore!

WARNING : jack_port_unregister will be called when both :

1. refcnt is equal 0!
2. port is owned by context! If you don't need jack_port_unregister() call by JackUtils, pass 1 to not_own argument => it will prevent port from being unregistered and threated as owned. WARNING: unregister JACK port while it's used by JACKUTILS is UNDEFINED BEHAVIOUR!

References JU_MAX_PORTS, ju_ctx_s::last_port, ju_port_s::port, ju_ctx_s::ports, and ju_port_s::refcnt.

ju_port_rawget()

JU_API jack_port_t * ju_port_rawget	(	ju_ctx_t *	x,
		int	p
	)

Returns jack_port_t, associated with handle.

(LOWLEVEL) Use this function ONLY to deal with another kinds of Jack Libraries.

Parameters

x	JackUtils context
p	port descriptor

you MUST NOT UNREGISTER returned jack_port_t, or change it's ownership manually! It is Undefined Behaviour! Refcounter of port descriptor is NOT changed here!

References get_port_j().

ju_port_read()

JU_PROC const ju_sample_t *() ju_port_read	(	ju_ctx_t *	x,
		int	p
	)

Gets audio buffer from the port.

Parameters

x	context
p	port descriptor (with type JU_INPUT)

Returns

readonly buffer from Input port

NULL if port is with output type or port handle is invalid

This function can be called ONLY inside the Jack Audio Process Callback!

See also

ju_process_func_t

Theese data buffers are valid only until Audio Processs Callback is working.

Caching and acessing theese buffers later, or outside of Jack Audio Process Callback is Undefined Behaviour!

References get_port_j(), is_input(), and ju_length().

ju_port_take()

JU_API void ju_port_take	(	ju_ctx_t *	x,
		int	p
	)

Increases reference counter of port.

Parameters

x	JackUtils context.
p	port descriptor.

References get_port_s(), and ju_port_s::refcnt.

ju_port_write()

JU_PROC size_t() ju_port_write	(	ju_ctx_t *	x,
		int	p,
		const ju_sample_t *	a,
		size_t	l
	)

Writes data to port with Output type from sample array.

Parameters

x	context
p	port descriptor
a	array of ju_sample_t
l	length of array a

Returns

count of writed samples (<= ju_length())

This function can be called ONLY inside the Audio Process Callback!

References get_port_j(), is_input(), and ju_length().

ju_port_write_stream()

JU_PROC void() ju_port_write_stream	(	ju_ctx_t *	x,
		int	p,
		ju_stream_func_t	s,
		void *	u
	)

Writes data to port with Output type from stream callback.

Parameters

x	context
p	port descriptor
s	stream callback
u	userdata to the stream callback

See also

ju_stream_func_t

This function can be called ONLY inside the Audio Process Callback!