summaryrefslogtreecommitdiffstats
path: root/pipewire-jack/jack/metadata.h
blob: 75a41054028231d8ac826e5b0745310e61e601f2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
/*
  Copyright (C) 2011-2014 David Robillard
  Copyright (C) 2013 Paul Davis

  This program is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or (at
  your option) any later version.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with this program; if not, write to the Free Software Foundation,
  Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/

/**
 * @file   jack/metadata.h
 * @ingroup publicheader
 * @brief  JACK Metadata API
 *
 */

#ifndef __jack_metadata_h__
#define __jack_metadata_h__

#include <jack/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup Metadata Metadata API.
 * @{
 */

/**
 * 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). */
    const char* key;

    /** The property value (null-terminated string). */
    const char* data;

    /**
     * Type of data, either a MIME type or URI.
     *
     * If type is NULL or empty, the data is assumed to be a UTF-8 encoded
     * string (text/plain). The data is a null-terminated string regardless of
     * type, so values can always be copied, but clients should not try to
     * interpret values of an unknown type.
     *
     * Example values:
     * - image/png;base64 (base64 encoded PNG image)
     * - http://www.w3.org/2001/XMLSchema#int (integer)
     *
     * Official types are preferred, but clients may use any syntactically
     * valid MIME type (which start with a type and slash, like "text/...").
     * If a URI type is used, it must be a complete absolute URI
     * (which start with a scheme and colon, like "http:").
     */
    const char* type;
} jack_property_t;

/**
 * Set a property on @p subject.
 *
 * See the above documentation for rules about @p subject and @p key.
 * @param subject The subject to set the property on.
 * @param key The key of the property.
 * @param value The value of the property.
 * @param type The type of the property. See the discussion of
 *             types in the definition of jack_property_t above.
 * @return 0 on success.
 */
int
jack_set_property(jack_client_t*,
                  jack_uuid_t subject,
                  const char* key,
                  const char* value,
                  const char* type);

/**
 * Get a property on @p subject.
 *
 * @param subject The subject to get the property from.
 * @param key The key of the property.
 * @param value Set to the value of the property if found, or NULL otherwise.
 *              The caller must free this value with jack_free().
 * @param 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().
 *
 * @return 0 on success, -1 if the @p subject has no @p key property.
 */
int
jack_get_property(jack_uuid_t subject,
                  const char* key,
                  char**      value,
                  char**      type);

/**
 * A description of a subject (a set of properties).
 */
typedef struct {
    jack_uuid_t      subject;        /**< Subject being described. */
    uint32_t         property_cnt;   /**< Number of elements in "properties". */
    jack_property_t* properties;     /**< Array of properties. */
    uint32_t         property_size;  /**< Private, do not use. */
} jack_description_t;

/**
 * Free a description.
 *
 * @param desc a jack_description_t whose associated memory will all be released
 * @param free_description_itself if non-zero, then @param desc will also be passed to free()
 */
void
jack_free_description (jack_description_t* desc, int free_description_itself);

/**
 * Get a description of @p subject.
 * @param subject The subject to get all properties of.
 * @param desc Set to the description of subject if found, or NULL otherwise.
 *             The caller must free this value with jack_free_description().
 * @return the number of properties, -1 if no @p subject with any properties exists.
 */
int
jack_get_properties (jack_uuid_t         subject,
                     jack_description_t* desc);

/**
 * Get descriptions for all subjects with metadata.
 * @param 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().
 * @return the number of descriptions, or -1 on error.
 */
int
jack_get_all_properties (jack_description_t** descs);

/**
 * Remove a single property on a subject.
 *
 * @param client The JACK client making the request to remove the property.
 * @param subject The subject to remove the property from.
 * @param key The key of the property to be removed.
 *
 * @return 0 on success, -1 otherwise
 */
int jack_remove_property (jack_client_t* client, jack_uuid_t subject, const char* key);

/**
 * Remove all properties on a subject.
 *
 * @param client The JACK client making the request to remove some properties.
 * @param subject The subject to remove all properties from.
 *
 * @return a count of the number of properties removed, or -1 on error.
 */
int jack_remove_properties (jack_client_t* client, jack_uuid_t subject);

/**
 * 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()).
 *
 * @param client The JACK client making the request to remove all properties
 *
 * @return 0 on success, -1 otherwise
 */
int jack_remove_all_properties (jack_client_t* client);

typedef enum {
        PropertyCreated,
        PropertyChanged,
        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,
                                           void*                  arg);

/**
 * Arrange for @p client to call @p callback whenever a property is created,
 * changed or deleted.
 *
 * @param client the JACK client making the request
 * @param callback the function to be invoked when a property change occurs
 * @param arg the argument to be passed to @param callback when it is invoked
 *
 * @return 0 success, -1 otherwise.
 */
int jack_set_property_change_callback (jack_client_t*             client,
                                       JackPropertyChangeCallback callback,
                                       void*                      arg);

/**
 * 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:
 * https://specifications.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 audible 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;

/**
 * @}
 */

#ifdef __cplusplus
} /* namespace */
#endif

#endif  /* __jack_metadata_h__ */