Jack2 1.9.22
Metadata API.

Classes

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
subjectThe subject the change relates to, this can be either a client or port
keyThe key of the modified property (URI string)
changeWherever the key has been created, changed or deleted
argpointer to a client supplied structure

Definition at line 209 of file metadata.h.

Enumeration Type Documentation

◆ jack_property_change_t

enum jack_property_change_t

Definition at line 191 of file metadata.h.

Function Documentation

◆ 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
subjectThe subject to set the property on.
keyThe key of the property.
valueThe value of the property.
typeThe type of the property. See the discussion of types in the definition of jack_property_t above.
Returns
0 on success.

◆ jack_get_property()

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

Get a property on subject.

Parameters
subjectThe subject to get the property from.
keyThe key of the property.
valueSet to the value of the property if found, or NULL otherwise. The caller must free this value with jack_free().
typeThe 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_free_description()

void jack_free_description ( jack_description_t * desc,
int free_description_itself )

Free a description.

Parameters
desca jack_description_t whose associated memory will all be released
free_description_itselfif non-zero, then
descwill also be passed to free()

◆ jack_get_properties()

int jack_get_properties ( jack_uuid_t subject,
jack_description_t * desc )

Get a description of subject.

Parameters
subjectThe subject to get all properties of.
descSet 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_all_properties()

int jack_get_all_properties ( jack_description_t ** descs)

Get descriptions for all subjects with metadata.

Parameters
descsSet 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_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
clientThe JACK client making the request to remove the property.
subjectThe subject to remove the property from.
keyThe key of the property to be removed.
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
clientThe JACK client making the request to remove some properties.
subjectThe subject to remove all properties from.
Returns
a count of the number of properties removed, or -1 on error.

◆ 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
clientThe JACK client making the request to remove all properties
Returns
0 on success, -1 otherwise

◆ 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
clientthe JACK client making the request
callbackthe function to be invoked when a property change occurs
argthe argument to be passed to
callbackwhen 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_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.