common/jack/metadata.h

   1 /*
   2   Copyright (C) 2011-2014 David Robillard
   3   Copyright (C) 2013 Paul Davis
   4
   5   This program is free software; you can redistribute it and/or modify it
   6   under the terms of the GNU Lesser General Public License as published by
   7   the Free Software Foundation; either version 2.1 of the License, or (at
   8   your option) any later version.
   9
  10   This program is distributed in the hope that it will be useful, but WITHOUT
  11   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12   FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  13   License for more details.
  14
  15   You should have received a copy of the GNU Lesser General Public License
  16   along with this program; if not, write to the Free Software Foundation,
  17   Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  18 */
  19
  20 /**
  21  * @file   jack/metadata.h
  22  * @ingroup publicheader
  23  * @brief  JACK Metadata API
  24  *
  25  */
  26
  27 #ifndef __jack_metadata_h__
  28 #define __jack_metadata_h__
  29
  30 #include <jack/types.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @defgroup Metadata Metadata API.
  38  * @{
  39  */
  40
  41 /**
  42  * A single property (key:value pair).
  43  *
  44  * Although there is no semantics imposed on metadata keys and values, it is
  45  * much less useful to use it to associate highly structured data with a port
  46  * (or client), since this then implies the need for some (presumably
  47  * library-based) code to parse the structure and be able to use it.
  48  *
  49  * The real goal of the metadata API is to be able to tag ports (and clients)
  50  * with small amounts of data that is outside of the core JACK API but
  51  * nevertheless useful.
  52  */
  53 typedef struct {
  54     /** The key of this property (URI string). */
  55     const char* key;
  56
  57     /** The property value (null-terminated string). */
  58     const char* data;
  59
  60     /**
  61      * Type of data, either a MIME type or URI.
  62      *
  63      * If type is NULL or empty, the data is assumed to be a UTF-8 encoded
  64      * string (text/plain). The data is a null-terminated string regardless of
  65      * type, so values can always be copied, but clients should not try to
  66      * interpret values of an unknown type.
  67      *
  68      * Example values:
  69      * - image/png;base64 (base64 encoded PNG image)
  70      * - http://www.w3.org/2001/XMLSchema#int (integer)
  71      *
  72      * Official types are preferred, but clients may use any syntactically
  73      * valid MIME type (which start with a type and slash, like "text/...").
  74      * If a URI type is used, it must be a complete absolute URI
  75      * (which start with a scheme and colon, like "http:").
  76      */
  77     const char* type;
  78 } jack_property_t;
  79
  80 /**
  81  * Set a property on @p subject.
  82  *
  83  * See the above documentation for rules about @p subject and @p key.
  84  * @param subject The subject to set the property on.
  85  * @param key The key of the property.
  86  * @param value The value of the property.
  87  * @param type The type of the property. See the discussion of
  88  *             types in the definition of jack_property_t above.
  89  * @return 0 on success.
  90  */
  91 int
  92 jack_set_property(jack_client_t*,
  93                   jack_uuid_t subject,
  94                   const char* key,
  95                   const char* value,
  96                   const char* type);
  97
  98 /**
  99  * Get a property on @p subject.
 100  *
 101  * @param subject The subject to get the property from.
 102  * @param key The key of the property.
 103  * @param value Set to the value of the property if found, or NULL otherwise.
 104  *              The caller must free this value with jack_free().
 105  * @param type The type of the property if set, or NULL. See the discussion
 106  *             of types in the definition of jack_property_t above.
 107  *             If non-null, the caller must free this value with jack_free().
 108  *
 109  * @return 0 on success, -1 if the @p subject has no @p key property.
 110  */
 111 int
 112 jack_get_property(jack_uuid_t subject,
 113                   const char* key,
 114                   char**      value,
 115                   char**      type);
 116
 117 /**
 118  * A description of a subject (a set of properties).
 119  */
 120 typedef struct {
 121     jack_uuid_t      subject;        /**< Subject being described. */
 122     uint32_t         property_cnt;   /**< Number of elements in "properties". */
 123     jack_property_t* properties;     /**< Array of properties. */
 124     uint32_t         property_size;  /**< Private, do not use. */
 125 } jack_description_t;
 126
 127 /**
 128  * Free a description.
 129  *
 130  * @param desc a jack_description_t whose associated memory will all be released
 131  * @param free_description_itself if non-zero, then @param desc will also be passed to free()
 132  */
 133 void
 134 jack_free_description (jack_description_t* desc, int free_description_itself);
 135
 136 /**
 137  * Get a description of @p subject.
 138  * @param subject The subject to get all properties of.
 139  * @param desc Set to the description of subject if found, or NULL otherwise.
 140  *             The caller must free this value with jack_free_description().
 141  * @return 0 on success, -1 if no @p subject with any properties exists.
 142  */
 143 int
 144 jack_get_properties (jack_uuid_t         subject,
 145                      jack_description_t* desc);
 146
 147 /**
 148  * Get descriptions for all subjects with metadata.
 149  * @param descs Set to a NULL-terminated array of descriptions.
 150  *              The caller must free each of these with jack_free_description(),
 151  *              and the array itself with jack_free().
 152  * @return 0 on success.
 153  */
 154 int
 155 jack_get_all_properties (jack_description_t** descs);
 156
 157 /**
 158  * Remove a single property on a subject.
 159  *
 160  * @param client The JACK client making the request to remove the property.
 161  * @param subject The subject to remove the property from.
 162  * @param key The key of the property to be removed.
 163  *
 164  * @return 0 on success, -1 otherwise
 165  */
 166 int jack_remove_property (jack_client_t* client, jack_uuid_t subject, const char* key);
 167
 168 /**
 169  * Remove all properties on a subject.
 170  *
 171  * @param client The JACK client making the request to remove some properties.
 172  * @param subject The subject to remove all properties from.
 173  *
 174  * @return a count of the number of properties removed, or -1 on error.
 175  */
 176 int jack_remove_properties (jack_client_t* client, jack_uuid_t subject);
 177
 178 /**
 179  * Remove all properties.
 180  *
 181  * WARNING!! This deletes all metadata managed by a running JACK server.
 182  * Data lost cannot be recovered (though it can be recreated by new calls
 183  * to jack_set_property()).
 184  *
 185  * @param client The JACK client making the request to remove all properties
 186  *
 187  * @return 0 on success, -1 otherwise
 188  */
 189 int jack_remove_all_properties (jack_client_t* client);
 190
 191 typedef enum {
 192         PropertyCreated,
 193         PropertyChanged,
 194         PropertyDeleted
 195 } jack_property_change_t;
 196
 197 typedef void (*JackPropertyChangeCallback)(jack_uuid_t            subject,
 198                                            const char*            key,
 199                                            jack_property_change_t change,
 200                                            void*                  arg);
 201
 202 /**
 203  * Arrange for @p client to call @p callback whenever a property is created,
 204  * changed or deleted.
 205  *
 206  * @param client the JACK client making the request
 207  * @param callback the function to be invoked when a property change occurs
 208  * @param arg the argument to be passed to @param callback when it is invoked
 209  *
 210  * @return 0 success, -1 otherwise.
 211  */
 212 int jack_set_property_change_callback (jack_client_t*             client,
 213                                        JackPropertyChangeCallback callback,
 214                                        void*                      arg);
 215
 216 /**
 217  * A value that identifies what the hardware port is connected to (an external
 218  * device of some kind). Possible values might be "E-Piano" or "Master 2 Track".
 219  */
 220 extern const char* JACK_METADATA_CONNECTED;
 221
 222 /**
 223  * The supported event types of an event port.
 224  *
 225  * This is a kludge around Jack only supporting MIDI, particularly for OSC.
 226  * This property is a comma-separated list of event types, currently "MIDI" or
 227  * "OSC".  If this contains "OSC", the port may carry OSC bundles (first byte
 228  * '#') or OSC messages (first byte '/').  Note that the "status byte" of both
 229  * OSC events is not a valid MIDI status byte, so MIDI clients that check the
 230  * status byte will gracefully ignore OSC messages if the user makes an
 231  * inappropriate connection.
 232  */
 233 extern const char* JACK_METADATA_EVENT_TYPES;
 234
 235 /**
 236  * A value that should be shown when attempting to identify the
 237  * specific hardware outputs of a client. Typical values might be
 238  * "ADAT1", "S/PDIF L" or "MADI 43".
 239  */
 240 extern const char* JACK_METADATA_HARDWARE;
 241
 242 /**
 243  * A value with a MIME type of "image/png;base64" that is an encoding of an
 244  * NxN (with 32 < N <= 128) image to be used when displaying a visual
 245  * representation of that client or port.
 246  */
 247 extern const char* JACK_METADATA_ICON_LARGE;
 248
 249 /**
 250  * The name of the icon for the subject (typically client).
 251  *
 252  * This is used for looking up icons on the system, possibly with many sizes or
 253  * themes.  Icons should be searched for according to the freedesktop Icon
 254  *
 255  * Theme Specification:
 256  * http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html
 257  */
 258 extern const char* JACK_METADATA_ICON_NAME;
 259
 260 /**
 261  * A value with a MIME type of "image/png;base64" that is an encoding of an
 262  * NxN (with N <=32) image to be used when displaying a visual representation
 263  * of that client or port.
 264  */
 265 extern const char* JACK_METADATA_ICON_SMALL;
 266
 267 /**
 268  * Order for a port.
 269  *
 270  * This is used to specify the best order to show ports in user interfaces.
 271  * The value MUST be an integer.  There are no other requirements, so there may
 272  * be gaps in the orders for several ports.  Applications should compare the
 273  * orders of ports to determine their relative order, but must not assign any
 274  * other relevance to order values.
 275  *
 276  * It is encouraged to use http://www.w3.org/2001/XMLSchema#int as the type.
 277  */
 278 extern const char* JACK_METADATA_ORDER;
 279
 280 /**
 281  * A value that should be shown to the user when displaying a port to the user,
 282  * unless the user has explicitly overridden that a request to show the port
 283  * name, or some other key value.
 284  */
 285 extern const char* JACK_METADATA_PRETTY_NAME;
 286
 287 /**
 288  */
 289 extern const char* JACK_METADATA_PORT_GROUP;
 290
 291 /**
 292  * The type of an audio signal.
 293  *
 294  * This property allows audio ports to be tagged with a "meaning".  The value
 295  * is a simple string.  Currently, the only type is "CV", for "control voltage"
 296  * ports.  Hosts SHOULD be take care to not treat CV ports as audibile and send
 297  * their output directly to speakers.  In particular, CV ports are not
 298  * necessarily periodic at all and may have very high DC.
 299  */
 300 extern const char* JACK_METADATA_SIGNAL_TYPE;
 301
 302 /**
 303  * @}
 304  */
 305
 306 #ifdef __cplusplus
 307 } /* namespace */
 308 #endif
 309
 310 #endif  /* __jack_metadata_h__ */