Jack2: Metadata API.

Jack2 1.9.21

Classes | Typedefs | Enumerations | Functions | Variables
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

  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

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

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