add new metadata API header

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 <jack/types.h>
+
+#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__ */