]>
code.delx.au - pulseaudio/blob - src/pulse/proplist.h
8f44df277656b1cd9718405a14e355d1157d53dc
1 #ifndef foopulseproplisthfoo
2 #define foopulseproplisthfoo
5 This file is part of PulseAudio.
7 Copyright 2007 Lennart Poettering
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.
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.
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
25 #include <sys/types.h>
27 #include <pulse/cdecl.h>
28 #include <pulse/gccmacro.h>
32 /* Defined properties:
34 * media.name "Guns'N'Roses: Civil War"
35 * media.title "Civil War"
36 * media.artist "Guns'N'Roses"
37 * media.language "de_DE"
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
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
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
57 * application.name "Rhythmbox Media Player"
58 * application.id "org.gnome.rhythmbox"
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
68 * device.api oss, alsa, sunaudio
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", ...
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"
132 /** A property list object. Basically a dictionary with UTF-8 strings
133 * as keys and arbitrary data as values. \since 0.9.11 */
134 typedef struct pa_proplist pa_proplist
;
136 /** Allocate a property list. \since 0.9.11 */
137 pa_proplist
* pa_proplist_new(void);
139 /** Free the property list. \since 0.9.11 */
140 void pa_proplist_free(pa_proplist
* p
);
142 /** Append a new string entry to the property list, possibly
143 * overwriting an already existing entry with the same key. An
144 * internal copy of the data passed is made. Will accept only valid
145 * UTF-8. \since 0.9.11 */
146 int pa_proplist_sets(pa_proplist
*p
, const char *key
, const char *value
);
148 /** Append a new string entry to the property list, possibly
149 * overwriting an already existing entry with the same key. An
150 * internal copy of the data passed is made. Will accept only valid
151 * UTF-8. The data can be passed as printf()-style format string with
152 * arguments. \since 0.9.11 */
153 int pa_proplist_setf(pa_proplist
*p
, const char *key
, const char *format
, ...) PA_GCC_PRINTF_ATTR(3,4);
155 /** Append a new arbitrary data 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. \since 0.9.11 */
158 int pa_proplist_set(pa_proplist
*p
, const char *key
, const void *data
, size_t nbytes
);
160 /* Return a string entry for the specified key. Will return NULL if
161 * the data is not valid UTF-8. Will return a NUL-terminated string in
162 * an internally allocated buffer. The caller should make a copy of
163 * the data before accessing the property list again. \since 0.9.11 */
164 const char *pa_proplist_gets(pa_proplist
*p
, const char *key
);
166 /** Return the the value for the specified key. Will return a
167 * NUL-terminated string for string entries. The pointer returned will
168 * point to an internally allocated buffer. The caller should make a
169 * copy of the data before the property list is accessed again. \since
171 int pa_proplist_get(pa_proplist
*p
, const char *key
, const void **data
, size_t *nbytes
);
173 /** Update mode enum for pa_proplist_update(). \since 0.9.11 */
174 typedef enum pa_update_mode
{
176 /*< Replace the entirey property list with the new one. Don't keep
177 * any of the old data around */
180 /*< Merge new property list into the existing one, not replacing
181 * any old entries if they share a common key with the new
185 /*< Merge new property list into the existing one, replacing all
186 * old entries that share a common key with the new property
190 /** Merge property list "other" into "p", adhering the merge mode as
191 * specified in "mode". \since 0.9.11 */
192 void pa_proplist_update(pa_proplist
*p
, pa_update_mode_t mode
, pa_proplist
*other
);
194 /** Removes a single entry from the property list, identified be the
195 * specified key name. \since 0.9.11 */
196 int pa_proplist_unset(pa_proplist
*p
, const char *key
);
198 /** Similar to pa_proplist_remove() but takes an array of keys to
199 * remove. The array should be terminated by a NULL pointer. Return -1
200 * on failure, otherwise the number of entries actually removed (which
201 * might even be 0, if there where no matching entries to
202 * remove). \since 0.9.11 */
203 int pa_proplist_unset_many(pa_proplist
*p
, const char * const keys
[]);
205 /** Iterate through the property list. The user should allocate a
206 * state variable of type void* and initialize it with NULL. A pointer
207 * to this variable should then be passed to pa_proplist_iterate()
208 * which should be called in a loop until it returns NULL which
209 * signifies EOL. The property list should not be modified during
210 * iteration through the list -- except for deleting the current
211 * looked at entry. On each invication this function will return the
212 * key string for the next entry. The keys in the property list do not
213 * have any particular order. \since 0.9.11 */
214 const char *pa_proplist_iterate(pa_proplist
*p
, void **state
);
216 /** Format the property list nicely as a human readable string. This
217 * works very much like pa_proplist_to_string_sep() and uses a newline
218 * as seperator and appends one final one. Call pa_xfree() on the
219 * result. \since 0.9.11 */
220 char *pa_proplist_to_string(pa_proplist
*p
);
222 /** Format the property list nicely as a human readable string and
223 * choose the seperator. Call pa_xfree() on the result. \since
225 char *pa_proplist_to_string_sep(pa_proplist
*p
, const char *sep
);
227 /** Allocate a new property list and assign key/value from a human
228 * readable string. \since 0.9.15 */
229 pa_proplist
*pa_proplist_from_string(const char *str
);
231 /** Returns 1 if an entry for the specified key is existant in the
232 * property list. \since 0.9.11 */
233 int pa_proplist_contains(pa_proplist
*p
, const char *key
);
235 /** Remove all entries from the property list object. \since 0.9.11 */
236 void pa_proplist_clear(pa_proplist
*p
);
238 /** Allocate a new property list and copy over every single entry from
239 * the specific list. \since 0.9.11 */
240 pa_proplist
* pa_proplist_copy(pa_proplist
*t
);
242 /** Return the number of entries on the property list. \since 0.9.15 */
243 unsigned pa_proplist_size(pa_proplist
*t
);
245 /** Returns 0 when the proplist is empty, positive otherwise \since 0.9.15 */
246 int pa_proplist_isempty(pa_proplist
*t
);