code.delx.au - pulseaudio/blob - src/pulse/proplist.h

   1 #ifndef foopulseproplisthfoo
   2 #define foopulseproplisthfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2007 Lennart Poettering
   8
   9   PulseAudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as
  11   published by the Free Software Foundation; either version 2.1 of the
  12   License, or (at your option) any later version.
  13
  14   PulseAudio is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   Lesser General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public
  20   License along with PulseAudio; if not, write to the Free Software
  21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  22   USA.
  23 ***/
  24
  25 #include <sys/types.h>
  26
  27 #include <pulse/cdecl.h>
  28 #include <pulse/gccmacro.h>
  29
  30 PA_C_DECL_BEGIN
  31
  32 /* Defined properties:
  33  *
  34  *    media.name                    "Guns'N'Roses: Civil War"
  35  *    media.title                   "Civil War"
  36  *    media.artist                  "Guns'N'Roses"
  37  *    media.language                "de_DE"
  38  *    media.filename
  39  *    media.icon
  40  *    media.icon_name
  41  *    media.role                    video, music, game, event, phone, production, filter, abstract, stream
  42  *    event.id                      button-click, session-login
  43  *    event.mouse.x
  44  *    event.mouse.y
  45  *    event.mouse.hpos
  46  *    event.mouse.vpos
  47  *    event.mouse.button
  48  *    window.name
  49  *    window.id
  50  *    window.icon
  51  *    window.icon_name
  52  *    window.x11.display
  53  *    window.x11.screen
  54  *    window.x11.monitor
  55  *    window.x11.xid
  56  *    application.name              "Rhythmbox Media Player"
  57  *    application.id                "org.gnome.rhythmbox"
  58  *    application.version
  59  *    application.icon
  60  *    application.icon_name
  61  *    application.language
  62  *    application.process.id
  63  *    application.process.binary
  64  *    application.process.user
  65  *    application.process.host
  66  *    device.string
  67  *    device.api                     oss, alsa, sunaudio
  68  *    device.description
  69  *    device.bus_path
  70  *    device.serial
  71  *    device.vendor_product_id
  72  *    device.class                   sound, modem, monitor, filter, abstract
  73  *    device.form_factor             laptop-speakers, external-speakers, telephone, tv-capture, webcam-capture, microphone-capture, headset
  74  *    device.connector               isa, pci, usb, firewire, bluetooth
  75  *    device.access_mode             mmap, mmap_rewrite, serial
  76  *    device.master_device
  77  *    device.bufferin.buffer_size
  78  *    device.bufferin.fragment_size
  79  */
  80 #define PA_PROP_MEDIA_NAME                     "media.name"
  81 #define PA_PROP_MEDIA_TITLE                    "media.title"
  82 #define PA_PROP_MEDIA_ARTIST                   "media.artist"
  83 #define PA_PROP_MEDIA_LANGUAGE                 "media.language"
  84 #define PA_PROP_MEDIA_FILENAME                 "media.filename"
  85 #define PA_PROP_MEDIA_ICON                     "media.icon"
  86 #define PA_PROP_MEDIA_ICON_NAME                "media.icon_name"
  87 #define PA_PROP_MEDIA_ROLE                     "media.role"
  88 #define PA_PROP_EVENT_ID                       "event.id"
  89 #define PA_PROP_EVENT_MOUSE_X                  "event.mouse.x"
  90 #define PA_PROP_EVENT_MOUSE_Y                  "event.mouse.y"
  91 #define PA_PROP_EVENT_MOUSE_HPOS               "event.mouse.hpos"
  92 #define PA_PROP_EVENT_MOUSE_VPOS               "event.mouse.vpos"
  93 #define PA_PROP_EVENT_MOUSE_BUTTON             "event.mouse.button"
  94 #define PA_PROP_WINDOW_NAME                    "window.name"
  95 #define PA_PROP_WINDOW_ID                      "window.id"
  96 #define PA_PROP_WINDOW_ICON                    "window.icon"
  97 #define PA_PROP_WINDOW_ICON_NAME               "window.icon_name"
  98 #define PA_PROP_WINDOW_X11_DISPLAY             "window.x11.display"
  99 #define PA_PROP_WINDOW_X11_SCREEN              "window.x11.screen"
 100 #define PA_PROP_WINDOW_X11_MONITOR             "window.x11.monitor"
 101 #define PA_PROP_WINDOW_X11_XID                 "window.x11.xid"
 102 #define PA_PROP_APPLICATION_NAME               "application.name"
 103 #define PA_PROP_APPLICATION_ID                 "application.id"
 104 #define PA_PROP_APPLICATION_VERSION            "application.version"
 105 #define PA_PROP_APPLICATION_ICON               "application.icon"
 106 #define PA_PROP_APPLICATION_ICON_NAME          "application.icon_name"
 107 #define PA_PROP_APPLICATION_LANGUAGE           "application.language"
 108 #define PA_PROP_APPLICATION_PROCESS_ID         "application.process.id"
 109 #define PA_PROP_APPLICATION_PROCESS_BINARY     "application.process.binary"
 110 #define PA_PROP_APPLICATION_PROCESS_USER       "application.process.user"
 111 #define PA_PROP_APPLICATION_PROCESS_HOST       "application.process.host"
 112 #define PA_PROP_DEVICE_STRING                  "device.string"
 113 #define PA_PROP_DEVICE_API                     "device.api"
 114 #define PA_PROP_DEVICE_DESCRIPTION             "device.description"
 115 #define PA_PROP_DEVICE_BUS_PATH                "device.bus_path"
 116 #define PA_PROP_DEVICE_SERIAL                  "device.serial"
 117 #define PA_PROP_DEVICE_VENDOR_PRODUCT_ID       "device.vendor_product_id"
 118 #define PA_PROP_DEVICE_CLASS                   "device.class"
 119 #define PA_PROP_DEVICE_FORM_FACTOR             "device.form_factor"
 120 #define PA_PROP_DEVICE_CONNECTOR               "device.connector"
 121 #define PA_PROP_DEVICE_ACCESS_MODE             "device.access_mode"
 122 #define PA_PROP_DEVICE_MASTER_DEVICE           "device.master_device"
 123 #define PA_PROP_DEVICE_BUFFERING_BUFFER_SIZE   "device.buffering.buffer_size"
 124 #define PA_PROP_DEVICE_BUFFERING_FRAGMENT_SIZE "device.buffering.fragment_size"
 125
 126 /** A property list object. Basically a dictionary with UTF-8 strings
 127  * as keys and arbitrary data as values. \since 0.9.11 */
 128 typedef struct pa_proplist pa_proplist;
 129
 130 /** Allocate a property list. \since 0.9.11 */
 131 pa_proplist* pa_proplist_new(void);
 132
 133 /** Free the property list. \since 0.9.11 */
 134 void pa_proplist_free(pa_proplist* p);
 135
 136 /** Append a new string entry to the property list, possibly
 137  * overwriting an already existing entry with the same key. An
 138  * internal copy of the data passed is made. Will accept only valid
 139  * UTF-8. \since 0.9.11 */
 140 int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
 141
 142 /** Append a new string entry to the property list, possibly
 143  * overwriting an already existing entry with the same key. An
 144  * internal copy of the data passed is made. Will accept only valid
 145  * UTF-8. The data can be passed as printf()-style format string with
 146  * arguments. \since 0.9.11 */
 147 int pa_proplist_setf(pa_proplist *p, const char *key, const char *format, ...) PA_GCC_PRINTF_ATTR(3,4);
 148
 149 /** Append a new arbitrary data entry to the property list, possibly
 150  * overwriting an already existing entry with the same key. An
 151  * internal copy of the data passed is made. \since 0.9.11 */
 152 int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nbytes);
 153
 154 /* Return a string entry for the specified key. Will return NULL if
 155  * the data is not valid UTF-8. Will return a NUL-terminated string in
 156  * an internally allocated buffer. The caller should make a copy of
 157  * the data before accessing the property list again. \since 0.9.11 */
 158 const char *pa_proplist_gets(pa_proplist *p, const char *key);
 159
 160 /** Return the the value for the specified key. Will return a
 161  * NUL-terminated string for string entries. The pointer returned will
 162  * point to an internally allocated buffer. The caller should make a
 163  * copy of the data before the property list is accessed again. \since
 164  * 0.9.11 */
 165 int pa_proplist_get(pa_proplist *p, const char *key, const void **data, size_t *nbytes);
 166
 167 /** Update mode enum for pa_proplist_update(). \since 0.9.11 */
 168 typedef enum pa_update_mode {
 169     PA_UPDATE_SET,  /*< Replace the entirey property list with the new one. Don't keep any of the old data around */
 170     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. */
 171     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. */
 172 } pa_update_mode_t;
 173
 174 /** Merge property list "other" into "p", adhering the merge mode as
 175  * specified in "mode". \since 0.9.11 */
 176 void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, pa_proplist *other);
 177
 178 /** Removes a single entry from the property list, identified be the
 179  * specified key name. \since 0.9.11 */
 180 int pa_proplist_unset(pa_proplist *p, const char *key);
 181
 182 /** Similar to pa_proplist_remove() but takes an array of keys to
 183  * remove. The array should be terminated by a NULL pointer. Return -1
 184  * on failure, otherwise the number of entries actually removed (which
 185  * might even be 0, if there where no matching entries to
 186  * remove). \since 0.9.11 */
 187 int pa_proplist_unset_many(pa_proplist *p, const char * const keys[]);
 188
 189 /** Iterate through the property list. The user should allocate a
 190  * state variable of type void* and initialize it with NULL. A pointer
 191  * to this variable should then be passed to pa_proplist_iterate()
 192  * which should be called in a loop until it returns NULL which
 193  * signifies EOL. The property list should not be modified during
 194  * iteration through the list -- except for deleting the current
 195  * looked at entry. On each invication this function will return the
 196  * key string for the next entry. The keys in the property list do not
 197  * have any particular order. \since 0.9.11 */
 198 const char *pa_proplist_iterate(pa_proplist *p, void **state);
 199
 200 /** Format the property list nicely as a human readable string. Call pa_xfree() on the result. \since
 201  * 0.9.11 */
 202 char *pa_proplist_to_string(pa_proplist *p);
 203
 204 /** Returns 1 if an entry for the specified key is existant in the
 205  * property list. \since 0.9.11 */
 206 int pa_proplist_contains(pa_proplist *p, const char *key);
 207
 208 /** Remove all entries from the property list object. \since 0.9.11 */
 209 void pa_proplist_clear(pa_proplist *p);
 210
 211 /** Allocate a new property list and copy over every single entry from
 212  * the specific list. \since 0.9.11 */
 213 pa_proplist* pa_proplist_copy(pa_proplist *t);
 214
 215 PA_C_DECL_END
 216
 217 #endif