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