add PA v15 changes

note, the documentation change to `pa_proplist_get()` was already taken
care of in eea623f.

note, i changed the `messaging_api.txt` url to link to the newer gitlab
instance rather than the older cgit instance.

Author: jnqnfe

pulse-binding/src/context/introspect.rs

@@ -172,12 +172,20 @@
 //! Server modules can be remotely loaded and unloaded using [`Introspector::load_module()`] and
 //! [`Introspector::unload_module()`].
 //!
+//! # Messages
+//!
+//! Server objects like sinks, sink inputs or modules can register a message handler to communicate
+//! with clients. A message can be sent to a named message handler using
+//! [`Introspector::send_message_to_object()`].
+//!
 //! # Clients
 //!
 //! The only operation supported on clients is the possibility of kicking them off the server using
 //! [`Introspector::kill_client()`].
 
 use std::os::raw::c_void;
+#[cfg(any(doc, feature = "pa_v15"))]
+use std::os::raw::c_char;
 use std::ffi::{CStr, CString};
 use std::borrow::Cow;
 use std::ptr::null_mut;
@@ -1278,6 +1286,63 @@ fn context_index_cb_proxy(_: *mut ContextInternal, index: u32, userdata: *mut c_
     });
 }
 
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Messages
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+impl Introspector {
+    /// Send a message to an object that registered a message handler.
+    ///
+    /// The callback must accept two params, firstly a boolean indicating success if `true`, and
+    /// secondly, the response string. The response string may possibly not be given if
+    /// unsuccessful.
+    ///
+    /// For more information see the [messaging_api.txt] documentation in the PulseAudio repository.
+    ///
+    /// [messaging_api.txt]: https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/blob/master/doc/messaging_api.txt
+    #[cfg(any(doc, feature = "pa_v15"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
+    pub fn send_message_to_object<F>(&mut self, recipient_name: &str, message: &str,
+        message_parameters: &str, callback: F) -> Operation<dyn FnMut(bool, Option<String>)>
+        where F: FnMut(bool, Option<String>) + 'static
+    {
+        // Warning: New CStrings will be immediately freed if not bound to a variable, leading to
+        // as_ptr() giving dangling pointers!
+        let c_recipient_name = CString::new(recipient_name.clone()).unwrap();
+        let c_message = CString::new(message.clone()).unwrap();
+        let c_message_parameters = CString::new(message_parameters.clone()).unwrap();
+
+        let cb_data = box_closure_get_capi_ptr::<dyn FnMut(bool, Option<String>)>(Box::new(callback));
+        let ptr = unsafe { capi::pa_context_send_message_to_object(self.context,
+            c_recipient_name.as_ptr(), c_message.as_ptr(), c_message_parameters.as_ptr(),
+            Some(send_message_to_object_cb_proxy), cb_data) };
+        Operation::from_raw(ptr, cb_data as *mut Box<dyn FnMut(bool, Option<String>)>)
+    }
+}
+
+/// Proxy for send message to object callbacks.
+///
+/// Warning: This is for single-use cases only! It destroys the actual closure callback.
+#[cfg(any(doc, feature = "pa_v15"))]
+extern "C"
+fn send_message_to_object_cb_proxy(_: *mut ContextInternal, success: i32, response: *const c_char,
+    userdata: *mut c_void)
+{
+    let success_actual = match success { 0 => false, _ => true };
+    let _ = std::panic::catch_unwind(|| {
+        let r = match response.is_null() {
+            true => None,
+            false => {
+                let tmp = unsafe { CStr::from_ptr(response) };
+                Some(tmp.to_string_lossy().into_owned())
+            },
+        };
+        // Note, destroys closure callback after use - restoring outer box means it gets dropped
+        let mut callback = get_su_callback::<dyn FnMut(bool, Option<String>)>(userdata);
+        (callback)(success_actual, r);
+    });
+}
+
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 // Client info
 ////////////////////////////////////////////////////////////////////////////////////////////////////

pulse-binding/src/proplist.rs

