JACK-AUDIO-CONNECTION-KIT
Data Structures | Typedefs | Enumerations | Functions | Variables
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
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

Enumeration Type Documentation

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

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

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

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

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

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: http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html

◆ JACK_METADATA_ICON_SMALL

const char* JACK_METADATA_ICON_SMALL

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

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

◆ JACK_METADATA_PRETTY_NAME

const char* JACK_METADATA_PRETTY_NAME

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

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.