drop support for PA v4

i was never quite satisfied with the way this was implemented and have long
meant to remove it.

Author: jnqnfe

COMPATIBILITY.md

@@ -34,7 +34,7 @@ however is a different and more complicated matter.
 ## Controlling Compatibility
 
 The Rust crates provided by this project each have a set of Cargo feature flags relating to
-PulseAudio versions. The supported versions of PA range from version 4.0 onwards.
+PulseAudio versions. The supported versions of PA range from version 5.0 onwards.
 
 The first thing to understand is that such feature flags are provided only when a version of PA
 includes changes to its API/ABI that require one, not for every PA version ever released. Hence
@@ -101,20 +101,19 @@ flags. This change in operation is hard coded. They do **not** (because it is no
 what version it is at runtime, they just work on the assumption that the program will never be run
 with an older PA version. Thus, if this is ever not the case, things can go very wrong.
 
-As an example, and in fact the primary area of concern, PA versions 5.0 and 14.0 both added new
-members to the end of some of the introspection structs. If you enable the feature flags for these
-versions (or newer), this adapts the crates to PA version 5.0+ or 14.0+ mode respectively. You will
-thus see that these new members are available in the corresponding structs offered by the crates,
-both in the raw FFI structs and also the ones returned by the introspection functions that translate
-those into the more “Rust-ified” ones. The operation of the “translation” functions will have been
-adjusted to include translation of those additional struct members. The danger here is that if your
-program is run on a system with an older version of PA, then the structs it’s C API provides will
-not match up correctly to the FFI struct description, lacking those extra members. The translation
-function will not know this however and will read and process the extra memory after the end of the
-actual structs the C API provided, assuming that memory to hold valid data. What then happens is
-undefined behaviour. Possibly a crash, possibly not, possibly an opportunity that could be seized
-upon as a security vulnerability, especially considering that some of these members involve
-pointers.
+As an example, and in fact the primary area of concern, PA version 14.0 added new members to the end
+of some of the introspection structs. If you enable the feature flags for this version (or newer),
+this adapts the crates to PA version 14.0+ mode. You will thus see that these new members are
+available in the corresponding structs offered by the crates, both in the raw FFI structs and also
+the ones returned by the introspection functions that translate those into the more “Rust-ified”
+ones. The operation of the “translation” functions will have been adjusted to include translation of
+those additional struct members. The danger here is that if your program is run on a system with an
+older version of PA, then the structs it’s C API provides will not match up correctly to the FFI
+struct description, lacking those extra members. The translation function will not know this however
+and will read and process the extra memory after the end of the actual structs the C API provided,
+assuming that memory to hold valid data. What then happens is undefined behaviour. Possibly a crash,
+possibly not, possibly an opportunity that could be seized upon as a security vulnerability,
+especially considering that some of these members involve pointers.
 
 Ideally a mechanism should be in place to properly prevent programs from loading at all unless the
 version of PA is new enough. Unfortunately, as I understand it, the system library versioning scheme
@@ -126,9 +125,6 @@ these crates, and needs further work/investigation.
 
 Currently it is left to program authors to somehow not let their programs be used on older versions
 of PA than they were compiled for, and/or to make careful choices as to the use of version features.
-(PA version 5.0 is pretty old, so it is unlikely that programs built for 5.0+ will get run on 4.0;
-and PA version 14.0 is very new, so unlikely that programs will select the version 14.0 feature flag
-for quite a while. So hopefully this should not be a practical problem).
 
 Some helper functions are provided in the `version` mod of the main binding crate to assist in
 checking at runtime the version of the available PA system library by processing the version string
@@ -166,7 +162,7 @@ Reducing the level to PA version 6.0+ (requires disabling the current default of
 libpulse-binding = { version = "2.0", default-features = false, features = "pa_v6" }
 ```
 
-Reducing the level to the absolute minimum supported (currently PA v4.0+):
+Reducing the level to the absolute minimum supported (currently PA v5.0+):
 
 ```toml
 libpulse-binding = { version = "2.0", default-features = false }

pulse-binding-mainloop-glib/CHANGELOG.md

@@ -1,3 +1,7 @@
+# unreleased]
+
+ * Dropped PA v4 support.
+
 # 2.27.1 (January 9th, 2023)
 
  * Fixed broken build status badge in readme.

pulse-binding-mainloop-glib/Cargo.toml

@@ -28,8 +28,7 @@ pa_v14 = ["pa_v13", "libpulse-binding/pa_v14", "libpulse-mainloop-glib-sys/pa_v1
 pa_v13 = ["pa_v12", "libpulse-binding/pa_v13", "libpulse-mainloop-glib-sys/pa_v13"]
 pa_v12 = ["pa_v8",  "libpulse-binding/pa_v12", "libpulse-mainloop-glib-sys/pa_v12"]
 pa_v8  = ["pa_v6",  "libpulse-binding/pa_v8",  "libpulse-mainloop-glib-sys/pa_v8"]
-pa_v6  = ["pa_v5",  "libpulse-binding/pa_v6",  "libpulse-mainloop-glib-sys/pa_v6"]
-pa_v5  = [          "libpulse-binding/pa_v5",  "libpulse-mainloop-glib-sys/pa_v5"]
+pa_v6  = [          "libpulse-binding/pa_v6",  "libpulse-mainloop-glib-sys/pa_v6"]
 
 [package.metadata.docs.rs]
 all-features = false

pulse-binding-simple/CHANGELOG.md

@@ -1,3 +1,7 @@
+# unreleased]
+
+ * Dropped PA v4 support.
+
 # 2.27.1 (January 9th, 2023)
 
  * Fixed broken build status badge in readme.

pulse-binding-simple/Cargo.toml

@@ -27,8 +27,7 @@ pa_v14 = ["pa_v13", "libpulse-binding/pa_v14", "libpulse-sys/pa_v14", "libpulse-
 pa_v13 = ["pa_v12", "libpulse-binding/pa_v13", "libpulse-sys/pa_v13", "libpulse-simple-sys/pa_v13"]
 pa_v12 = ["pa_v8",  "libpulse-binding/pa_v12", "libpulse-sys/pa_v12", "libpulse-simple-sys/pa_v12"]
 pa_v8  = ["pa_v6",  "libpulse-binding/pa_v8",  "libpulse-sys/pa_v8",  "libpulse-simple-sys/pa_v8"]
-pa_v6  = ["pa_v5",  "libpulse-binding/pa_v6",  "libpulse-sys/pa_v6",  "libpulse-simple-sys/pa_v6"]
-pa_v5  = [          "libpulse-binding/pa_v5",  "libpulse-sys/pa_v5",  "libpulse-simple-sys/pa_v5"]
+pa_v6  = [          "libpulse-binding/pa_v6",  "libpulse-sys/pa_v6",  "libpulse-simple-sys/pa_v6"]
 
 [package.metadata.docs.rs]
 all-features = false

pulse-binding/CHANGELOG.md

@@ -1,3 +1,7 @@
+# unreleased]
+
+ * Dropped PA v4 support.
+
 # 2.27.1 (January 9th, 2023)
 
  * Fixed broken build status badge in readme.

pulse-binding/Cargo.toml

@@ -32,8 +32,7 @@ pa_v14 = ["pa_v13", "libpulse-sys/pa_v14"]
 pa_v13 = ["pa_v12", "libpulse-sys/pa_v13"]
 pa_v12 = ["pa_v8",  "libpulse-sys/pa_v12"]
 pa_v8  = ["pa_v6",  "libpulse-sys/pa_v8"]
-pa_v6  = ["pa_v5",  "libpulse-sys/pa_v6"]
-pa_v5  = [          "libpulse-sys/pa_v5"]
+pa_v6  = [          "libpulse-sys/pa_v6"]
 
 [package.metadata.docs.rs]
 all-features = false

pulse-binding/src/context/introspect.rs

@@ -195,10 +195,7 @@ use capi::pa_source_info as SourceInfoInternal;
 use capi::pa_server_info as ServerInfoInternal;
 use capi::pa_module_info as ModuleInfoInternal;
 use capi::pa_client_info as ClientInfoInternal;
-#[cfg(not(any(doc, feature = "pa_v5")))]
-use capi::pa_card_profile_info as CardProfileInfoInternal;
-#[cfg(any(doc, feature = "pa_v5"))]
-use capi::pa_card_profile_info2 as CardProfileInfo2Internal;
+use capi::pa_card_profile_info2 as CardProfileInfoInternal;
 use capi::pa_card_port_info as CardPortInfoInternal;
 use capi::pa_card_info as CardInfoInternal;
 use capi::pa_sink_input_info as SinkInputInfoInternal;
@@ -1455,35 +1452,16 @@ fn get_client_info_list_cb_proxy(_: *mut ContextInternal, i: *const ClientInfoIn
 // Card info
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
-/// Stores information about a specific profile of a card.
-///
-/// Please note that this structure can be extended as part of evolutionary API updates at any time
-/// in any new release.
-///
-/// Replaced with `CardProfileInfo2` in PA version 5+.
-#[derive(Debug)]
-#[cfg(not(any(doc, feature = "pa_v5")))]
-pub struct CardProfileInfo<'a> {
-    /// Name of this profile.
-    pub name: Option<Cow<'a, str>>,
-    /// Description of this profile.
-    pub description: Option<Cow<'a, str>>,
-    /// Number of sinks this profile would create.
-    pub n_sinks: u32,
-    /// Number of sources this profile would create.
-    pub n_sources: u32,
-    /// The higher this value is, the more useful this profile is as a default.
-    pub priority: u32,
-}
+/// Backwards compatable alias
+#[deprecated = "Use the name CardProfileInfo instead"]
+pub type CardProfileInfo2<'a> = CardProfileInfo<'a>;
 
 /// Stores information about a specific profile of a card.
 ///
 /// Please note that this structure can be extended as part of evolutionary API updates at any time
 /// in any new release.
 #[derive(Debug)]
-#[cfg(any(doc, feature = "pa_v5"))]
-#[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
-pub struct CardProfileInfo2<'a> {
+pub struct CardProfileInfo<'a> {
     /// Name of this profile.
     pub name: Option<Cow<'a, str>>,
     /// Description of this profile.
@@ -1501,7 +1479,6 @@ pub struct CardProfileInfo2<'a> {
     pub available: bool,
 }
 
-#[cfg(not(any(doc, feature = "pa_v5")))]
 impl<'a> CardProfileInfo<'a> {
     fn new_from_raw(p: *const CardProfileInfoInternal) -> Self {
         assert!(!p.is_null());
@@ -1519,29 +1496,6 @@ impl<'a> CardProfileInfo<'a> {
                 n_sinks: src.n_sinks,
                 n_sources: src.n_sources,
                 priority: src.priority,
-            }
-        }
-    }
-}
-
-#[cfg(any(doc, feature = "pa_v5"))]
-impl<'a> CardProfileInfo2<'a> {
-    fn new_from_raw(p: *const CardProfileInfo2Internal) -> Self {
-        assert!(!p.is_null());
-        let src = unsafe { &*p };
-        unsafe {
-            CardProfileInfo2 {
-                name: match src.name.is_null() {
-                    false => Some(CStr::from_ptr(src.name).to_string_lossy()),
-                    true => None,
-                },
-                description: match src.description.is_null() {
-                    false => Some(CStr::from_ptr(src.description).to_string_lossy()),
-                    true => None,
-                },
-                n_sinks: src.n_sinks,
-                n_sources: src.n_sources,
-                priority: src.priority,
                 available: match src.available {
                     0 => false,
                     _ => true,
@@ -1573,12 +1527,7 @@ pub struct CardPortInfo<'a> {
     /// active.
     pub latency_offset: i64,
     /// Set of available profiles.
-    #[cfg(not(any(doc, feature = "pa_v5")))]
     pub profiles: Vec<CardProfileInfo<'a>>,
-    /// Set of available profiles.
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
-    pub profiles: Vec<CardProfileInfo2<'a>>,
     /// An indentifier for the group of ports that share their availability status with each other.
     ///
     /// This is meant especially for handling cases where one 3.5 mm connector is used for
@@ -1612,24 +1561,12 @@ impl<'a> CardPortInfo<'a> {
 
         let mut profiles_vec = Vec::with_capacity(src.n_profiles as usize);
 
-        #[cfg(not(any(doc, feature = "pa_v5")))]
-        assert!(src.n_profiles == 0 || !src.profiles.is_null());
-        #[cfg(not(any(doc, feature = "pa_v5")))]
-        for i in 0..src.n_profiles as isize {
-            let indexed_ptr = unsafe { (*src.profiles.offset(i)) as *mut CardProfileInfoInternal };
-            if !indexed_ptr.is_null() {
-                profiles_vec.push(CardProfileInfo::new_from_raw(indexed_ptr));
-            }
-        }
-
-        #[cfg(any(doc, feature = "pa_v5"))]
         assert!(src.n_profiles == 0 || !src.profiles2.is_null());
-        #[cfg(any(doc, feature = "pa_v5"))]
         for i in 0..src.n_profiles as isize {
             let indexed_ptr =
-                unsafe { (*src.profiles2.offset(i)) as *mut CardProfileInfo2Internal };
+                unsafe { (*src.profiles2.offset(i)) as *mut CardProfileInfoInternal };
             if !indexed_ptr.is_null() {
-                profiles_vec.push(CardProfileInfo2::new_from_raw(indexed_ptr));
+                profiles_vec.push(CardProfileInfo::new_from_raw(indexed_ptr));
             }
         }
 
@@ -1680,19 +1617,9 @@ pub struct CardInfo<'a> {
     /// Set of ports.
     pub ports: Vec<CardPortInfo<'a>>,
     /// Set of available profiles.
-    #[cfg(not(any(doc, feature = "pa_v5")))]
     pub profiles: Vec<CardProfileInfo<'a>>,
     /// Pointer to active profile in the set, or `None`.
-    #[cfg(not(any(doc, feature = "pa_v5")))]
     pub active_profile: Option<Box<CardProfileInfo<'a>>>,
-    /// Set of available profiles.
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
-    pub profiles: Vec<CardProfileInfo2<'a>>,
-    /// Pointer to active profile in the set, or `None`.
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
-    pub active_profile: Option<Box<CardProfileInfo2<'a>>>,
 }
 
 impl<'a> CardInfo<'a> {
@@ -1710,24 +1637,12 @@ impl<'a> CardInfo<'a> {
         }
         let mut profiles_vec = Vec::with_capacity(src.n_profiles as usize);
 
-        #[cfg(not(any(doc, feature = "pa_v5")))]
-        assert!(src.n_profiles == 0 || !src.profiles.is_null());
-        #[cfg(not(any(doc, feature = "pa_v5")))]
-        for i in 0..src.n_profiles as isize {
-            let indexed_ptr = unsafe { src.profiles.offset(i) as *mut CardProfileInfoInternal };
-            if !indexed_ptr.is_null() {
-                profiles_vec.push(CardProfileInfo::new_from_raw(indexed_ptr));
-            }
-        }
-
-        #[cfg(any(doc, feature = "pa_v5"))]
         assert!(src.n_profiles == 0 || !src.profiles2.is_null());
-        #[cfg(any(doc, feature = "pa_v5"))]
         for i in 0..src.n_profiles as isize {
             let indexed_ptr =
-                unsafe { (*src.profiles2.offset(i)) as *mut CardProfileInfo2Internal };
+                unsafe { (*src.profiles2.offset(i)) as *mut CardProfileInfoInternal };
             if !indexed_ptr.is_null() {
-                profiles_vec.push(CardProfileInfo2::new_from_raw(indexed_ptr));
+                profiles_vec.push(CardProfileInfo::new_from_raw(indexed_ptr));
             }
         }
 
@@ -1749,15 +1664,9 @@ impl<'a> CardInfo<'a> {
                 proplist: Proplist::from_raw_weak(src.proplist),
                 ports: ports_vec,
                 profiles: profiles_vec,
-                #[cfg(not(any(doc, feature = "pa_v5")))]
-                active_profile: match src.active_profile.is_null() {
-                    true => None,
-                    false => Some(Box::new(CardProfileInfo::new_from_raw(src.active_profile))),
-                },
-                #[cfg(any(doc, feature = "pa_v5"))]
                 active_profile: match src.active_profile2.is_null() {
                     true => None,
-                    false => Some(Box::new(CardProfileInfo2::new_from_raw(src.active_profile2))),
+                    false => Some(Box::new(CardProfileInfo::new_from_raw(src.active_profile2))),
                 },
             }
         }

pulse-binding/src/context/mod.rs

@@ -615,8 +615,6 @@ impl Context {
     /// cookie from a custom location. Applications don’t usually need to care about the cookie at
     /// all, but if it happens that you know what the authentication cookie is and your application
     /// needs to load it from a non-standard location, feel free to use this function.
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
     pub fn load_cookie_from_file(&mut self, cookie_file_path: &str) -> Result<(), PAErr> {
         // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
         // as_ptr() giving dangling pointers!

pulse-binding/src/mainloop/threaded.rs

@@ -389,7 +389,6 @@
 //! ```
 
 use std::rc::Rc;
-#[cfg(any(doc, feature = "pa_v5"))]
 use std::ffi::CString;
 use crate::def;
 use crate::error::PAErr;
@@ -554,8 +553,6 @@ impl Mainloop {
     }
 
     /// Sets the name of the thread.
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
     pub fn set_name(&mut self, name: &str) {
         // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
         // as_ptr() giving dangling pointers!

pulse-binding/src/sample.rs

@@ -316,24 +316,18 @@ impl Spec {
     ///
     /// Or in other words that the client library running on the end user system accepts it.
     #[inline]
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
     pub fn format_is_valid(&self) -> bool {
         unsafe { capi::pa_sample_format_valid(self.format as u32) != 0 }
     }
 
     /// Checks only if the rate is within the supported range.
     #[inline]
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
     pub fn rate_is_valid(&self) -> bool {
         unsafe { capi::pa_sample_rate_valid(self.rate) != 0 }
     }
 
     /// Checks only if the channel count is within the supported range.
     #[inline]
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
     pub fn channels_are_valid(&self) -> bool {
         unsafe { capi::pa_channels_valid(self.channels) != 0 }
     }

pulse-binding/src/version.rs

@@ -22,7 +22,7 @@
 //! versions of the PA client system library, with feature flags adapting the crate to changes made
 //! in the API of newer PA versions.
 //!
-//! Note that the minimum supported version of PA is v4.0.
+//! Note that the minimum supported version of PA is v5.0.
 //!
 //! # Runtime checking
 //!

pulse-binding/src/volume.rs

@@ -61,7 +61,6 @@
 
 use std::borrow::{Borrow, BorrowMut};
 use std::ffi::CStr;
-#[cfg(any(doc, feature = "pa_v5"))]
 use std::ptr::null;
 use crate::sample;
 use crate::channelmap::{Map, Position, PositionMask, POSITION_MASK_ALL};
@@ -359,8 +358,6 @@ impl Volume {
     ///
     /// The volume is printed in several formats: the raw volume value, percentage, and if
     /// `print_db` is true, also the dB value.
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
     pub fn print_verbose(&self, print_db: bool) -> String {
         const PRINT_VERBOSE_MAX: usize = capi::PA_VOLUME_SNPRINT_VERBOSE_MAX;
         let mut tmp = Vec::with_capacity(PRINT_VERBOSE_MAX);
@@ -821,8 +818,6 @@ impl ChannelVolumes {
     /// The volume for each channel is printed in several formats: the raw volume value,
     /// percentage, and if `print_db` is non-zero, also the dB value. If `map` is provided, the
     /// channel names will be printed.
-    #[cfg(any(doc, feature = "pa_v5"))]
-    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v5")))]
     pub fn print_verbose(&self, map: Option<&Map>, print_db: bool) -> String {
         const PRINT_VERBOSE_MAX: usize = capi::PA_CVOLUME_SNPRINT_VERBOSE_MAX;