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