1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196
// Copyright 2017 Lyndon Brown // // This file is part of the PulseAudio Rust language binding. // // This library is free software; you can redistribute it and/or modify it under the terms of the // GNU Lesser General Public License as published by the Free Software Foundation; either version // 2.1 of the License, or (at your option) any later version. // // This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without // even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU // Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public License along with this library; // if not, see <http://www.gnu.org/licenses/>. //! Sample cache mechanism. //! //! # Overview //! //! The sample cache provides a simple way of overcoming high network latencies and reducing //! bandwidth. Instead of streaming a sound precisely when it should be played, it is stored on the //! server and only the command to start playing it needs to be sent. //! //! # Creation //! //! To create a sample, the normal stream API is used (see [`::stream`]). The function //! [`::stream::Stream::connect_upload`] will make sure the stream is stored as a sample on the //! server. //! //! To complete the upload, [`::stream::Stream::finish_upload`] is called and the sample will //! receive the same name as the stream. If the upload should be aborted, simply call //! [`::stream::Stream::disconnect`]. //! //! # Playing samples //! //! To play back a sample, simply call [`::context::Context::play_sample`]: //! //! ```rust,ignore //! extern crate libpulse_binding as pulse; //! //! use pulse::volume; //! //! //... //! //! let o = my_context.play_sample( //! "sample2", // Name of my sample //! None, // Use default sink //! volume::VOLUME_NORM, // Full volume //! None // Don’t need a callback //! ); //! ``` //! //! # Removing samples //! //! When a sample is no longer needed, it should be removed on the server to save resources. The //! sample is deleted using [`::context::Context::remove_sample`]. //! //! [`::stream`]: ../../stream/index.html //! [`::stream::Stream::connect_upload`]: ../../stream/struct.Stream.html#method.connect_upload //! [`::stream::Stream::finish_upload`]: ../../stream/struct.Stream.html#method.finish_upload //! [`::stream::Stream::disconnect`]: ../../stream/struct.Stream.html#method.disconnect //! [`::context::Context::play_sample`]: ../struct.Context.html#method.play_sample //! [`::context::Context::remove_sample`]: ../struct.Context.html#method.remove_sample use std; use capi; use std::os::raw::{c_char, c_void}; use std::ffi::CString; use std::ptr::null; use super::{ContextInternal, Context}; use callbacks::box_closure_get_capi_ptr; use ::operation::Operation; impl Context { /// Remove a sample from the sample cache. /// /// Returns an operation object which may be used to cancel the operation while it is running. /// /// The callback must accept a `bool`, which indicates success. /// /// Panics if the underlying C function returns a null pointer. pub fn remove_sample<F>(&mut self, name: &str, callback: F) -> Operation<dyn FnMut(bool)> where F: FnMut(bool) + 'static { // Warning: New CStrings will be immediately freed if not bound to a variable, leading to // as_ptr() giving dangling pointers! let c_name = CString::new(name.clone()).unwrap(); let cb_data = box_closure_get_capi_ptr::<dyn FnMut(bool)>(Box::new(callback)); let ptr = unsafe { capi::pa_context_remove_sample(self.ptr, c_name.as_ptr(), Some(super::success_cb_proxy), cb_data) }; assert!(!ptr.is_null()); Operation::from_raw(ptr, cb_data as *mut Box<dyn FnMut(bool)>) } /// Play a sample from the sample cache to the specified device. /// /// If the specified device is `None` use the default sink. /// /// # Params /// /// * `name`: Name of the sample to play. /// * `dev`: Sink to play this sample on, or `None` for default. /// * `volume`: Volume to play this sample with. Starting with 0.9.15 you may pass here /// [`::volume::VOLUME_INVALID`] which will leave the decision about the volume to the server /// side which is a good idea. /// * `callback`: Optional success callback. It must accept a `bool`, which indicates success. /// /// Panics if the underlying C function returns a null pointer. /// /// [`::volume::VOLUME_INVALID`]: ../volume/constant.VOLUME_INVALID.html pub fn play_sample(&mut self, name: &str, dev: Option<&str>, volume: ::volume::Volume, callback: Option<Box<dyn FnMut(bool) + 'static>>) -> Operation<dyn FnMut(bool)> { // Warning: New CStrings will be immediately freed if not bound to a variable, leading to // as_ptr() giving dangling pointers! let c_name = CString::new(name.clone()).unwrap(); let c_dev = match dev { Some(dev) => CString::new(dev.clone()).unwrap(), None => CString::new("").unwrap(), }; let p_dev: *const c_char = match dev { Some(_) => c_dev.as_ptr(), None => null::<c_char>(), }; let (cb_fn, cb_data): (Option<extern "C" fn(_, _, _)>, _) = ::callbacks::get_su_capi_params::<_, _>(callback, super::success_cb_proxy); let ptr = unsafe { capi::pa_context_play_sample(self.ptr, c_name.as_ptr(), p_dev, volume.0, cb_fn, cb_data) }; assert!(!ptr.is_null()); Operation::from_raw(ptr, cb_data as *mut Box<dyn FnMut(bool)>) } /// Play a sample from the sample cache to the specified device, allowing specification of a /// property list for the playback stream. /// /// If the device is `None` use the default sink. /// /// # Params /// /// * `name`: Name of the sample to play. /// * `dev`: Sink to play this sample on, or `None` for default. /// * `volume`: Volume to play this sample with. Starting with 0.9.15 you may pass here /// [`::volume::VOLUME_INVALID`] which will leave the decision about the volume to the server /// side which is a good idea. /// * `proplist`: Property list for this sound. The property list of the cached entry will have /// this merged into it. /// * `callback`: Optional success callback. It must accept an `u32` index value wrapper in a /// `Result`. The index is the index of the sink input object. `Err` is given instead on /// failure. /// /// Panics if the underlying C function returns a null pointer. /// /// [`::volume::VOLUME_INVALID`]: ../volume/constant.VOLUME_INVALID.html pub fn play_sample_with_proplist(&mut self, name: &str, dev: Option<&str>, volume: ::volume::Volume, proplist: &::proplist::Proplist, callback: Option<Box<dyn FnMut(Result<u32, ()>) + 'static>>) -> Operation<dyn FnMut(Result<u32, ()>)> { // Warning: New CStrings will be immediately freed if not bound to a // variable, leading to as_ptr() giving dangling pointers! let c_name = CString::new(name.clone()).unwrap(); let c_dev = match dev { Some(dev) => CString::new(dev.clone()).unwrap(), None => CString::new("").unwrap(), }; let p_dev: *const c_char = match dev { Some(_) => c_dev.as_ptr(), None => null::<c_char>(), }; let (cb_fn, cb_data): (Option<extern "C" fn(_, _, _)>, _) = ::callbacks::get_su_capi_params::<_, _>(callback, play_sample_success_cb_proxy); let ptr = unsafe { capi::pa_context_play_sample_with_proplist(self.ptr, c_name.as_ptr(), p_dev, volume.0, proplist.0.ptr, cb_fn, cb_data) }; assert!(!ptr.is_null()); Operation::from_raw(ptr, cb_data as *mut Box<dyn FnMut(Result<u32, ()>)>) } } /// Proxy for completion success callbacks. /// Warning: This is for single-use cases only! It destroys the actual closure callback. extern "C" fn play_sample_success_cb_proxy(_: *mut ContextInternal, index: u32, userdata: *mut c_void) { let index_actual = match index { ::def::INVALID_INDEX => Err(()), i => Ok(i) }; let _ = std::panic::catch_unwind(|| { // Note, destroys closure callback after use - restoring outer box means it gets dropped let mut callback = ::callbacks::get_su_callback::<dyn FnMut(Result<u32, ()>)>(userdata); (callback)(index_actual); }); }