#include <pulse/gccmacro.h>
#include <pulse/version.h>
+/** \file
+ * Property list constants and functions */
+
PA_C_DECL_BEGIN
/** For streams: localized media name, formatted as UTF-8. e.g. "Guns'N'Roses: Civil War".*/
#define PA_PROP_MEDIA_ROLE "media.role"
/** 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 */
-#define PA_PROP_FILTER_WANT "filter.want"
+#define PA_PROP_FILTER_WANT "filter.want"
/** 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 */
-#define PA_PROP_FILTER_APPLY "filter.apply"
+#define PA_PROP_FILTER_APPLY "filter.apply"
/** 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 it's own, internal AEC) \since 1.0 */
-#define PA_PROP_FILTER_SUPPRESS "filter.suppress"
+#define PA_PROP_FILTER_SUPPRESS "filter.suppress"
/** For event sound streams: XDG event sound name. e.g. "message-new-email" (Event sound streams are those with media.role set to "event") */
#define PA_PROP_EVENT_ID "event.id"
/** 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 */
#define PA_PROP_WINDOW_VPOS "window.vpos"
-/** 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 */
+/** 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 */
#define PA_PROP_WINDOW_DESKTOP "window.desktop"
/** For streams that belong to an X11 window on the screen: the X11 display string. e.g. ":0.0" */
/** For devices: profile identifier for the profile this devices is in. e.g. "analog-stereo", "analog-surround-40", "iec958-stereo", ...*/
#define PA_PROP_DEVICE_PROFILE_NAME "device.profile.name"
-/** 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 */
+/** 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 */
#define PA_PROP_DEVICE_INTENDED_ROLES "device.intended_roles"
/** For devices: human readable one-line description of the profile this device is in. e.g. "Analog Stereo", ... */
* the data before accessing the property list again. \since 0.9.11 */
const char *pa_proplist_gets(pa_proplist *p, const char *key);
-/** Return the the value for the specified key. Will return a
+/** Return the value for the specified key. Will return a
* NUL-terminated string for string entries. The pointer returned will
* point to an internally allocated buffer. The caller should make a
* copy of the data before the property list is accessed again. \since
typedef enum pa_update_mode {
PA_UPDATE_SET
/**< Replace the entire property list with the new one. Don't keep
- * any of the old data around */,
+ * any of the old data around. */,
PA_UPDATE_MERGE
/**< Merge new property list into the existing one, not replacing
int pa_proplist_unset(pa_proplist *p, const char *key);
/** Similar to pa_proplist_unset() but takes an array of keys to
- * remove. The array should be terminated by a NULL pointer. Return -1
+ * remove. The array should be terminated by a NULL pointer. Returns -1
* on failure, otherwise the number of entries actually removed (which
- * might even be 0, if there where no matching entries to
+ * might even be 0, if there were no matching entries to
* remove). \since 0.9.11 */
int pa_proplist_unset_many(pa_proplist *p, const char * const keys[]);
* to this variable should then be passed to pa_proplist_iterate()
* which should be called in a loop until it returns NULL which
* signifies EOL. The property list should not be modified during
- * iteration through the list -- except for deleting the current
- * looked at entry. On each invication this function will return the
+ * iteration through the list -- with the exception of deleting the
+ * current entry. On each invocation this function will return the
* key string for the next entry. The keys in the property list do not
* have any particular order. \since 0.9.11 */
const char *pa_proplist_iterate(pa_proplist *p, void **state);
/** Format the property list nicely as a human readable string. This
* works very much like pa_proplist_to_string_sep() and uses a newline
- * as seperator and appends one final one. Call pa_xfree() on the
+ * as separator and appends one final one. Call pa_xfree() on the
* result. \since 0.9.11 */
char *pa_proplist_to_string(pa_proplist *p);
/** Format the property list nicely as a human readable string and
- * choose the seperator. Call pa_xfree() on the result. \since
+ * choose the separator. Call pa_xfree() on the result. \since
* 0.9.15 */
char *pa_proplist_to_string_sep(pa_proplist *p, const char *sep);
* readable string. \since 0.9.15 */
pa_proplist *pa_proplist_from_string(const char *str);
-/** Returns 1 if an entry for the specified key is existant in the
+/** Returns 1 if an entry for the specified key exists in the
* property list. \since 0.9.11 */
int pa_proplist_contains(pa_proplist *p, const char *key);
/** Allocate a new property list and copy over every single entry from
* the specific list. \since 0.9.11 */
-pa_proplist* pa_proplist_copy(pa_proplist *t);
+pa_proplist* pa_proplist_copy(pa_proplist *p);
-/** Return the number of entries on the property list. \since 0.9.15 */
-unsigned pa_proplist_size(pa_proplist *t);
+/** Return the number of entries in the property list. \since 0.9.15 */
+unsigned pa_proplist_size(pa_proplist *p);
/** Returns 0 when the proplist is empty, positive otherwise \since 0.9.15 */
-int pa_proplist_isempty(pa_proplist *t);
+int pa_proplist_isempty(pa_proplist *p);
/** Return non-zero when a and b have the same keys and values.
* \since 0.9.16 */