Metadata API.

Data Structures
struct	jack_property_t
struct	jack_description_t

Typedefs
typedef void(*	JackPropertyChangeCallback) (jack_uuid_t subject, const char *key, jack_property_change_t change, void *arg)

Enumerations
enum	jack_property_change_t { PropertyCreated , PropertyChanged , PropertyDeleted }

Functions
int	jack_set_property (jack_client_t *, jack_uuid_t subject, const char *key, const char *value, const char *type)
int	jack_get_property (jack_uuid_t subject, const char *key, char **value, char **type)
void	jack_free_description (jack_description_t *desc, int free_description_itself)
int	jack_get_properties (jack_uuid_t subject, jack_description_t *desc)
int	jack_get_all_properties (jack_description_t **descs)
int	jack_remove_property (jack_client_t *client, jack_uuid_t subject, const char *key)
int	jack_remove_properties (jack_client_t *client, jack_uuid_t subject)
int	jack_remove_all_properties (jack_client_t *client)
int	jack_set_property_change_callback (jack_client_t *client, JackPropertyChangeCallback callback, void *arg)

Variables
const char *	JACK_METADATA_CONNECTED
const char *	JACK_METADATA_EVENT_TYPES
const char *	JACK_METADATA_HARDWARE
const char *	JACK_METADATA_ICON_LARGE
const char *	JACK_METADATA_ICON_NAME
const char *	JACK_METADATA_ICON_SMALL
const char *	JACK_METADATA_ORDER
const char *	JACK_METADATA_PRETTY_NAME
const char *	JACK_METADATA_PORT_GROUP
const char *	JACK_METADATA_SIGNAL_TYPE

Detailed Description

Typedef Documentation

JackPropertyChangeCallback

typedef void(* JackPropertyChangeCallback) (jack_uuid_t subject, const char *key, jack_property_change_t change, void *arg)

Prototype for the client supplied function that is called by the engine anytime a property or properties have been modified.

Note that when the key is empty, it means all properties have been modified. This is often used to indicate that the removal of all keys.

Parameters

subject	The subject the change relates to, this can be either a client or port
key	The key of the modified property (URI string)
change	Wherever the key has been created, changed or deleted
arg	pointer to a client supplied structure

Enumeration Type Documentation

jack_property_change_t

enum jack_property_change_t

Enumerator
PropertyCreated
PropertyChanged
PropertyDeleted

Function Documentation

jack_free_description()

void jack_free_description	(	jack_description_t *	desc,
		int	free_description_itself
	)

Free a description.

Parameters

desc	a jack_description_t whose associated memory will all be released
free_description_itself	if non-zero, then
desc	will also be passed to free()

jack_get_all_properties()

int jack_get_all_properties

(

jack_description_t **

descs

)

Get descriptions for all subjects with metadata.

Parameters

descs

Set to an array of descriptions. The caller must free each of these with jack_free_description(), and the array itself with jack_free().

Returns

the number of descriptions, or -1 on error.

jack_get_properties()

int jack_get_properties	(	jack_uuid_t	subject,
		jack_description_t *	desc
	)

Get a description of subject.

Parameters

subject	The subject to get all properties of.
desc	Set to the description of subject if found, or NULL otherwise. The caller must free this value with jack_free_description().

Returns

the number of properties, -1 if no subject with any properties exists.

jack_get_property()

int jack_get_property	(	jack_uuid_t	subject,
		const char *	key,
		char **	value,
		char **	type
	)

Get a property on subject.

Parameters

subject	The subject to get the property from.
key	The key of the property.
value	Set to the value of the property if found, or NULL otherwise. The caller must free this value with jack_free().
type	The type of the property if set, or NULL. See the discussion of types in the definition of jack_property_t above. If non-null, the caller must free this value with jack_free().

Returns

0 on success, -1 if the subject has no key property.

jack_remove_all_properties()

int jack_remove_all_properties

(

jack_client_t *

client

)

Remove all properties.

WARNING!! This deletes all metadata managed by a running JACK server. Data lost cannot be recovered (though it can be recreated by new calls to jack_set_property()).

Parameters

client

The JACK client making the request to remove all properties

Returns

0 on success, -1 otherwise

jack_remove_properties()

int jack_remove_properties	(	jack_client_t *	client,
		jack_uuid_t	subject
	)

Remove all properties on a subject.

