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 #include <pulse/version.h>
  30
  31 PA_C_DECL_BEGIN
  32
  33 /* Defined properties:
  34  *
  35  *    media.name                    "Guns'N'Roses: Civil War"
  36  *    media.title                   "Civil War"
  37  *    media.artist                  "Guns'N'Roses"
  38  *    media.language                "de_DE"
  39  *    media.filename
  40  *    media.icon                    Binary blob containing PNG icon data
  41  *    media.icon_name               Name from XDG icon naming spec
  42  *    media.role                    video, music, game, event, phone, animation, production, filter, abstract, stream
  43  *    event.id                      Name from XDG sound naming spec
  44  *    event.description             "Button blabla clicked" for a11y
  45  *    event.mouse.x
  46  *    event.mouse.y
  47  *    event.mouse.hpos              Float formatted as string in range 0..1
  48  *    event.mouse.vpos              Float formatted as string in range 0..1
  49  *    event.mouse.button            Button number following X11 ordering
  50  *    window.name
  51  *    window.id                     "org.gnome.rhytmbox.MainWindow"
  52  *    window.icon                   Binary blob containing PNG icon data
  53  *    window.icon_name              Name from XDG icon naming spec
  54  *    window.x11.display
  55  *    window.x11.screen
  56  *    window.x11.monitor
  57  *    window.x11.xid
  58  *    application.name              "Rhythmbox Media Player"
  59  *    application.id                "org.gnome.rhythmbox"
  60  *    application.version
  61  *    application.icon              Binary blob containing PNG icon data
  62  *    application.icon_name         Name from XDG icon naming spec
  63  *    application.language
  64  *    application.process.id
  65  *    application.process.binary
  66  *    application.process.user
  67  *    application.process.host
  68  *    application.process.machine_id D-Bus machine ID
  69  *    device.string
  70  *    device.api                    oss, alsa, sunaudio
  71  *    device.description
  72  *    device.bus_path
  73  *    device.serial
  74  *    device.vendor_product_id
  75  *    device.class                  sound, modem, monitor, filter, abstract
  76  *    device.form_factor            laptop-speakers, external-speakers, telephone, tv-capture, webcam-capture, microphone-capture, headset, headphones, hands-free, car, hifi, computer, portable
  77  *    device.connector              isa, pci, usb, firewire, bluetooth
  78  *    device.access_mode            mmap, mmap_rewrite, serial
  79  *    device.master_device
  80  *    device.buffering.buffer_size
  81  *    device.buffering.fragment_size
  82  *    device.profile.name           analog-stereo, analog-surround-40, iec958-stereo, ...
  83  *    device.profile.description    "Analog Stereo", ...
  84  */
  85 #define PA_PROP_MEDIA_NAME                     "media.name"
  86 #define PA_PROP_MEDIA_TITLE                    "media.title"
  87 #define PA_PROP_MEDIA_ARTIST                   "media.artist"
  88 #define PA_PROP_MEDIA_LANGUAGE                 "media.language"
  89 #define PA_PROP_MEDIA_FILENAME                 "media.filename"
  90 #define PA_PROP_MEDIA_ICON                     "media.icon"
  91 #define PA_PROP_MEDIA_ICON_NAME                "media.icon_name"
  92 #define PA_PROP_MEDIA_ROLE                     "media.role"
  93 #define PA_PROP_EVENT_ID                       "event.id"
  94 #define PA_PROP_EVENT_DESCRIPTION              "event.description"
  95 #define PA_PROP_EVENT_MOUSE_X                  "event.mouse.x"
  96 #define PA_PROP_EVENT_MOUSE_Y                  "event.mouse.y"
  97 #define PA_PROP_EVENT_MOUSE_HPOS               "event.mouse.hpos"
  98 #define PA_PROP_EVENT_MOUSE_VPOS               "event.mouse.vpos"
  99 #define PA_PROP_EVENT_MOUSE_BUTTON             "event.mouse.button"
 100 #define PA_PROP_WINDOW_NAME                    "window.name"
 101 #define PA_PROP_WINDOW_ID                      "window.id"
 102 #define PA_PROP_WINDOW_ICON                    "window.icon"
 103 #define PA_PROP_WINDOW_ICON_NAME               "window.icon_name"
 104 #define PA_PROP_WINDOW_X11_DISPLAY             "window.x11.display"
 105 #define PA_PROP_WINDOW_X11_SCREEN              "window.x11.screen"
 106 #define PA_PROP_WINDOW_X11_MONITOR             "window.x11.monitor"
 107 #define PA_PROP_WINDOW_X11_XID                 "window.x11.xid"
 108 #define PA_PROP_APPLICATION_NAME               "application.name"
 109 #define PA_PROP_APPLICATION_ID                 "application.id"
 110 #define PA_PROP_APPLICATION_VERSION            "application.version"
 111 #define PA_PROP_APPLICATION_ICON               "application.icon"
 112 #define PA_PROP_APPLICATION_ICON_NAME          "application.icon_name"
 113 #define PA_PROP_APPLICATION_LANGUAGE           "application.language"
 114 #define PA_PROP_APPLICATION_PROCESS_ID         "application.process.id"
 115 #define PA_PROP_APPLICATION_PROCESS_BINARY     "application.process.binary"
 116 #define PA_PROP_APPLICATION_PROCESS_USER       "application.process.user"
 117 #define PA_PROP_APPLICATION_PROCESS_HOST       "application.process.host"
 118 #define PA_PROP_APPLICATION_PROCESS_MACHINE_ID "application.process.machine_id"
 119 #define PA_PROP_DEVICE_STRING                  "device.string"
 120 #define PA_PROP_DEVICE_API                     "device.api"
 121 #define PA_PROP_DEVICE_DESCRIPTION             "device.description"
 122 #define PA_PROP_DEVICE_BUS_PATH                "device.bus_path"
 123 #define PA_PROP_DEVICE_SERIAL                  "device.serial"
 124 #define PA_PROP_DEVICE_VENDOR_PRODUCT_ID       "device.vendor_product_id"
 125 #define PA_PROP_DEVICE_CLASS                   "device.class"
 126 #define PA_PROP_DEVICE_FORM_FACTOR             "device.form_factor"
 127 #define PA_PROP_DEVICE_CONNECTOR               "device.connector"
 128 #define PA_PROP_DEVICE_ACCESS_MODE             "device.access_mode"
 129 #define PA_PROP_DEVICE_MASTER_DEVICE           "device.master_device"
 130 #define PA_PROP_DEVICE_BUFFERING_BUFFER_SIZE   "device.buffering.buffer_size"
 131 #define PA_PROP_DEVICE_BUFFERING_FRAGMENT_SIZE "device.buffering.fragment_size"
 132 #define PA_PROP_DEVICE_PROFILE_NAME            "device.profile.name"
 133 #define PA_PROP_DEVICE_PROFILE_DESCRIPTION     "device.profile.description"
 134 #define PA_PROP_MODULE_AUTHOR                  "module.author"
 135 #define PA_PROP_MODULE_DESCRIPTION             "module.description"
 136 #define PA_PROP_MODULE_USAGE                   "module.usage"
 137 #define PA_PROP_MODULE_VERSION                 "module.version"
 138
 139 /** A property list object. Basically a dictionary with ASCII strings
 140  * as keys and arbitrary data as values. \since 0.9.11 */
 141 typedef struct pa_proplist pa_proplist;
 142
 143 /** Allocate a property list. \since 0.9.11 */
 144 pa_proplist* pa_proplist_new(void);
 145
 146 /** Free the property list. \since 0.9.11 */
 147 void pa_proplist_free(pa_proplist* p);
 148
 149 /** Append a new string 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. Will accept only valid
 152  * UTF-8. \since 0.9.11 */
 153 int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
 154
 155 /** Append a new string entry to the property list, possibly
 156  * overwriting an already existing entry with the same key. An
 157  * internal copy of the data passed is made. Will accept only valid
 158  * UTF-8. The data can be passed as printf()-style format string with
 159  * arguments. \since 0.9.11 */
 160 int pa_proplist_setf(pa_proplist *p, const char *key, const char *format, ...) PA_GCC_PRINTF_ATTR(3,4);
 161
 162 /** Append a new arbitrary data entry to the property list, possibly
 163  * overwriting an already existing entry with the same key. An
 164  * internal copy of the data passed is made. \since 0.9.11 */
 165 int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nbytes);
 166
 167 /** Return a string entry for the specified key. Will return NULL if
 168  * the data is not valid UTF-8. Will return a NUL-terminated string in
 169  * an internally allocated buffer. The caller should make a copy of
 170  * the data before accessing the property list again. \since 0.9.11 */
 171 const char *pa_proplist_gets(pa_proplist *p, const char *key);
 172
 173 /** Return the the value for the specified key. Will return a
 174  * NUL-terminated string for string entries. The pointer returned will
 175  * point to an internally allocated buffer. The caller should make a
 176  * copy of the data before the property list is accessed again. \since
 177  * 0.9.11 */
 178 int pa_proplist_get(pa_proplist *p, const char *key, const void **data, size_t *nbytes);
 179
 180 /** Update mode enum for pa_proplist_update(). \since 0.9.11 */
 181 typedef enum pa_update_mode {
 182     PA_UPDATE_SET,
 183     /*< Replace the entirey property list with the new one. Don't keep
 184      *  any of the old data around */
 185
 186     PA_UPDATE_MERGE,
 187     /*< Merge new property list into the existing one, not replacing
 188      *  any old entries if they share a common key with the new
 189      *  property list. */
 190
 191     PA_UPDATE_REPLACE
 192     /*< Merge new property list into the existing one, replacing all
 193      *  old entries that share a common key with the new property
 194      *  list. */
 195 } pa_update_mode_t;
 196
 197 /** \cond fulldocs */
 198 #define PA_UPDATE_SET PA_UPDATE_SET
 199 #define PA_UPDATE_MERGE PA_UPDATE_MERGE
 200 #define PA_UPDATE_REPLACE PA_UPDATE_REPLACE
 201 /** \endcond */
 202
 203 /** Merge property list "other" into "p", adhering the merge mode as
 204  * specified in "mode". \since 0.9.11 */
 205 void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, pa_proplist *other);
 206
 207 /** Removes a single entry from the property list, identified be the
 208  * specified key name. \since 0.9.11 */
 209 int pa_proplist_unset(pa_proplist *p, const char *key);
 210
 211 /** Similar to pa_proplist_remove() but takes an array of keys to
 212  * remove. The array should be terminated by a NULL pointer. Return -1
 213  * on failure, otherwise the number of entries actually removed (which
 214  * might even be 0, if there where no matching entries to
 215  * remove). \since 0.9.11 */
 216 int pa_proplist_unset_many(pa_proplist *p, const char * const keys[]);
 217
 218 /** Iterate through the property list. The user should allocate a
 219  * state variable of type void* and initialize it with NULL. A pointer
 220  * to this variable should then be passed to pa_proplist_iterate()
 221  * which should be called in a loop until it returns NULL which
 222  * signifies EOL. The property list should not be modified during
 223  * iteration through the list -- except for deleting the current
 224  * looked at entry. On each invication this function will return the
 225  * key string for the next entry. The keys in the property list do not
 226  * have any particular order. \since 0.9.11 */
 227 const char *pa_proplist_iterate(pa_proplist *p, void **state);
 228
 229 /** Format the property list nicely as a human readable string. This
 230  * works very much like pa_proplist_to_string_sep() and uses a newline
 231  * as seperator and appends one final one. Call pa_xfree() on the
 232  * result. \since 0.9.11 */
 233 char *pa_proplist_to_string(pa_proplist *p);
 234
 235 /** Format the property list nicely as a human readable string and
 236  * choose the seperator. Call pa_xfree() on the result. \since
 237  * 0.9.15 */
 238 char *pa_proplist_to_string_sep(pa_proplist *p, const char *sep);
 239
 240 /** Allocate a new property list and assign key/value from a human
 241  * readable string. \since 0.9.15 */
 242 pa_proplist *pa_proplist_from_string(const char *str);
 243
 244   /** Returns 1 if an entry for the specified key is existant in the
 245  * property list. \since 0.9.11 */
 246 int pa_proplist_contains(pa_proplist *p, const char *key);
 247
 248 /** Remove all entries from the property list object. \since 0.9.11 */
 249 void pa_proplist_clear(pa_proplist *p);
 250
 251 /** Allocate a new property list and copy over every single entry from
 252  * the specific list. \since 0.9.11 */
 253 pa_proplist* pa_proplist_copy(pa_proplist *t);
 254
 255 /** Return the number of entries on the property list. \since 0.9.15 */
 256 unsigned pa_proplist_size(pa_proplist *t);
 257
 258 /** Returns 0 when the proplist is empty, positive otherwise \since 0.9.15 */
 259 int pa_proplist_isempty(pa_proplist *t);
 260
 261 PA_C_DECL_END
 262
 263 #endif