@@ -97,6 +97,12 @@ pub mod properties {
     pub use capi::PA_PROP_MODULE_VERSION as MODULE_VERSION;
     pub use capi::PA_PROP_FORMAT_RATE as FORMAT_RATE;
     pub use capi::PA_PROP_FORMAT_CHANNELS as FORMAT_CHANNELS;
+    #[cfg(any(doc, feature = "pa_v15"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
+    pub use capi::PA_PROP_CONTEXT_FORCE_DISABLE_SHM as CONTEXT_FORCE_DISABLE_SHM;
+    #[cfg(any(doc, feature = "pa_v15"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
+    pub use capi::PA_PROP_BLUETOOTH_CODEC as BLUETOOTH_CODEC;
 
     /* These need defining here, rather than `pub use`, in order to correctly link to other things
      * in their doc comments */

pulse-sys/src/context/introspect.rs

@@ -335,6 +335,10 @@ pub struct pa_sample_info {
 
 pub type pa_sample_info_cb_t = Option<extern "C" fn(c: *mut pa_context, i: *const pa_sample_info, eol: i32, userdata: *mut c_void)>;
 
+#[cfg(any(doc, feature = "pa_v15"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
+pub type pa_context_string_cb_t = Option<extern "C" fn(c: *mut pa_context, success: i32, response: *const c_char, userdata: *mut c_void)>;
+
 #[link(name="pulse")]
 extern "C" {
     pub fn pa_context_get_sink_info_by_name(c: *mut pa_context, name: *const c_char, cb: pa_sink_info_cb_t, userdata: *mut c_void) -> *mut pa_operation;
@@ -368,6 +372,10 @@ extern "C" {
     pub fn pa_context_load_module(c: *mut pa_context, name: *const c_char, argument: *const c_char, cb: pa_context_index_cb_t, userdata: *mut c_void) -> *mut pa_operation;
     pub fn pa_context_unload_module(c: *mut pa_context, idx: u32, cb: pa_context_success_cb_t, userdata: *mut c_void) -> *mut pa_operation;
 
+    #[cfg(any(doc, feature = "pa_v15"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
+    pub fn pa_context_send_message_to_object(c: *mut pa_context, recipient_name: *const c_char, message: *const c_char, message_parameters: *const c_char, cb: pa_context_string_cb_t, userdata: *mut c_void) -> *mut pa_operation;
+
     pub fn pa_context_get_client_info(c: *mut pa_context, idx: u32, cb: pa_client_info_cb_t, userdata: *mut c_void) -> *mut pa_operation;
     pub fn pa_context_get_client_info_list(c: *mut pa_context, cb: pa_client_info_cb_t, userdata: *mut c_void) -> *mut pa_operation;
     pub fn pa_context_kill_client(c: *mut pa_context, idx: u32, cb: pa_context_success_cb_t, userdata: *mut c_void) -> *mut pa_operation;

pulse-sys/src/proplist.rs

@@ -291,6 +291,18 @@ pub const PA_PROP_FORMAT_CHANNELS: &str = "format.channels";
 /// For PCM formats: the channel map of the stream as returned by `pa_channel_map_snprint`.
 pub const PA_PROP_FORMAT_CHANNEL_MAP: &str = "format.channel_map";
 
+/// For context: whether to forcefully disable data transfer via POSIX or memfd shared memory.
+/// This property overrides any other client configuration which would otherwise enable SHM
+/// communication channels.
+#[cfg(any(doc, feature = "pa_v15"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
+pub const PA_PROP_CONTEXT_FORCE_DISABLE_SHM: &str = "context.force.disable.shm";
+
+/// For a bluez device: the currently selected codec name.
+#[cfg(any(doc, feature = "pa_v15"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "pa_v15")))]
+pub const PA_PROP_BLUETOOTH_CODEC: &str = "bluetooth.codec";
+
 /// A property list object. Basically a dictionary with ASCII strings as keys and arbitrary data as
 /// values.
 #[repr(C)] pub struct pa_proplist { _private: [u8; 0] }