merge glitch-free branch back into trunk

git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@2445 fefdeb5f-60dc-0310-8127-8f9354f1896f

1 files changed, 147 insertions, 38 deletions

diff --git a/src/pulse/proplist.h b/src/pulse/proplist.h
index c4cf9ac9..f433ec62 100644
--- a/src/pulse/proplist.h
+++ b/src/pulse/proplist.h
@@ -24,67 +24,176 @@
   USA.
 ***/
 
-#include <pulsecore/macro.h>
+#include <pulse/cdecl.h>
+#include <pulse/gccmacro.h>
+
+PA_C_DECL_BEGIN
 
 /* Defined properties:
  *
- *    x11.xid
- *    x11.display
- *    x11.x_pointer
- *    x11.y_pointer
- *    x11.button
- *    media.name
- *    media.title
- *    media.artist
- *    media.language
+ *    media.name                    "Guns'N'Roses: Civil War"
+ *    media.title                   "Civil War"
+ *    media.artist                  "Guns'N'Roses"
+ *    media.language                "de_DE"
  *    media.filename
  *    media.icon
  *    media.icon_name
- *    media.role                    video, music, game, event, phone, production
- *    application.name
+ *    media.role                    video, music, game, event, phone, production, filter, abstract, stream
+ *    event.id                      button-click, session-login
+ *    event.x11.display
+ *    event.x11.xid
+ *    event.x11.x_pointer
+ *    event.x11.y_pointer
+ *    event.x11.button
+ *    application.name              "Rhythmbox Media Player"
+ *    application.id                "org.gnome.rhythmbox"
  *    application.version
  *    application.icon
  *    application.icon_name
+ *    application.process.id
+ *    application.process.binary
+ *    application.process.user
+ *    application.process.host
+ *    device.string
+ *    device.api                     oss, alsa, sunaudio
+ *    device.description
+ *    device.bus_path
+ *    device.serial
+ *    device.vendor_product_id
+ *    device.class                   sound, modem, monitor, filter
+ *    device.form_factor             laptop-speakers, external-speakers, telephone, tv-capture, webcam-capture, microphone-capture, headset
+ *    device.connector               isa, pci, usb, firewire, bluetooth
+ *    device.access_mode             mmap, mmap_rewrite, serial
+ *    device.master_device
+ *    device.buffer_size
  */
 
-#define PA_PROP_X11_XID                  "x11.xid"
-#define PA_PROP_X11_DISPLAY              "x11.display"
-#define PA_PROP_X11_X_POINTER            "x11.x_pointer"
-#define PA_PROP_X11_Y_POINTER            "x11.y_pointer"
-#define PA_PROP_X11_BUTTON               "x11.button"
-#define PA_PROP_MEDIA_NAME               "media.name"
-#define PA_PROP_MEDIA_TITLE              "media.title"
-#define PA_PROP_MEDIA_ARTIST             "media.artist"
-#define PA_PROP_MEDIA_LANGUAGE           "media.language"
-#define PA_PROP_MEDIA_FILENAME           "media.filename"
-#define PA_PROP_MEDIA_ICON               "media.icon"
-#define PA_PROP_MEDIA_ICON_NAME          "media.icon_name"
-#define PA_PROP_MEDIA_ROLE               "media.role"
-#define PA_PROP_APPLICATION_NAME         "application.name"
-#define PA_PROP_APPLICATION_VERSION      "application.version"
-#define PA_PROP_APPLICATION_ICON         "application.icon"
-#define PA_PROP_APPLICATION_ICON_NAME    "application.icon_name"
-
+#define PA_PROP_MEDIA_NAME                     "media.name"
+#define PA_PROP_MEDIA_TITLE                    "media.title"
+#define PA_PROP_MEDIA_ARTIST                   "media.artist"
+#define PA_PROP_MEDIA_LANGUAGE                 "media.language"
+#define PA_PROP_MEDIA_FILENAME                 "media.filename"
+#define PA_PROP_MEDIA_ICON                     "media.icon"
+#define PA_PROP_MEDIA_ICON_NAME                "media.icon_name"
+#define PA_PROP_MEDIA_ROLE                     "media.role"
+#define PA_PROP_EVENT_ID                       "event.id"
+#define PA_PROP_EVENT_X11_DISPLAY              "event.x11.display"
+#define PA_PROP_EVENT_X11_XID                  "event.x11.xid"
+#define PA_PROP_EVENT_MOUSE_X                  "event.mouse.x"
+#define PA_PROP_EVENT_MOUSE_Y                  "event.mouse.y"
+#define PA_PROP_EVENT_MOUSE_BUTTON             "event.mouse.button"
+#define PA_PROP_APPLICATION_NAME               "application.name"
+#define PA_PROP_APPLICATION_ID                 "application.id"
+#define PA_PROP_APPLICATION_VERSION            "application.version"
+#define PA_PROP_APPLICATION_ICON               "application.icon"
+#define PA_PROP_APPLICATION_ICON_NAME          "application.icon_name"
+#define PA_PROP_APPLICATION_LANGUAGE           "application.language"
+#define PA_PROP_APPLICATION_PROCESS_ID         "application.process.id"
+#define PA_PROP_APPLICATION_PROCESS_BINARY     "application.process.binary"
+#define PA_PROP_APPLICATION_PROCESS_USER       "application.process.user"
+#define PA_PROP_APPLICATION_PROCESS_HOST       "application.process.host"
+#define PA_PROP_DEVICE_STRING                  "device.string"
+#define PA_PROP_DEVICE_API                     "device.api"
+#define PA_PROP_DEVICE_DESCRIPTION             "device.description"
+#define PA_PROP_DEVICE_BUS_PATH                "device.bus_path"
+#define PA_PROP_DEVICE_SERIAL                  "device.serial"
+#define PA_PROP_DEVICE_VENDOR_PRODUCT_ID       "device.vendor_product_id"
+#define PA_PROP_DEVICE_CLASS                   "device.class"
+#define PA_PROP_DEVICE_FORM_FACTOR             "device.form_factor"
+#define PA_PROP_DEVICE_CONNECTOR               "device.connector"
+#define PA_PROP_DEVICE_ACCESS_MODE             "device.access_mode"
+#define PA_PROP_DEVICE_MASTER_DEVICE           "device.master_device"
+#define PA_PROP_DEVICE_BUFFERING_BUFFER_SIZE   "device.buffering.buffer_size"
+#define PA_PROP_DEVICE_BUFFERING_FRAGMENT_SIZE "device.buffering.fragment_size"
+
+/** A property list object. Basically a dictionary with UTF-8 strings
+ * as keys and arbitrary data as values. \since 0.9.11 */
 typedef struct pa_proplist pa_proplist;
 