Parameters

client	The JACK client making the request to remove some properties.
subject	The subject to remove all properties from.

Returns

a count of the number of properties removed, or -1 on error.

jack_remove_property()

int jack_remove_property	(	jack_client_t *	client,
		jack_uuid_t	subject,
		const char *	key
	)

Remove a single property on a subject.

Parameters

client	The JACK client making the request to remove the property.
subject	The subject to remove the property from.
key	The key of the property to be removed.

Returns

0 on success, -1 otherwise

jack_set_property()

int jack_set_property	(	jack_client_t *	,
		jack_uuid_t	subject,
		const char *	key,
		const char *	value,
		const char *	type
	)

Set a property on subject.

See the above documentation for rules about subject and key.

Parameters

subject	The subject to set the property on.
key	The key of the property.
value	The value of the property.
type	The type of the property. See the discussion of types in the definition of jack_property_t above.

Returns

0 on success.

jack_set_property_change_callback()

int jack_set_property_change_callback	(	jack_client_t *	client,
		JackPropertyChangeCallback	callback,
		void *	arg
	)

Arrange for client to call callback whenever a property is created, changed or deleted.

Parameters

client	the JACK client making the request
callback	the function to be invoked when a property change occurs
arg	the argument to be passed to
callback	when it is invoked

Returns

0 success, -1 otherwise.

Variable Documentation

JACK_METADATA_CONNECTED

const char* JACK_METADATA_CONNECTED

extern

A value that identifies what the hardware port is connected to (an external device of some kind). Possible values might be "E-Piano" or "Master 2 Track".

JACK_METADATA_EVENT_TYPES

const char* JACK_METADATA_EVENT_TYPES

extern

The supported event types of an event port.

This is a kludge around Jack only supporting MIDI, particularly for OSC. This property is a comma-separated list of event types, currently "MIDI" or "OSC". If this contains "OSC", the port may carry OSC bundles (first byte '#') or OSC messages (first byte '/'). Note that the "status byte" of both OSC events is not a valid MIDI status byte, so MIDI clients that check the status byte will gracefully ignore OSC messages if the user makes an inappropriate connection.

JACK_METADATA_HARDWARE

const char* JACK_METADATA_HARDWARE

extern

A value that should be shown when attempting to identify the specific hardware outputs of a client. Typical values might be "ADAT1", "S/PDIF L" or "MADI 43".

JACK_METADATA_ICON_LARGE

const char* JACK_METADATA_ICON_LARGE

extern

A value with a MIME type of "image/png;base64" that is an encoding of an NxN (with 32 < N <= 128) image to be used when displaying a visual representation of that client or port.

JACK_METADATA_ICON_NAME

const char* JACK_METADATA_ICON_NAME

extern

The name of the icon for the subject (typically client).

This is used for looking up icons on the system, possibly with many sizes or themes. Icons should be searched for according to the freedesktop Icon

Theme Specification: https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html

JACK_METADATA_ICON_SMALL

const char* JACK_METADATA_ICON_SMALL

extern

A value with a MIME type of "image/png;base64" that is an encoding of an NxN (with N <=32) image to be used when displaying a visual representation of that client or port.

JACK_METADATA_ORDER

const char* JACK_METADATA_ORDER

extern

Order for a port.

This is used to specify the best order to show ports in user interfaces. The value MUST be an integer. There are no other requirements, so there may be gaps in the orders for several ports. Applications should compare the orders of ports to determine their relative order, but must not assign any other relevance to order values.

It is encouraged to use http://www.w3.org/2001/XMLSchema#int as the type.

JACK_METADATA_PORT_GROUP

const char* JACK_METADATA_PORT_GROUP

extern

JACK_METADATA_PRETTY_NAME

const char* JACK_METADATA_PRETTY_NAME

extern

A value that should be shown to the user when displaying a port to the user, unless the user has explicitly overridden that a request to show the port name, or some other key value.

JACK_METADATA_SIGNAL_TYPE

const char* JACK_METADATA_SIGNAL_TYPE

extern

The type of an audio signal.

This property allows audio ports to be tagged with a "meaning". The value is a simple string. Currently, the only type is "CV", for "control voltage" ports. Hosts SHOULD be take care to not treat CV ports as audibile and send their output directly to speakers. In particular, CV ports are not necessarily periodic at all and may have very high DC.