From: Peter Meerwald <p.meerwald@xxxxxxxxxxxxxxxxxx>
ATTENTION: pa_proplist_unset() and pa_proplist_contains() have unconventional
return codes (-2/-1/0) and -1/0/1, resp.); this aims to document the current
behaviour, however, it might as well be a bug...
---
src/pulse/proplist.h | 13 ++++++++-----
1 files changed, 8 insertions(+), 5 deletions(-)
diff --git a/src/pulse/proplist.h b/src/pulse/proplist.h
index b95cfc9..de48634 100644
--- a/src/pulse/proplist.h
+++ b/src/pulse/proplist.h
@@ -311,8 +311,8 @@ int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nb
* 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
- * NUL-terminated string for string entries. The pointer returned will
+/** Store the value for the specified key in \a data. Will store a
+ * NUL-terminated string for string entries. The \a data pointer will
* point to an internally allocated buffer. The caller should make a
* copy of the data before the property list is accessed again. \since
* 0.9.11 */
@@ -346,7 +346,9 @@ typedef enum pa_update_mode {
void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, pa_proplist *other);
/** Removes a single entry from the property list, identified be the
- * specified key name. \since 0.9.11 */
+ * specified key name. Returns 0 if the key has been removed, -1 if the
+ * key name is invalid, or -2 if the key does not exist in the property
+ * list.\since 0.9.11 */
int pa_proplist_unset(pa_proplist *p, const char *key);
/** Similar to pa_proplist_unset() but takes an array of keys to
@@ -383,14 +385,15 @@ char *pa_proplist_to_string_sep(pa_proplist *p, const char *sep);
pa_proplist *pa_proplist_from_string(const char *str);
/** Returns 1 if an entry for the specified key exists in the
- * property list. \since 0.9.11 */
+ * property list, 0 if such an entry does not exist, or -1 if the key
+ * is invalid. \since 0.9.11 */
int pa_proplist_contains(pa_proplist *p, const char *key);
/** Remove all entries from the property list object. \since 0.9.11 */
void pa_proplist_clear(pa_proplist *p);
/** Allocate a new property list and copy over every single entry from
- * the specific list. \since 0.9.11 */
+ * the specified list. \since 0.9.11 */
pa_proplist* pa_proplist_copy(pa_proplist *p);
/** Return the number of entries in the property list. \since 0.9.15 */
--
1.7.4.1