+/** Allocate a property list. \since 0.9.11 */
 pa_proplist* pa_proplist_new(void);
-void pa_proplist_free(pa_proplist* p);
 
-/** Will accept only valid UTF-8 */
-int pa_proplist_puts(pa_proplist *p, const char *key, const char *value);
-int pa_proplist_put(pa_proplist *p, const char *key, const void *data, size_t nbytes);
+/** Free the property list. \since 0.9.11 */
+void pa_proplist_free(pa_proplist* p);
 
-/* Will return NULL if the data is not valid UTF-8 */
+/** Append a new string entry to the property list, possibly
+ * overwriting an already existing entry with the same key. An
+ * internal copy of the data passed is made. Will accept only valid
+ * UTF-8. \since 0.9.11 */
+int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
+
+/** Append a new string entry to the property list, possibly
+ * overwriting an already existing entry with the same key. An
+ * internal copy of the data passed is made. Will accept only valid
+ * UTF-8. The data can be passed as printf()-style format string with
+ * arguments. \since 0.9.11 */
+int pa_proplist_setf(pa_proplist *p, const char *key, const char *format, ...) PA_GCC_PRINTF_ATTR(3,4);
+
+/** Append a new arbitrary data entry to the property list, possibly
+ * overwriting an already existing entry with the same key. An
+ * internal copy of the data passed is made. \since 0.9.11 */
+int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nbytes);
+
+/* Return a string entry for the specified key. Will return NULL if
+ * the data is not valid UTF-8. Will return a NUL-terminated string in
+ * an internally allocated buffer. The caller should make a copy of
+ * the data before accessing the property list again. \since 0.9.11 */
 const char *pa_proplist_gets(pa_proplist *p, const char *key);
-int pa_proplist_get(pa_proplist *p, const char *key, const void **data, size_t *nbytes);
 
-void pa_proplist_merge(pa_proplist *p, pa_proplist *other);
-int pa_proplist_remove(pa_proplist *p, const char *key);
+/** Return the the value for the specified key. Will return a
+ * NUL-terminated string for string entries. The pointer returned will
+ * point to an internally allocated buffer. The caller should make a
+ * copy of the data before the property list is accessed again. \since
+ * 0.9.11 */
+int pa_proplist_get(pa_proplist *p, const char *key, const void **data, size_t *nbytes);
 
+/** Update mode enum for pa_proplist_update(). \since 0.9.11 */
+typedef enum pa_update_mode {
+    PA_UPDATE_SET,  /*< Replace the entirey property list with the new one. Don't keep any of the old data around */
+    PA_UPDATE_MERGE, /*< Merge new property list into the existing one, not replacing any old entries if they share a common key with the new property list. */
+    PA_UPDATE_REPLACE /*< Merge new property list into the existing one, replacing all old entries that share a common key with  the new property list. */
+} pa_update_mode_t;
+
+/** Merge property list "other" into "p", adhering the merge mode as
+ * specified in "mode". \since 0.9.11 */
+void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, pa_proplist *other);
+
+/** Removes a single entry from the property list, identified be the
+ * specified key name. \since 0.9.11 */
+int pa_proplist_unset(pa_proplist *p, const char *key);
+
+/** Similar to pa_proplist_remove() but takes an array of keys to
+ * remove. The array should be terminated by a NULL pointer. Return -1
+ * on failure, otherwise the number of entries actually removed (which
+ * might even be 0, if there where no matching entries to
+ * remove). \since 0.9.11 */
+int pa_proplist_unset_many(pa_proplist *p, const char * const keys[]);
+
+/** Iterate through the property list. The user should allocate a
+ * state variable of type void* and initialize it with NULL. A pointer
+ * to this variable should then be passed to pa_proplist_iterate()
+ * which should be called in a loop until it returns NULL which
+ * signifies EOL. The property list should not be modified during
+ * iteration through the list. On each invication this function will
+ * return the key string for the next entry. The keys in the property
+ * list do not have any particular order. \since 0.9.11 */
 const char *pa_proplist_iterate(pa_proplist *p, void **state);
 
+/** Format the property list nicely as a human readable string. Call pa_xfree() on the result. \since
+ * 0.9.11 */
 char *pa_proplist_to_string(pa_proplist *p);
 
+/** Returns 1 if an entry for the specified key is existant in the
+ * property list. \since 0.9.11 */
 int pa_proplist_contains(pa_proplist *p, const char *key);
 
+/** Remove all entries from the property list object. \since 0.9.11 */
+void pa_proplist_clear(pa_proplist *p);
+
+/** Allocate a new property list and copy over every single entry from
+ * the specific list. \since 0.9.11 */
+pa_proplist* pa_proplist_copy(pa_proplist *t);
+
+PA_C_DECL_END
+
 #endif