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