From 94dd1e8751371761b60d511171d89fd149b417be Mon Sep 17 00:00:00 2001 From: Paul Davis Date: Mon, 30 Sep 2013 18:55:15 -0400 Subject: [PATCH] add new metadata API header --- metadata.h | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 metadata.h diff --git a/metadata.h b/metadata.h new file mode 100644 index 0000000..26122f5 --- /dev/null +++ b/metadata.h @@ -0,0 +1,164 @@ +/* + Copyright (C) 2001 Paul Davis + Copyright (C) 2011 David Robillard + + 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. +*/ + +#ifndef __jack_metadata_h__ +#define __jack_metadata_h__ + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @defgroup Metadata Metadata API. + * @{ + */ + +/** + * 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. + */ +} jack_property_t; + + +/** + * Set a property on @c subject. + * + * See the above documentation for rules about @c subject and @c 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. + * @return 0 on success. + */ +int +jack_set_property(jack_uuid_t subject, + const char* key, + const char* value, + const char* type); + +/** + * Get a property on @c 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(). + * + * @return 0 on success, -1 if the @c subject has no @c 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; /**< The subject being described. */ + jack_property_t* properties; /**< An array of properties. */ +} jack_description_t; + +/** + * Free a description. + */ +void +jack_free_description(jack_description_t* desc); + +/** + * Get a description of @c 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. + */ +int +jack_get_properties (jack_uuid_t subject, + jack_description_t* desc); + +/** + * Get descriptions for all subjects with metadata. + * @param subject The subject to get all properties of. + * @param descs Set to a NULL-terminated array of descriptions. + * The caller must free each of these with jack_free_desription(), + * and the array itself with jack_free(). + * @return 0 on success. + */ +int +jack_get_all_properties (jack_description_t** descs); + + +int jack_remove_property (jack_uuid_t subject, const char* key); +int jack_remove_properties (jack_uuid_t subject); + +int jack_remove_all_properties (void); + +typedef enum { + PropertyCreated, + PropertyChanged, + PropertyDeleted +} jack_property_change_t; + +typedef void (*JackPropertyChangeCallback)(jack_uuid_t subject, + const char* key, + jack_property_change_t change, + void* arg); + +int jack_set_property_change_callback (jack_client_t* client, + JackPropertyChangeCallback callback, + void *arg); + + +#ifdef __cplusplus +} /* namespace */ +#endif + +/** + * @} + */ + +#endif /* __jack_metadata_h__ */