libpulse_binding/
proplist.rs

1// Copyright 2017 Lyndon Brown
2//
3// This file is part of the PulseAudio Rust language binding.
4//
5// Licensed under the MIT license or the Apache license (version 2.0), at your option. You may not
6// copy, modify, or distribute this file except in compliance with said license. You can find copies
7// of these licenses either in the LICENSE-MIT and LICENSE-APACHE files, or alternatively at
8// <http://opensource.org/licenses/MIT> and <http://www.apache.org/licenses/LICENSE-2.0>
9// respectively.
10//
11// Portions of documentation are copied from the LGPL 2.1+ licensed PulseAudio C headers on a
12// fair-use basis, as discussed in the overall project readme (available in the git repository).
13
14//! Property list constants and functions.
15
16use std::os::raw::{c_char, c_void};
17use std::ffi::{CStr, CString};
18use std::ptr::{null, null_mut};
19use std::marker::PhantomData;
20use crate::error::PAErr;
21
22pub(crate) use capi::pa_proplist as ProplistInternal;
23pub use capi::pa_update_mode_t as UpdateMode;
24
25/// Common properties.
26pub mod properties {
27    use capi;
28
29    pub use capi::PA_PROP_MEDIA_NAME as MEDIA_NAME;
30    pub use capi::PA_PROP_MEDIA_TITLE as MEDIA_TITLE;
31    pub use capi::PA_PROP_MEDIA_ARTIST as MEDIA_ARTIST;
32    pub use capi::PA_PROP_MEDIA_COPYRIGHT as MEDIA_COPYRIGHT;
33    pub use capi::PA_PROP_MEDIA_SOFTWARE as MEDIA_SOFTWARE;
34    pub use capi::PA_PROP_MEDIA_LANGUAGE as MEDIA_LANGUAGE;
35    pub use capi::PA_PROP_MEDIA_FILENAME as MEDIA_FILENAME;
36    pub use capi::PA_PROP_MEDIA_ICON as MEDIA_ICON;
37    pub use capi::PA_PROP_MEDIA_ICON_NAME as MEDIA_ICON_NAME;
38    pub use capi::PA_PROP_MEDIA_ROLE as MEDIA_ROLE;
39    pub use capi::PA_PROP_FILTER_WANT as FILTER_WANT;
40    pub use capi::PA_PROP_EVENT_ID as EVENT_ID;
41    pub use capi::PA_PROP_EVENT_DESCRIPTION as EVENT_DESCRIPTION;
42    pub use capi::PA_PROP_EVENT_MOUSE_X as EVENT_MOUSE_X;
43    pub use capi::PA_PROP_EVENT_MOUSE_Y as EVENT_MOUSE_Y;
44    pub use capi::PA_PROP_EVENT_MOUSE_HPOS as EVENT_MOUSE_HPOS;
45    pub use capi::PA_PROP_EVENT_MOUSE_VPOS as EVENT_MOUSE_VPOS;
46    pub use capi::PA_PROP_EVENT_MOUSE_BUTTON as EVENT_MOUSE_BUTTON;
47    pub use capi::PA_PROP_WINDOW_NAME as WINDOW_NAME;
48    pub use capi::PA_PROP_WINDOW_ID as WINDOW_ID;
49    pub use capi::PA_PROP_WINDOW_ICON as WINDOW_ICON;
50    pub use capi::PA_PROP_WINDOW_ICON_NAME as WINDOW_ICON_NAME;
51    pub use capi::PA_PROP_WINDOW_X as WINDOW_X;
52    pub use capi::PA_PROP_WINDOW_Y as WINDOW_Y;
53    pub use capi::PA_PROP_WINDOW_WIDTH as WINDOW_WIDTH;
54    pub use capi::PA_PROP_WINDOW_HEIGHT as WINDOW_HEIGHT;
55    pub use capi::PA_PROP_WINDOW_HPOS as WINDOW_HPOS;
56    pub use capi::PA_PROP_WINDOW_VPOS as WINDOW_VPOS;
57    pub use capi::PA_PROP_WINDOW_DESKTOP as WINDOW_DESKTOP;
58    pub use capi::PA_PROP_WINDOW_X11_DISPLAY as WINDOW_X11_DISPLAY;
59    pub use capi::PA_PROP_WINDOW_X11_SCREEN as WINDOW_X11_SCREEN;
60    pub use capi::PA_PROP_WINDOW_X11_MONITOR as WINDOW_X11_MONITOR;
61    pub use capi::PA_PROP_WINDOW_X11_XID as WINDOW_X11_XID;
62    pub use capi::PA_PROP_APPLICATION_NAME as APPLICATION_NAME;
63    pub use capi::PA_PROP_APPLICATION_ID as APPLICATION_ID;
64    pub use capi::PA_PROP_APPLICATION_VERSION as APPLICATION_VERSION;
65    pub use capi::PA_PROP_APPLICATION_ICON as APPLICATION_ICON;
66    pub use capi::PA_PROP_APPLICATION_ICON_NAME as APPLICATION_ICON_NAME;
67    pub use capi::PA_PROP_APPLICATION_LANGUAGE as APPLICATION_LANGUAGE;
68    pub use capi::PA_PROP_APPLICATION_PROCESS_ID as APPLICATION_PROCESS_ID;
69    pub use capi::PA_PROP_APPLICATION_PROCESS_BINARY as APPLICATION_PROCESS_BINARY;
70    pub use capi::PA_PROP_APPLICATION_PROCESS_USER as APPLICATION_PROCESS_USER;
71    pub use capi::PA_PROP_APPLICATION_PROCESS_HOST as APPLICATION_PROCESS_HOST;
72    pub use capi::PA_PROP_APPLICATION_PROCESS_MACHINE_ID as APPLICATION_PROCESS_MACHINE_ID;
73    pub use capi::PA_PROP_APPLICATION_PROCESS_SESSION_ID as APPLICATION_PROCESS_SESSION_ID;
74    pub use capi::PA_PROP_DEVICE_STRING as DEVICE_STRING;
75    pub use capi::PA_PROP_DEVICE_API as DEVICE_API;
76    pub use capi::PA_PROP_DEVICE_DESCRIPTION as DEVICE_DESCRIPTION;
77    pub use capi::PA_PROP_DEVICE_BUS_PATH as DEVICE_BUS_PATH;
78    pub use capi::PA_PROP_DEVICE_SERIAL as DEVICE_SERIAL;
79    pub use capi::PA_PROP_DEVICE_VENDOR_ID as DEVICE_VENDOR_ID;
80    pub use capi::PA_PROP_DEVICE_VENDOR_NAME as DEVICE_VENDOR_NAME;
81    pub use capi::PA_PROP_DEVICE_PRODUCT_ID as DEVICE_PRODUCT_ID;
82    pub use capi::PA_PROP_DEVICE_PRODUCT_NAME as DEVICE_PRODUCT_NAME;
83    pub use capi::PA_PROP_DEVICE_CLASS as DEVICE_CLASS;
84    pub use capi::PA_PROP_DEVICE_FORM_FACTOR as DEVICE_FORM_FACTOR;
85    pub use capi::PA_PROP_DEVICE_BUS as DEVICE_BUS;
86    pub use capi::PA_PROP_DEVICE_ICON as DEVICE_ICON;
87    pub use capi::PA_PROP_DEVICE_ICON_NAME as DEVICE_ICON_NAME;
88    pub use capi::PA_PROP_DEVICE_ACCESS_MODE as DEVICE_ACCESS_MODE;
89    pub use capi::PA_PROP_DEVICE_MASTER_DEVICE as DEVICE_MASTER_DEVICE;
90    pub use capi::PA_PROP_DEVICE_BUFFERING_BUFFER_SIZE as DEVICE_BUFFERING_BUFFER_SIZE;
91    pub use capi::PA_PROP_DEVICE_BUFFERING_FRAGMENT_SIZE as DEVICE_BUFFERING_FRAGMENT_SIZE;
92    pub use capi::PA_PROP_DEVICE_PROFILE_NAME as DEVICE_PROFILE_NAME;
93    pub use capi::PA_PROP_DEVICE_PROFILE_DESCRIPTION as DEVICE_PROFILE_DESCRIPTION;
94    pub use capi::PA_PROP_MODULE_AUTHOR as MODULE_AUTHOR;
95    pub use capi::PA_PROP_MODULE_DESCRIPTION as MODULE_DESCRIPTION;
96    pub use capi::PA_PROP_MODULE_USAGE as MODULE_USAGE;
97    pub use capi::PA_PROP_MODULE_VERSION as MODULE_VERSION;
98    pub use capi::PA_PROP_FORMAT_RATE as FORMAT_RATE;
99    pub use capi::PA_PROP_FORMAT_CHANNELS as FORMAT_CHANNELS;
100    #[cfg(any(doc, feature = "pa_v15"))]
101    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
102    pub use capi::PA_PROP_CONTEXT_FORCE_DISABLE_SHM as CONTEXT_FORCE_DISABLE_SHM;
103    #[cfg(any(doc, feature = "pa_v15"))]
104    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
105    pub use capi::PA_PROP_BLUETOOTH_CODEC as BLUETOOTH_CODEC;
106
107    /* These need defining here, rather than `pub use`, in order to correctly link to other things
108     * in their doc comments */
109
110    /// For streams: the name of a filter that is desired, e.g. “echo-cancel” or “equalizer-sink”.
111    /// Differs from [`FILTER_WANT`] in that it forces PulseAudio to apply the filter, regardless of
112    /// whether PulseAudio thinks it makes sense to do so or not. If this is set, [`FILTER_WANT`] is
113    /// ignored. In other words, you almost certainly do not want to use this.
114    pub const FILTER_APPLY: &str = capi::PA_PROP_FILTER_APPLY;
115
116    /// For streams: the name of a filter that should specifically be suppressed (i.e. overrides
117    /// [`FILTER_WANT`]). Useful for the times that [`FILTER_WANT`] is automatically added (e.g.
118    /// echo-cancellation for phone streams when $VOIP_APP does its own, internal AEC).
119    pub const FILTER_SUPPRESS: &str = capi::PA_PROP_FILTER_SUPPRESS;
120
121    /// For devices: intended use. A space separated list of roles (see [`MEDIA_ROLE`]) this device
122    /// is particularly well suited for, due to latency, quality or form factor.
123    pub const DEVICE_INTENDED_ROLES: &str = capi::PA_PROP_DEVICE_INTENDED_ROLES;
124
125    /// For PCM formats: the sample format used as returned by
126    /// [`Format::to_string()`](crate::sample::Format::to_string).
127    pub const FORMAT_SAMPLE_FORMAT: &str = capi::PA_PROP_FORMAT_SAMPLE_FORMAT;
128
129    /// For PCM formats: the channel map of the stream as returned by
130    /// [`Map::print()`](crate::channelmap::Map::print).
131    pub const FORMAT_CHANNEL_MAP: &str = capi::PA_PROP_FORMAT_CHANNEL_MAP;
132}
133
134/// A property list object. Basically a dictionary with ASCII strings as keys and arbitrary data as
135/// values.
136pub struct Proplist(pub(crate) ProplistInner);
137
138unsafe impl Send for Proplist {}
139unsafe impl Sync for Proplist {}
140
141/// Inner type holding ownership over actual C object, necessary to guard against use-after-free
142/// issues with respect to the related `Iterator` object.
143pub(crate) struct ProplistInner {
144    /// The actual C object.
145    pub(crate) ptr: *mut ProplistInternal,
146    /// Used to avoid freeing the internal object when used as a weak wrapper in callbacks.
147    weak: bool,
148}
149
150impl std::fmt::Debug for Proplist {
151    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
152        write!(f, "[{}]", self.to_string_sep(", ").unwrap())
153    }
154}
155
156/// Proplist iterator, used for iterating over the list’s keys. Returned by the
157/// [`Proplist::iter()`] method.
158///
159/// Note, lifetime `'a` is used to tie an instance of this struct to the associated `Proplist`, and
160/// thus prevent a use-after-free issue that would otherwise occur should the `Proplist` be
161/// destroyed first. Conversion from a `Proplist` via `into_iter` is okay though as responsibility
162/// for destruction is transfered to it.
163//XXX: Do **NOT** derive `Clone` for this, it will introduce a use-afer-free. To implement `Clone` properly would require an `Rc` wrapper around `ProplistInner`, but then if that would apply to `Proplist` also, that affects the `Send`+`Sync` properties of `Proplist` and anything using it.
164pub struct Iterator<'a> {
165    /// The actual C proplist object.
166    pl_ref: ProplistInner,
167    /// State tracker, used by underlying C function.
168    state: *mut c_void,
169    /// Use lifetime `'a`.
170    phantom: PhantomData<&'a ProplistInner>,
171}
172
173impl<'a> Iterator<'a> {
174    fn new(pl: *mut ProplistInternal) -> Self {
175        Self {
176            pl_ref: ProplistInner { ptr: pl, weak: true },
177            state: null_mut::<c_void>(),
178            phantom: PhantomData,
179        }
180    }
181}
182
183impl<'a> std::iter::Iterator for Iterator<'a> {
184    type Item = String;
185    fn next(&mut self) -> Option<Self::Item> {
186        let state_actual = &mut self.state as *mut *mut c_void;
187        let key_ptr = unsafe { capi::pa_proplist_iterate(self.pl_ref.ptr, state_actual) };
188        if key_ptr.is_null() {
189            return None;
190        }
191        // We assume key_ptr will never be null at this point
192        Some(unsafe { CStr::from_ptr(key_ptr).to_string_lossy().into_owned() })
193    }
194}
195
196impl IntoIterator for Proplist {
197    type Item = String;
198    type IntoIter = Iterator<'static>;
199
200    fn into_iter(mut self) -> Self::IntoIter {
201        let mut iter = Iterator::new(self.0.ptr);
202        // Move responsibility for destruction, if it has it (is not weak itself)
203        iter.pl_ref.weak = self.0.weak;
204        self.0.weak = true;
205        iter
206    }
207}
208
209impl PartialEq for Proplist {
210    #[inline]
211    fn eq(&self, other: &Self) -> bool {
212        unsafe { capi::pa_proplist_equal(self.0.ptr, other.0.ptr) != 0 }
213    }
214}
215
216impl Proplist {
217    /// Allocates a property list.
218    pub fn new() -> Option<Self> {
219        let ptr = unsafe { capi::pa_proplist_new() };
220        match ptr.is_null() {
221            false => Some(Self::from_raw(ptr)),
222            true => None,
223        }
224    }
225
226    /// Allocates a new property list and assigns key/value from a human readable string.
227    pub fn new_from_string(s: &str) -> Option<Self> {
228        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
229        // as_ptr() giving dangling pointers!
230        let c_str = CString::new(s).unwrap();
231        let ptr = unsafe { capi::pa_proplist_from_string(c_str.as_ptr()) };
232        match ptr.is_null() {
233            false => Some(Self::from_raw(ptr)),
234            true => None,
235        }
236    }
237
238    /// Creates a new `Proplist` from an existing [`ProplistInternal`] pointer.
239    #[inline]
240    pub(crate) fn from_raw(ptr: *mut ProplistInternal) -> Self {
241        assert_eq!(false, ptr.is_null());
242        Proplist(ProplistInner { ptr: ptr, weak: false })
243    }
244
245    /// Creates a new `Proplist` from an existing [`ProplistInternal`] pointer.
246    ///
247    /// This is the ‘weak’ version, which avoids destroying the internal object when dropped.
248    #[inline]
249    pub(crate) fn from_raw_weak(ptr: *mut ProplistInternal) -> Self {
250        assert_eq!(false, ptr.is_null());
251        Proplist(ProplistInner { ptr: ptr, weak: true })
252    }
253
254    /// Checks if the key is valid.
255    pub fn key_is_valid(key: &str) -> bool {
256        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
257        // as_ptr() giving dangling pointers!
258        let c_key = CString::new(key).unwrap();
259        unsafe { capi::pa_proplist_key_valid(c_key.as_ptr()) != 0 }
260    }
261
262    /// Appends a new string entry to the property list, possibly overwriting an already existing
263    /// entry with the same key.
264    ///
265    /// An internal copy is made of the provided string.
266    pub fn set_str(&mut self, key: &str, value: &str) -> Result<(), ()> {
267        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
268        // as_ptr() giving dangling pointers!
269        let c_key = CString::new(key).unwrap();
270        let c_value = CString::new(value).unwrap();
271        match unsafe { capi::pa_proplist_sets(self.0.ptr, c_key.as_ptr(), c_value.as_ptr()) } {
272            0 => Ok(()),
273            _ => Err(()),
274        }
275    }
276
277    /// Appends a new string entry to the property list, possibly overwriting an already existing
278    /// entry with the same key.
279    ///
280    /// This is similar to [`set_str()`](Self::set_str), however here the provided key and value
281    /// are combined into a single string, separated by an `=`. An internal copy is made of the
282    /// provided string.
283    pub fn set_pl(&mut self, pair: &str) -> Result<(), ()> {
284        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
285        // as_ptr() giving dangling pointers!
286        let c_pair = CString::new(pair).unwrap();
287        match unsafe { capi::pa_proplist_setp(self.0.ptr, c_pair.as_ptr()) } {
288            0 => Ok(()),
289            _ => Err(()),
290        }
291    }
292
293    /// Appends a new arbitrary data entry to the property list, possibly overwriting an already
294    /// existing entry with the same key.
295    ///
296    /// An internal copy of the provided data is made.
297    pub fn set(&mut self, key: &str, data: &[u8]) -> Result<(), ()> {
298        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
299        //  as_ptr() giving dangling pointers!
300        let c_key = CString::new(key).unwrap();
301        match unsafe { capi::pa_proplist_set(self.0.ptr, c_key.as_ptr(),
302            data.as_ptr() as *mut c_void, data.len()) }
303        {
304            0 => Ok(()),
305            _ => Err(()),
306        }
307    }
308
309    /// Gets a string entry for the specified key.
310    ///
311    /// Will return `None` if the key does not exist or if data is not valid UTF-8.
312    pub fn get_str(&self, key: &str) -> Option<String> {
313        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
314        // as_ptr() giving dangling pointers!
315        let c_key = CString::new(key).unwrap();
316        let ptr = unsafe { capi::pa_proplist_gets(self.0.ptr, c_key.as_ptr()) };
317        match ptr.is_null() {
318            false => Some(unsafe { CStr::from_ptr(ptr).to_string_lossy().into_owned() }),
319            true => None,
320        }
321    }
322
323    /// Gets the value for the specified key.
324    ///
325    /// For string entries, the value store will be NUL-terminated.
326    ///
327    /// The caller should make a copy of the data before any subsequent modification or destruction
328    /// of the property list.
329    ///
330    /// Returns a slice formed from the data pointer and the length of the data.
331    /// Returns `None` if key does not exist.
332    pub fn get(&self, key: &str) -> Option<&[u8]> {
333        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
334        // as_ptr() giving dangling pointers!
335        let c_key = CString::new(key).unwrap();
336        let mut data_ptr = null::<c_void>();
337        let mut nbytes: usize = 0;
338        if unsafe { capi::pa_proplist_get(self.0.ptr, c_key.as_ptr(), &mut data_ptr, &mut nbytes) }
339            != 0
340        {
341            return None;
342        }
343        if data_ptr.is_null() {
344            return None;
345        }
346        Some(unsafe { std::slice::from_raw_parts(data_ptr as *const u8, nbytes) })
347    }
348
349    /// Merges property list “other” into self, adhering to the merge mode specified.
350    #[inline]
351    pub fn merge(&mut self, other: &Self, mode: UpdateMode) {
352        unsafe { capi::pa_proplist_update(self.0.ptr, mode, other.0.ptr); }
353    }
354
355    /// Removes a single entry from the property list, identified by the specified key name.
356    pub fn unset(&mut self, key: &str) -> Result<(), PAErr> {
357        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
358        // as_ptr() giving dangling pointers!
359        let c_key = CString::new(key).unwrap();
360        match unsafe { capi::pa_proplist_unset(self.0.ptr, c_key.as_ptr()) } {
361            0 => Ok(()),
362            e => Err(PAErr(e)),
363        }
364    }
365
366    /// Similar to [`unset()`](Self::unset) but takes an array of keys to remove.
367    ///
368    /// Returns `None` on failure, otherwise the number of entries actually removed (which might
369    /// even be 0, if there were no matching entries to remove).
370    pub fn unset_many(&mut self, keys: &[&str]) -> Option<u32> {
371        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
372        // as_ptr() giving dangling pointers!
373        let mut c_keys: Vec<CString> = Vec::with_capacity(keys.len());
374        for k in keys {
375            c_keys.push(CString::new(*k).unwrap());
376        }
377
378        // Capture array of pointers to the above CString values.
379        // We also add a NULL pointer entry on the end, as expected by the C function called here.
380        let mut c_keys_ptrs: Vec<*const c_char> = Vec::with_capacity(c_keys.len() + 1);
381        for k in &c_keys {
382            c_keys_ptrs.push(k.as_ptr());
383        }
384        c_keys_ptrs.push(null());
385
386        match unsafe { capi::pa_proplist_unset_many(self.0.ptr, c_keys_ptrs.as_ptr()) } {
387            r if r < 0 => None,
388            r => Some(r as u32),
389        }
390    }
391
392    /// Gets an immutable iterator over the list’s keys.
393    ///
394    /// The property list should not be modified during iteration through the list, with the
395    /// exception of deleting the current entry. The keys in the property list do not have any
396    /// particular order.
397    ///
398    /// ```rust
399    /// # extern crate libpulse_binding as pulse;
400    /// # use pulse::proplist::Proplist;
401    /// #
402    /// # fn main() {
403    /// #     let mut my_props = Proplist::new().unwrap();
404    /// #     my_props.set_str(pulse::proplist::properties::APPLICATION_NAME, "FooApp").unwrap();
405    /// #
406    /// for key in my_props.iter() {
407    ///     //do something with it
408    ///     println!("key: {}", key);
409    /// }
410    /// # }
411    /// ```
412    #[inline]
413    pub fn iter(&self) -> Iterator<'_> {
414        Iterator::new(self.0.ptr)
415    }
416
417    /// Formats the property list nicely as a human readable string.
418    ///
419    /// This works very much like [`to_string_sep()`](Self::to_string_sep) and uses a newline as
420    /// separator and appends one final one.
421    pub fn to_string(&self) -> Option<String> {
422        let ptr = unsafe { capi::pa_proplist_to_string(self.0.ptr) };
423        if ptr.is_null() {
424            return None;
425        }
426        // Note, copying string on behalf of user here, and freeing that returned by PA, as
427        // documentation instructs, saving the user from having to remember.
428        unsafe {
429            let ret = Some(CStr::from_ptr(ptr).to_string_lossy().into_owned());
430            capi::pa_xfree(ptr as *mut c_void);
431            ret
432        }
433    }
434
435    /// Formats the property list nicely as a human readable string, choosing the separator used.
436    pub fn to_string_sep(&self, sep: &str) -> Option<String> {
437        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
438        // as_ptr() giving dangling pointers!
439        let c_sep = CString::new(sep).unwrap();
440        let ptr = unsafe { capi::pa_proplist_to_string_sep(self.0.ptr, c_sep.as_ptr()) };
441        if ptr.is_null() {
442            return None;
443        }
444        // Note, copying string on behalf of user here, and freeing that returned by PA, as
445        // documentation instructs, saving the user from having to remember.
446        unsafe {
447            let ret = Some(CStr::from_ptr(ptr).to_string_lossy().into_owned());
448            capi::pa_xfree(ptr as *mut c_void);
449            ret
450        }
451    }
452
453    /// Checks if this contains an entry with the given key.
454    ///
455    /// Returns `true` if an entry for the specified key exists in the property list. Returns `None`
456    /// on error.
457    pub fn contains(&self, key: &str) -> Option<bool> {
458        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
459        // as_ptr() giving dangling pointers!
460        let c_key = CString::new(key).unwrap();
461        match unsafe { capi::pa_proplist_contains(self.0.ptr, c_key.as_ptr()) } {
462            0 => Some(false),
463            1 => Some(true),
464            _ => None,
465        }
466    }
467
468    /// Removes all entries from the property list object.
469    #[inline]
470    pub fn clear(&mut self) {
471        unsafe { capi::pa_proplist_clear(self.0.ptr); }
472    }
473
474    /// Gets the number of entries in the property list.
475    #[inline]
476    pub fn len(&self) -> u32 {
477        unsafe { capi::pa_proplist_size(self.0.ptr) }
478    }
479
480    /// Checks if the proplist is empty.
481    #[inline]
482    pub fn is_empty(&self) -> bool {
483        unsafe { capi::pa_proplist_isempty(self.0.ptr) == 0 }
484    }
485}
486
487impl Drop for ProplistInner {
488    fn drop(&mut self) {
489        if !self.weak {
490            unsafe { capi::pa_proplist_free(self.ptr) };
491        }
492        self.ptr = null_mut::<ProplistInternal>();
493    }
494}
495
496impl Clone for Proplist {
497    /// Allocates a new property list and copy over every single entry from the specified list.
498    ///
499    /// If this is called on a ‘weak’ instance, a non-weak object is returned.
500    #[inline]
501    fn clone(&self) -> Self {
502        Self::from_raw(unsafe { capi::pa_proplist_copy(self.0.ptr) })
503    }
504}
505
506#[cfg(test)]
507mod tests {
508    use super::*;
509
510    /// Test that you cannot create a use-after-free situation by destroying a `Proplist` before an
511    /// associated `Iterator` (we avoid `Rc`/`Arc`).
512    #[test]
513    #[cfg(compile_fail)]
514    fn proplist_iter_lifetime() {
515        let iter = {
516            let my_props = Proplist::new().unwrap();
517            my_props.iter() //Returning this should not compile!
518        };
519
520        for key in iter {
521            //do something with it
522            println!("key: {}", key);
523        }
524    }
525
526    /// Test that you can however return an iterator if you convert the `Proplist` into one
527    #[test]
528    fn proplist_iter_lifetime_conv() {
529        let iter = {
530            let my_props = Proplist::new().unwrap();
531            my_props.into_iter()
532        };
533
534        for key in iter {
535            //do something with it
536            println!("key: {}", key);
537        }
538    }
539}
libpulse_binding/proplist.rs

libpulse_binding/
proplist.rs
