LADI
/
jack-headers
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1 from drobilla/master 

Clean up metadata.h and fix Doxygen markup.
This commit is contained in:
pauldavisthefirst 2014-01-19 12:46:58 -08:00
parent 742c63e024 56000a76d1
commit 686a7414a7
1 changed files with 63 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
metadata.h
View File

@ -1,17 +1,17 @@
/*
Copyright (C) 2011 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.
@ -42,38 +42,41 @@ extern "C" {
* A single property (key:value pair).
*/
typedef struct {
const char* key; /**< The key of this property (URI string). */
const char* data; /**< The property value (null-terminated string) */
const char* type; /**< MIME type of data. Likely values are:
*
* text/utf8 (for an null terminated string)
* image/png;base64 (for a data-URI converted image)
*
* If type is null (or empty), the type should
* be assumed to be "text/utf8" and the memory
* pointed to by "data" should be interpreted
* as a null-terminated string encoded using UTF-8.
*
* If the type is image/png;base64, the memory
* pointed to by "data" should be interpreted as
* a base64 encoded PNG image.
*
* Other types are subject to the shared understanding
* of the mime type by both the setter and retriever
* of the property.
*/
/** 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 @c subject.
* Set a property on @p subject.
*
* See the above documentation for rules about @c subject and @c key.
* 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 MIME type of the property. See the discussion of
* types in the definition of jack_property_t above.
* @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
@ -84,18 +87,17 @@ jack_set_property(jack_client_t*,
const char* type);
/**
* Get a property on @c subject.
* 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 MIME 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().
* @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 @c subject has no @c key property.
* @return 0 on success, -1 if the @p subject has no @p key property.
*/
int
jack_get_property(jack_uuid_t subject,
@ -107,10 +109,10 @@ jack_get_property(jack_uuid_t subject,
* A description of a subject (a set of properties).
*/
typedef struct {
jack_uuid_t subject; /**< The subject being described. */
uint32_t property_cnt;/**< The number of properties stored in "properties" */
jack_property_t* properties; /**< An array of properties. */
uint32_t property_size; /**< private, don't use or touch */
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;
/**
@ -120,18 +122,18 @@ typedef struct {
* @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);
jack_free_description (jack_description_t* desc, int free_description_itself);
/**
* Get a description of @c subject.
* 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_desription().
* @return 0 on success, -1 if no @c subject with any properties exists.
* @return 0 on success, -1 if no @p subject with any properties exists.
*/
int
jack_get_properties (jack_uuid_t subject,
jack_description_t* desc);
jack_get_properties (jack_uuid_t subject,
jack_description_t* desc);
/**
* Get descriptions for all subjects with metadata.
@ -143,7 +145,8 @@ jack_get_properties (jack_uuid_t subject,
int
jack_get_all_properties (jack_description_t** descs);
/** Remove a single property on a subject
/**
* 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.
@ -153,21 +156,23 @@ jack_get_all_properties (jack_description_t** descs);
*/
int jack_remove_property (jack_client_t* client, jack_uuid_t subject, const char* key);
/** Remove all properties on a subject
/**
* 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 if an error occurs
* @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
/**
* Remove all properties.
*
* WARNING!! This deletes all metadata managed by a running JACK server.
* 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()).
*
* to jack_set_property()).
*
* @param client The JACK client making the request to remove all properties
*
* @return 0 on success, -1 otherwise
@ -180,13 +185,14 @@ typedef enum {
PropertyDeleted
} jack_property_change_t;
typedef void (*JackPropertyChangeCallback)(jack_uuid_t subject,
const char* key,
typedef void (*JackPropertyChangeCallback)(jack_uuid_t subject,
const char* key,
jack_property_change_t change,
void* arg);
void* arg);
/** Arrange for @param client to call @param callback whenever
* a property is created, changed or deleted.
/**
* 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
@ -194,9 +200,9 @@ typedef void (*JackPropertyChangeCallback)(jack_uuid_t subject,
*
* @return 0 success, -1 otherwise.
*/
int jack_set_property_change_callback (jack_client_t* client,
int jack_set_property_change_callback (jack_client_t* client,
JackPropertyChangeCallback callback,
void *arg);
void* arg);
#ifdef __cplusplus
} /* namespace */