diff options
Diffstat (limited to 'src/pulse/proplist.h')
| -rw-r--r-- | src/pulse/proplist.h | 185 |
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 |