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 /** For streams: localized media name, formatted as UTF-8. e.g. "Guns'N'Roses: Civil War".*/
  34 #define PA_PROP_MEDIA_NAME                     "media.name"
  35
  36 /** For streams: localized media title if applicable, formatted as UTF-8. e.g. "Civil War" */
  37 #define PA_PROP_MEDIA_TITLE                    "media.title"
  38
  39 /** For streams: localized media artist if applicable, formatted as UTF-8. e.g. "Guns'N'Roses" */
  40 #define PA_PROP_MEDIA_ARTIST                   "media.artist"
  41
  42 /** For streams: localized media copyright string if applicable, formatted as UTF-8. e.g. "Evil Record Corp." */
  43 #define PA_PROP_MEDIA_COPYRIGHT                "media.copyright"
  44
  45 /** For streams: localized media generator software string if applicable, formatted as UTF-8. e.g. "Foocrop AudioFrobnicator" */
  46 #define PA_PROP_MEDIA_SOFTWARE                 "media.software"
  47
  48 /** For streams: media language if applicable, in standard POSIX format. e.g. "de_DE" */
  49 #define PA_PROP_MEDIA_LANGUAGE                 "media.language"
  50
  51 /** For streams: source filename if applicable, in URI format or local path. e.g. "/home/lennart/music/foobar.ogg" */
  52 #define PA_PROP_MEDIA_FILENAME                 "media.filename"
  53
  54 /** \cond fulldocs */
  55 /** For streams: icon for the media. A binary blob containing PNG image data */
  56 #define PA_PROP_MEDIA_ICON                     "media.icon"
  57 /** \endcond */
  58
  59 /** For streams: an XDG icon name for the media. e.g. "audio-x-mp3" */
  60 #define PA_PROP_MEDIA_ICON_NAME                "media.icon_name"
  61
  62 /** For streams: logic role of this media. One of the strings "video", "music", "game", "event", "phone", "animation", "production", "a11y", "test" */
  63 #define PA_PROP_MEDIA_ROLE                     "media.role"
  64
  65 /** For event sound streams: XDG event sound name. e.g. "message-new-email" (Event sound streams are those with media.role set to "event") */
  66 #define PA_PROP_EVENT_ID                       "event.id"
  67
  68 /** For event sound streams: localized human readable one-line description of the event, formatted as UTF-8. e.g. "Email from lennart@example.com received." */
  69 #define PA_PROP_EVENT_DESCRIPTION              "event.description"
  70
  71 /** For event sound streams: absolute horizontal mouse position on the screen if the event sound was triggered by a mouse click, integer formatted as text string. e.g. "865" */
  72 #define PA_PROP_EVENT_MOUSE_X                  "event.mouse.x"
  73
  74 /** For event sound streams: absolute vertical mouse position on the screen if the event sound was triggered by a mouse click, integer formatted as text string. e.g. "432" */
  75 #define PA_PROP_EVENT_MOUSE_Y                  "event.mouse.y"
  76
  77 /** For event sound streams: relative horizontal mouse position on the screen if the event sound was triggered by a mouse click, float formatted as text string, ranging from 0.0 (left side of the screen) to 1.0 (right side of the screen). e.g. "0.65" */
  78 #define PA_PROP_EVENT_MOUSE_HPOS               "event.mouse.hpos"
  79
  80 /** For event sound streams: relative vertical mouse position on the screen if the event sound was triggered by a mouse click, float formatted as text string, ranging from 0.0 (top of the screen) to 1.0 (bottom of the screen). e.g. "0.43" */
  81 #define PA_PROP_EVENT_MOUSE_VPOS               "event.mouse.vpos"
  82
  83 /** For event sound streams: mouse button that triggered the event if applicable, integer formatted as string with 0=left, 1=middle, 2=right. e.g. "0" */
  84 #define PA_PROP_EVENT_MOUSE_BUTTON             "event.mouse.button"
  85
  86 /** For streams that belong to a window on the screen: localized window title. e.g. "Totem Music Player" */
  87 #define PA_PROP_WINDOW_NAME                    "window.name"
  88
  89 /** For streams that belong to a window on the screen: a textual id for identifying a window logically. e.g. "org.gnome.Totem.MainWindow" */
  90 #define PA_PROP_WINDOW_ID                      "window.id"
  91
  92 /** \cond fulldocs */
  93 /** For streams that belong to a window on the screen: window icon. A binary blob containing PNG image data */
  94 #define PA_PROP_WINDOW_ICON                    "window.icon"
  95 /** \endcond */
  96
  97 /** For streams that belong to a window on the screen: an XDG icon name for the window. e.g. "totem" */
  98 #define PA_PROP_WINDOW_ICON_NAME               "window.icon_name"
  99
 100 /** For streams that belong to a window on the screen: absolute horizontal window position on the screen, integer formatted as text string. e.g. "865". \since 0.9.17 */
 101 #define PA_PROP_WINDOW_X                       "window.x"
 102
 103 /** For streams that belong to a window on the screen: absolute vertical window position on the screen, integer formatted as text string. e.g. "343". \since 0.9.17 */
 104 #define PA_PROP_WINDOW_Y                       "window.y"
 105
 106 /** For streams that belong to a window on the screen: window width on the screen, integer formatted as text string. e.g. "365". \since 0.9.17 */
 107 #define PA_PROP_WINDOW_WIDTH                   "window.width"
 108
 109 /** For streams that belong to a window on the screen: window height on the screen, integer formatted as text string. e.g. "643". \since 0.9.17 */
 110 #define PA_PROP_WINDOW_HEIGHT                  "window.height"
 111
 112 /** For streams that belong to a window on the screen: relative position of the window center on the screen, float formatted as text string, ranging from 0.0 (left side of the screen) to 1.0 (right side of the screen). e.g. "0.65". \since 0.9.17 */
 113 #define PA_PROP_WINDOW_HPOS                    "window.hpos"
 114
 115 /** For streams that belong to a window on the screen: relative position of the window center on the screen, float formatted as text string, ranging from 0.0 (top of the screen) to 1.0 (bottom of the screen). e.g. "0.43". \since 0.9.17 */
 116 #define PA_PROP_WINDOW_VPOS                    "window.vpos"
 117
 118 /** For streams that belong to a window on the screen: if the windowing system supports multiple desktops, a comma seperated list of indexes of the desktops this window is visible on. If this property is an empty string, it is visible on all desktops (i.e. 'sticky'). The first desktop is 0. e.g. "0,2,3" \since 0.9.18 */
 119 #define PA_PROP_WINDOW_DESKTOP                 "window.desktop"
 120
 121 /** For streams that belong to an X11 window on the screen: the X11 display string. e.g. ":0.0" */
 122 #define PA_PROP_WINDOW_X11_DISPLAY             "window.x11.display"
 123
 124 /** For streams that belong to an X11 window on the screen: the X11 screen the window is on, an integer formatted as string. e.g. "0" */
 125 #define PA_PROP_WINDOW_X11_SCREEN              "window.x11.screen"
 126
 127 /** For streams that belong to an X11 window on the screen: the X11 monitor the window is on, an integer formatted as string. e.g. "0" */
 128 #define PA_PROP_WINDOW_X11_MONITOR             "window.x11.monitor"
 129
 130 /** For streams that belong to an X11 window on the screen: the window XID, an integer formatted as string. e.g. "25632" */
 131 #define PA_PROP_WINDOW_X11_XID                 "window.x11.xid"
 132
 133 /** For clients/streams: localized human readable application name. e.g. "Totem Music Player" */
 134 #define PA_PROP_APPLICATION_NAME               "application.name"
 135
 136 /** For clients/streams: a textual id for identifying an application logically. e.g. "org.gnome.Totem" */
 137 #define PA_PROP_APPLICATION_ID                 "application.id"
 138
 139 /** For clients/streams: a version string e.g. "0.6.88" */
 140 #define PA_PROP_APPLICATION_VERSION            "application.version"
 141
 142 /** \cond fulldocs */
 143 /** For clients/streams: application icon. A binary blob containing PNG image data */
 144 #define PA_PROP_APPLICATION_ICON               "application.icon"
 145 /** \endcond */
 146
 147 /** For clients/streams: an XDG icon name for the application. e.g. "totem" */
 148 #define PA_PROP_APPLICATION_ICON_NAME          "application.icon_name"
 149
 150 /** For clients/streams: application language if applicable, in standard POSIX format. e.g. "de_DE" */
 151 #define PA_PROP_APPLICATION_LANGUAGE           "application.language"
 152
 153 /** For clients/streams on UNIX: application process PID, an integer formatted as string. e.g. "4711" */
 154 #define PA_PROP_APPLICATION_PROCESS_ID         "application.process.id"
 155
 156 /** For clients/streams: application process name. e.g. "totem" */
 157 #define PA_PROP_APPLICATION_PROCESS_BINARY     "application.process.binary"
 158
 159 /** For clients/streams: application user name. e.g. "lennart" */
 160 #define PA_PROP_APPLICATION_PROCESS_USER       "application.process.user"
 161
 162 /** For clients/streams: host name the application runs on. e.g. "omega" */
 163 #define PA_PROP_APPLICATION_PROCESS_HOST       "application.process.host"
 164
 165 /** For clients/streams: the D-Bus host id the application runs on. e.g. "543679e7b01393ed3e3e650047d78f6e" */
 166 #define PA_PROP_APPLICATION_PROCESS_MACHINE_ID "application.process.machine_id"
 167
 168 /** For clients/streams: an id for the login session the application runs in. On Unix the value of $XDG_SESSION_COOKIE. e.g. "543679e7b01393ed3e3e650047d78f6e-1235159798.76193-190367717" */
 169 #define PA_PROP_APPLICATION_PROCESS_SESSION_ID "application.process.session_id"
 170
 171 /** For devices: device string in the underlying audio layer's format. e.g. "surround51:0" */
 172 #define PA_PROP_DEVICE_STRING                  "device.string"
 173
 174 /** For devices: API this device is access with. e.g. "alsa" */
 175 #define PA_PROP_DEVICE_API                     "device.api"
 176
 177 /** For devices: localized human readable device one-line description, e.g. "Foobar Industries USB Headset 2000+ Ultra" */
 178 #define PA_PROP_DEVICE_DESCRIPTION             "device.description"
 179
 180 /** For devices: bus path to the device in the OS' format. e.g. "/sys/bus/pci/devices/0000:00:1f.2" */
 181 #define PA_PROP_DEVICE_BUS_PATH                "device.bus_path"
 182
 183 /** For devices: serial number if applicable. e.g. "4711-0815-1234" */
 184 #define PA_PROP_DEVICE_SERIAL                  "device.serial"
 185
 186 /** For devices: vendor ID if applicable. e.g. 1274 */
 187 #define PA_PROP_DEVICE_VENDOR_ID               "device.vendor.id"
 188
 189 /** For devices: vendor name if applicable. e.g. "Foocorp Heavy Industries" */
 190 #define PA_PROP_DEVICE_VENDOR_NAME             "device.vendor.name"
 191
 192 /** For devices: product ID if applicable. e.g. 4565 */
 193 #define PA_PROP_DEVICE_PRODUCT_ID              "device.product.id"
 194
 195 /** For devices: product name if applicable. e.g. "SuperSpeakers 2000 Pro" */
 196 #define PA_PROP_DEVICE_PRODUCT_NAME            "device.product.name"
 197
 198 /** For devices: device class. One of "sound", "modem", "monitor", "filter" */
 199 #define PA_PROP_DEVICE_CLASS                   "device.class"
 200
 201 /** For devices: form factor if applicable. One of "internal", "speaker", "handset", "tv", "webcam", "microphone", "headset", "headphone", "hands-free", "car", "hifi", "computer", "portable" */
 202 #define PA_PROP_DEVICE_FORM_FACTOR             "device.form_factor"
 203
 204 /** For devices: bus of the device if applicable. One of "isa", "pci", "usb", "firewire", "bluetooth" */
 205 #define PA_PROP_DEVICE_BUS                     "device.bus"
 206
 207 /** \cond fulldocs */
 208 /** For devices: icon for the device. A binary blob containing PNG image data */
 209 #define PA_PROP_DEVICE_ICON                    "device.icon"
 210 /** \endcond */
 211
 212 /** For devices: an XDG icon name for the device. e.g. "sound-card-speakers-usb" */
 213 #define PA_PROP_DEVICE_ICON_NAME               "device.icon_name"
 214
 215 /** For devices: access mode of the device if applicable. One of "mmap", "mmap_rewrite", "serial" */
 216 #define PA_PROP_DEVICE_ACCESS_MODE             "device.access_mode"
 217
 218 /** For filter devices: master device id if applicable. */
 219 #define PA_PROP_DEVICE_MASTER_DEVICE           "device.master_device"
 220
 221 /** For devices: buffer size in bytes, integer formatted as string. */
 222 #define PA_PROP_DEVICE_BUFFERING_BUFFER_SIZE   "device.buffering.buffer_size"
 223
 224 /** For devices: fragment size in bytes, integer formatted as string. */
 225 #define PA_PROP_DEVICE_BUFFERING_FRAGMENT_SIZE "device.buffering.fragment_size"
 226
 227 /** For devices: profile identifier for the profile this devices is in. e.g. "analog-stereo", "analog-surround-40", "iec958-stereo", ...*/
 228 #define PA_PROP_DEVICE_PROFILE_NAME            "device.profile.name"
 229
 230 /** For devices: intended use. A comma seperated list of roles (see PA_PROP_MEDIA_ROLE) this device is particularly well suited for, due to latency, quality or form factor. \since 0.9.16 */
 231 #define PA_PROP_DEVICE_INTENDED_ROLES          "device.intended_roles"
 232
 233 /** For devices: human readable one-line description of the profile this device is in. e.g. "Analog Stereo", ... */
 234 #define PA_PROP_DEVICE_PROFILE_DESCRIPTION     "device.profile.description"
 235
 236 /** For modules: the author's name, formatted as UTF-8 string. e.g. "Lennart Poettering" */
 237 #define PA_PROP_MODULE_AUTHOR                  "module.author"
 238
 239 /** For modules: a human readable one-line description of the module's purpose formatted as UTF-8. e.g. "Frobnicate sounds with a flux compensator" */
 240 #define PA_PROP_MODULE_DESCRIPTION             "module.description"
 241
 242 /** For modules: a human readable usage description of the module's arguments formatted as UTF-8. */
 243 #define PA_PROP_MODULE_USAGE                   "module.usage"
 244
 245 /** For modules: a version string for the module. e.g. "0.9.15" */
 246 #define PA_PROP_MODULE_VERSION                 "module.version"
 247
 248 /** A property list object. Basically a dictionary with ASCII strings
 249  * as keys and arbitrary data as values. \since 0.9.11 */
 250 typedef struct pa_proplist pa_proplist;
 251
 252 /** Allocate a property list. \since 0.9.11 */
 253 pa_proplist* pa_proplist_new(void);
 254
 255 /** Free the property list. \since 0.9.11 */
 256 void pa_proplist_free(pa_proplist* p);
 257
 258 /** Append a new string entry to the property list, possibly
 259  * overwriting an already existing entry with the same key. An
 260  * internal copy of the data passed is made. Will accept only valid
 261  * UTF-8. \since 0.9.11 */
 262 int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
 263
 264 /** Append a new string entry to the property list, possibly
 265  * overwriting an already existing entry with the same key. An
 266  * internal copy of the data passed is made. Will accept only valid
 267  * UTF-8. The string passed in must contain a '='. Left hand side of
 268  * the '=' is used as key name, the right hand side as string
 269  * data. \since 0.9.16 */
 270 int pa_proplist_setp(pa_proplist *p, const char *pair);
 271
 272 /** Append a new string entry to the property list, possibly
 273  * overwriting an already existing entry with the same key. An
 274  * internal copy of the data passed is made. Will accept only valid
 275  * UTF-8. The data can be passed as printf()-style format string with
 276  * arguments. \since 0.9.11 */
 277 int pa_proplist_setf(pa_proplist *p, const char *key, const char *format, ...) PA_GCC_PRINTF_ATTR(3,4);
 278
 279 /** Append a new arbitrary data entry to the property list, possibly
 280  * overwriting an already existing entry with the same key. An
 281  * internal copy of the data passed is made. \since 0.9.11 */
 282 int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nbytes);
 283
 284 /** Return a string entry for the specified key. Will return NULL if
 285  * the data is not valid UTF-8. Will return a NUL-terminated string in
 286  * an internally allocated buffer. The caller should make a copy of
 287  * the data before accessing the property list again. \since 0.9.11 */
 288 const char *pa_proplist_gets(pa_proplist *p, const char *key);
 289
 290 /** Return the the value for the specified key. Will return a
 291  * NUL-terminated string for string entries. The pointer returned will
 292  * point to an internally allocated buffer. The caller should make a
 293  * copy of the data before the property list is accessed again. \since
 294  * 0.9.11 */
 295 int pa_proplist_get(pa_proplist *p, const char *key, const void **data, size_t *nbytes);
 296
 297 /** Update mode enum for pa_proplist_update(). \since 0.9.11 */
 298 typedef enum pa_update_mode {
 299     PA_UPDATE_SET
 300     /**< Replace the entire property list with the new one. Don't keep
 301      *  any of the old data around */,
 302
 303     PA_UPDATE_MERGE
 304     /**< Merge new property list into the existing one, not replacing
 305      *  any old entries if they share a common key with the new
 306      *  property list. */,
 307
 308     PA_UPDATE_REPLACE
 309     /**< Merge new property list into the existing one, replacing all
 310      *  old entries that share a common key with the new property
 311      *  list. */
 312 } pa_update_mode_t;
 313
 314 /** \cond fulldocs */
 315 #define PA_UPDATE_SET PA_UPDATE_SET
 316 #define PA_UPDATE_MERGE PA_UPDATE_MERGE
 317 #define PA_UPDATE_REPLACE PA_UPDATE_REPLACE
 318 /** \endcond */
 319
 320 /** Merge property list "other" into "p", adhering the merge mode as
 321  * specified in "mode". \since 0.9.11 */
 322 void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, pa_proplist *other);
 323
 324 /** Removes a single entry from the property list, identified be the
 325  * specified key name. \since 0.9.11 */
 326 int pa_proplist_unset(pa_proplist *p, const char *key);
 327
 328 /** Similar to pa_proplist_unset() but takes an array of keys to
 329  * remove. The array should be terminated by a NULL pointer. Return -1
 330  * on failure, otherwise the number of entries actually removed (which
 331  * might even be 0, if there where no matching entries to
 332  * remove). \since 0.9.11 */
 333 int pa_proplist_unset_many(pa_proplist *p, const char * const keys[]);
 334
 335 /** Iterate through the property list. The user should allocate a
 336  * state variable of type void* and initialize it with NULL. A pointer
 337  * to this variable should then be passed to pa_proplist_iterate()
 338  * which should be called in a loop until it returns NULL which
 339  * signifies EOL. The property list should not be modified during
 340  * iteration through the list -- except for deleting the current
 341  * looked at entry. On each invication this function will return the
 342  * key string for the next entry. The keys in the property list do not
 343  * have any particular order. \since 0.9.11 */
 344 const char *pa_proplist_iterate(pa_proplist *p, void **state);
 345
 346 /** Format the property list nicely as a human readable string. This
 347  * works very much like pa_proplist_to_string_sep() and uses a newline
 348  * as seperator and appends one final one. Call pa_xfree() on the
 349  * result. \since 0.9.11 */
 350 char *pa_proplist_to_string(pa_proplist *p);
 351
 352 /** Format the property list nicely as a human readable string and
 353  * choose the seperator. Call pa_xfree() on the result. \since
 354  * 0.9.15 */
 355 char *pa_proplist_to_string_sep(pa_proplist *p, const char *sep);
 356
 357 /** Allocate a new property list and assign key/value from a human
 358  * readable string. \since 0.9.15 */
 359 pa_proplist *pa_proplist_from_string(const char *str);
 360
 361 /** Returns 1 if an entry for the specified key is existant in the
 362  * property list. \since 0.9.11 */
 363 int pa_proplist_contains(pa_proplist *p, const char *key);
 364
 365 /** Remove all entries from the property list object. \since 0.9.11 */
 366 void pa_proplist_clear(pa_proplist *p);
 367
 368 /** Allocate a new property list and copy over every single entry from
 369  * the specific list. \since 0.9.11 */
 370 pa_proplist* pa_proplist_copy(pa_proplist *t);
 371
 372 /** Return the number of entries on the property list. \since 0.9.15 */
 373 unsigned pa_proplist_size(pa_proplist *t);
 374
 375 /** Returns 0 when the proplist is empty, positive otherwise \since 0.9.15 */
 376 int pa_proplist_isempty(pa_proplist *t);
 377
 378 /** Return non-zero when a and b have the same keys and values.
 379  * \since 0.9.16 */
 380 int pa_proplist_equal(pa_proplist *a, pa_proplist *b);
 381
 382 PA_C_DECL_END
 383
 384 #endif