From 15a179df5fc1a388c0719b4305343bd0b8d45cf8 Mon Sep 17 00:00:00 2001 From: falkTX Date: Sun, 6 Oct 2019 20:30:22 +0100 Subject: [PATCH] Update metadata.h from jack2 Signed-off-by: falkTX --- metadata.h | 120 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 110 insertions(+), 10 deletions(-) diff --git a/metadata.h b/metadata.h index e787f08..9e02616 100644 --- a/metadata.h +++ b/metadata.h @@ -1,5 +1,5 @@ /* - Copyright (C) 2011 David Robillard + Copyright (C) 2011-2014 David Robillard Copyright (C) 2013 Paul Davis This program is free software; you can redistribute it and/or modify it @@ -40,6 +40,15 @@ extern "C" { /** * A single property (key:value pair). + * + * Although there is no semantics imposed on metadata keys and values, it is + * much less useful to use it to associate highly structured data with a port + * (or client), since this then implies the need for some (presumably + * library-based) code to parse the structure and be able to use it. + * + * The real goal of the metadata API is to be able to tag ports (and clients) + * with small amounts of data that is outside of the core JACK API but + * nevertheless useful. */ typedef struct { /** The key of this property (URI string). */ @@ -185,6 +194,18 @@ typedef enum { PropertyDeleted } jack_property_change_t; +/** + * 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. + * + * @param subject The subject the change relates to, this can be either a client or port + * @param key The key of the modified property (URI string) + * @param change Wherever the key has been created, changed or deleted + * @param arg pointer to a client supplied structure + */ typedef void (*JackPropertyChangeCallback)(jack_uuid_t subject, const char* key, jack_property_change_t change, @@ -204,19 +225,98 @@ int jack_set_property_change_callback (jack_client_t* client, JackPropertyChangeCallback callback, void* arg); -#ifdef __cplusplus -} /* namespace */ -#endif +/** + * 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". + */ +extern const char* JACK_METADATA_CONNECTED; + +/** + * 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. + */ +extern const char* JACK_METADATA_EVENT_TYPES; + +/** + * 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". + */ +extern const char* JACK_METADATA_HARDWARE; + +/** + * 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. + */ +extern const char* JACK_METADATA_ICON_LARGE; + +/** + * 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 + */ +extern const char* JACK_METADATA_ICON_NAME; + +/** + * 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. + */ +extern const char* JACK_METADATA_ICON_SMALL; + +/** + * 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. + */ +extern const char* JACK_METADATA_ORDER; + +/** + * 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. + */ +extern const char* JACK_METADATA_PRETTY_NAME; + +/** + */ +extern const char* JACK_METADATA_PORT_GROUP; + +/** + * 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. + */ +extern const char* JACK_METADATA_SIGNAL_TYPE; /** * @} */ -extern const char* JACK_METADATA_PRETTY_NAME; -extern const char* JACK_METADATA_HARDWARE; -extern const char* JACK_METADATA_CONNECTED; -extern const char* JACK_METADATA_PORT_GROUP; -extern const char* JACK_METADATA_ICON_SMALL; -extern const char* JACK_METADATA_ICON_LARGE; +#ifdef __cplusplus +} /* namespace */ +#endif #endif /* __jack_metadata_h__ */