Struct libpulse_binding::context::Context
source · pub struct Context { /* private fields */ }
Expand description
An opaque connection context to a daemon.
Note: Saves a copy of active multi-use closure callbacks, which it frees on drop.
Implementations§
source§impl Context
impl Context
sourcepub fn device_manager(&self) -> DeviceManager
pub fn device_manager(&self) -> DeviceManager
Gets a device manager object linked to the current context, giving access to device manager routines.
source§impl Context
impl Context
sourcepub fn device_restore(&self) -> DeviceRestore
pub fn device_restore(&self) -> DeviceRestore
Gets a device restore object linked to the current context, giving access to device restore routines.
source§impl Context
impl Context
sourcepub fn stream_restore(&self) -> StreamRestore
pub fn stream_restore(&self) -> StreamRestore
Gets a stream restore object linked to the current context, giving access to stream restore routines.
source§impl Context
impl Context
sourcepub fn introspect(&self) -> Introspector
pub fn introspect(&self) -> Introspector
Gets an introspection object linked to the current context, giving access to introspection routines.
See context::introspect
.
source§impl Context
impl Context
sourcepub fn remove_sample<F>(
&mut self,
name: &str,
callback: F
) -> Operation<dyn FnMut(bool)>where
F: FnMut(bool) + 'static,
pub fn remove_sample<F>( &mut self, name: &str, callback: F ) -> Operation<dyn FnMut(bool)>where F: FnMut(bool) + 'static,
Removes 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.
sourcepub fn play_sample(
&mut self,
name: &str,
dev: Option<&str>,
volume: Option<Volume>,
callback: Option<Box<dyn FnMut(bool) + 'static>>
) -> Operation<dyn FnMut(bool)>
pub fn play_sample( &mut self, name: &str, dev: Option<&str>, volume: Option<Volume>, callback: Option<Box<dyn FnMut(bool) + 'static>> ) -> Operation<dyn FnMut(bool)>
Plays 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, orNone
for default.volume
: Volume to play this sample with, orNone
to leave the decision about the volume to the server side which is a good idea.Volume::INVALID
has the same meaning as `None.callback
: Optional success callback. It must accept abool
, which indicates success.
Panics if the underlying C function returns a null pointer.
sourcepub fn play_sample_with_proplist(
&mut self,
name: &str,
dev: Option<&str>,
volume: Option<Volume>,
proplist: &Proplist,
callback: Option<Box<dyn FnMut(Result<u32, ()>) + 'static>>
) -> Operation<dyn FnMut(Result<u32, ()>)>
pub fn play_sample_with_proplist( &mut self, name: &str, dev: Option<&str>, volume: Option<Volume>, proplist: &Proplist, callback: Option<Box<dyn FnMut(Result<u32, ()>) + 'static>> ) -> Operation<dyn FnMut(Result<u32, ()>)>
Plays 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, orNone
for default.volume
: Volume to play this sample with, orNone
to leave the decision about the volume to the server side which is a good idea.Volume::INVALID
has the same meaning as `None.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 anu32
index value wrapper in aResult
. 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.
source§impl Context
impl Context
sourcepub fn subscribe<F>(
&mut self,
mask: InterestMaskSet,
callback: F
) -> Operation<dyn FnMut(bool)>where
F: FnMut(bool) + 'static,
pub fn subscribe<F>( &mut self, mask: InterestMaskSet, callback: F ) -> Operation<dyn FnMut(bool)>where F: FnMut(bool) + 'static,
Enables event notification.
The mask
parameter is used to specify which facilities you are interested in being
modified about. Use set_subscribe_callback()
to set the actual callback that will be
called when an event occurs.
The callback must accept a bool
, which indicates success.
Panics if the underlying C function returns a null pointer.
sourcepub fn set_subscribe_callback(
&mut self,
callback: Option<Box<dyn FnMut(Option<Facility>, Option<Operation>, u32) + 'static>>
)
pub fn set_subscribe_callback( &mut self, callback: Option<Box<dyn FnMut(Option<Facility>, Option<Operation>, u32) + 'static>> )
Sets the context specific call back function that is called whenever a subscribed-to event occurs.
Use subscribe()
to set the facilities you are interested in receiving notifications for,
and thus to start receiving notifications with the callback set here.
The callback must take three parameters. The first two are the facility and operation
components of the event type respectively (the underlying C API provides this information
combined into a single integer, here we extract the two component parts for you); these are
wrapped in Option
wrappers should the given values ever not map to the enum variants, but
it’s probably safe to always just unwrap()
them). The third parameter is an associated
index value.
source§impl Context
impl Context
sourcepub fn new(mainloop: &impl Mainloop, name: &str) -> Option<Self>
pub fn new(mainloop: &impl Mainloop, name: &str) -> Option<Self>
Instantiates a new connection context with an abstract mainloop API and an application name.
It is recommended to use new_with_proplist()
instead and
specify some initial properties.
Note, this will fail either should the underlying C API call return a null pointer for some
reason, or if the version of the PulseAudio client system library at runtime is found to be
older than the minimum version set via this crate’s feature flags (as a means to help
prevent “forward” compatibility problems, as discussed in the project COMPATIBILITY.md
documentation).
sourcepub fn new_with_proplist(
mainloop: &impl Mainloop,
name: &str,
proplist: &Proplist
) -> Option<Self>
pub fn new_with_proplist( mainloop: &impl Mainloop, name: &str, proplist: &Proplist ) -> Option<Self>
Instantiates a new connection context with an abstract mainloop API and an application name, and specify the initial client property list.
Note, this will fail either should the underlying C API call return a null pointer for some
reason, or if the version of the PulseAudio client system library at runtime is found to be
older than the minimum version set via this crate’s feature flags (as a means to help
prevent “forward” compatibility problems, as discussed in the project COMPATIBILITY.md
documentation).
sourcepub fn set_state_callback(
&mut self,
callback: Option<Box<dyn FnMut() + 'static>>
)
pub fn set_state_callback( &mut self, callback: Option<Box<dyn FnMut() + 'static>> )
Sets a callback function that is called whenever the context status changes.
sourcepub fn set_event_callback(
&mut self,
callback: Option<Box<dyn FnMut(String, Proplist) + 'static>>
)
pub fn set_event_callback( &mut self, callback: Option<Box<dyn FnMut(String, Proplist) + 'static>> )
Sets a callback function that is called whenever a meta/policy control event is received.
The callback is given a name which represents what event occurred. The set of defined events can be extended at any time. Also, server modules may introduce additional message types so make sure that your callback function ignores messages it doesn’t know. It is also given an (owned) property list.
sourcepub fn is_pending(&self) -> bool
pub fn is_pending(&self) -> bool
Checks if some data is pending to be written to the connection (returns true
if so).
sourcepub fn connect(
&mut self,
server: Option<&str>,
flags: FlagSet,
api: Option<&SpawnApi>
) -> Result<(), PAErr>
pub fn connect( &mut self, server: Option<&str>, flags: FlagSet, api: Option<&SpawnApi> ) -> Result<(), PAErr>
Connects the context to the specified server.
If server is None
, connect to the default server. This routine may but will not always
return synchronously on error. Use set_state_callback()
to be notified when the
connection is established. If flags
doesn’t have FlagSet::NOAUTOSPAWN
set and no
specific server is specified or accessible, a new daemon is spawned. If api
is not None
,
the functions specified in the structure are used when forking a new child process.
sourcepub fn disconnect(&mut self)
pub fn disconnect(&mut self)
Terminates the context connection immediately.
sourcepub fn drain<F>(&mut self, callback: F) -> Option<Operation<dyn FnMut()>>where
F: FnMut() + 'static,
pub fn drain<F>(&mut self, callback: F) -> Option<Operation<dyn FnMut()>>where F: FnMut() + 'static,
Drains the context.
If there is nothing to drain, the function returns None
.
Note that it can also return None
under other conditions. Many functions in the C API
perform internal state validation checks and return a null pointer if they detect a problem,
just as they return a null pointer on invalid input. Other functions panic on getting a null
pointer return, however this function is unique in a null pointer also signalling something
useful, and it is not possible to tell the difference. However, while I feel the need to be
clear about the possibility, I believe that such invalid state conditions should only occur
if there were a serious bug within PA, thus you are probably safe to just ignore this and
always take a None
return to indicate only that there is nothing to drain.
sourcepub fn exit_daemon<F>(&mut self, callback: F) -> Operation<dyn FnMut(bool)>where
F: FnMut(bool) + 'static,
pub fn exit_daemon<F>(&mut self, callback: F) -> Operation<dyn FnMut(bool)>where F: FnMut(bool) + 'static,
Tells the daemon to exit.
The returned operation is unlikely to complete successfully, since the daemon probably died before returning a success notification.
The callback must accept a bool
, which indicates success.
Panics if the underlying C function returns a null pointer.
sourcepub fn set_default_sink<F>(
&mut self,
name: &str,
callback: F
) -> Operation<dyn FnMut(bool)>where
F: FnMut(bool) + 'static,
pub fn set_default_sink<F>( &mut self, name: &str, callback: F ) -> Operation<dyn FnMut(bool)>where F: FnMut(bool) + 'static,
Sets the name of the default sink.
The callback must accept a bool
, which indicates success.
Panics if the underlying C function returns a null pointer.
sourcepub fn set_default_source<F>(
&mut self,
name: &str,
callback: F
) -> Operation<dyn FnMut(bool)>where
F: FnMut(bool) + 'static,
pub fn set_default_source<F>( &mut self, name: &str, callback: F ) -> Operation<dyn FnMut(bool)>where F: FnMut(bool) + 'static,
Sets the name of the default source.
The callback must accept a bool
, which indicates success.
Panics if the underlying C function returns a null pointer.
sourcepub fn is_local(&self) -> Option<bool>
pub fn is_local(&self) -> Option<bool>
Checks if this is a connection to a local daemon.
Returns true
when the connection is to a local daemon. Returns None
on error, for
instance when no connection has been made yet.
sourcepub fn set_name<F>(
&mut self,
name: &str,
callback: F
) -> Operation<dyn FnMut(bool)>where
F: FnMut(bool) + 'static,
pub fn set_name<F>( &mut self, name: &str, callback: F ) -> Operation<dyn FnMut(bool)>where F: FnMut(bool) + 'static,
Sets a different application name for context on the server.
Panics if the underlying C function returns a null pointer.
sourcepub fn get_server(&self) -> Option<String>
pub fn get_server(&self) -> Option<String>
Gets the server name this context is connected to.
sourcepub fn get_protocol_version(&self) -> u32
pub fn get_protocol_version(&self) -> u32
Gets the protocol version of the library.
sourcepub fn get_server_protocol_version(&self) -> Option<u32>
pub fn get_server_protocol_version(&self) -> Option<u32>
Gets the protocol version of the connected server.
Returns None
on error.
sourcepub fn proplist_update<F>(
&mut self,
mode: UpdateMode,
pl: &Proplist,
callback: F
) -> Operation<dyn FnMut(bool)>where
F: FnMut(bool) + 'static,
pub fn proplist_update<F>( &mut self, mode: UpdateMode, pl: &Proplist, callback: F ) -> Operation<dyn FnMut(bool)>where F: FnMut(bool) + 'static,
Updates the property list of the client, adding new entries.
Please note that it is highly recommended to set as many properties initially via
new_with_proplist()
as possible instead a posteriori with this
function, since that information may then be used to route streams of the client to the
right device.
Panics if the underlying C function returns a null pointer.
sourcepub fn proplist_remove<F>(
&mut self,
keys: &[&str],
callback: F
) -> Operation<dyn FnMut(bool)>where
F: FnMut(bool) + 'static,
pub fn proplist_remove<F>( &mut self, keys: &[&str], callback: F ) -> Operation<dyn FnMut(bool)>where F: FnMut(bool) + 'static,
Updates the property list of the client, remove entries.
Panics if the underlying C function returns a null pointer.
sourcepub fn get_index(&self) -> Option<u32>
pub fn get_index(&self) -> Option<u32>
Gets the client index this context is identified in the server with.
This is useful for usage with the introspection functions, such as
Introspector::get_client_info()
.
Returns None
on error.
sourcepub fn rttime_new<T, F>(
&self,
mainloop: &dyn Mainloop<MI = T::MI>,
time: MonotonicTs,
callback: F
) -> Option<TimeEvent<T::MI>>where
T: Mainloop + 'static,
F: FnMut(TimeEventRef<T::MI>) + 'static,
pub fn rttime_new<T, F>( &self, mainloop: &dyn Mainloop<MI = T::MI>, time: MonotonicTs, callback: F ) -> Option<TimeEvent<T::MI>>where T: Mainloop + 'static, F: FnMut(TimeEventRef<T::MI>) + 'static,
Creates a new timer event source for the specified time.
This is an alternative to the mainloop new_timer_event_rt
method.
A reference to the mainloop object is needed, in order to associate the event object with it. The association is done to ensure the event does not outlive the mainloop.
If pointer returned by underlying C function is NULL
, None
will be returned, otherwise a
TimeEvent
object will be returned.
Example event set to fire in five seconds time:
use libpulse_binding::time::{MonotonicTs, MicroSeconds};
let _t_event = context.rttime_new::<Mainloop, _>(&mainloop,
MonotonicTs::now() + MicroSeconds::from_secs(5).unwrap(),
|_| { println!("Timer event fired!"); });
Note: You must ensure that the returned event object lives for as long as you want its
event(s) to fire, as its Drop
implementation destroys the event source. I.e. if you create
a new event, but then immediately drop the object returned here, no event will fire!
sourcepub fn get_tile_size(&self, ss: Option<&Spec>) -> Option<usize>
pub fn get_tile_size(&self, ss: Option<&Spec>) -> Option<usize>
Gets the optimal block size for passing around audio buffers.
It is recommended to allocate buffers of the size returned here when writing audio data to playback streams, if the latency constraints permit this. It is not recommended writing larger blocks than this because usually they will then be split up internally into chunks of this size. It is not recommended writing smaller blocks than this (unless required due to latency demands) because this increases CPU usage.
If ss
is None
you will be returned the byte-exact tile size.
If ss
is invalid, returns None
, else returns tile size rounded down to multiple of the
frame size.
This is supposed to be used in a construct such as:
let ss = stream.get_sample_spec().unwrap();
let size = context.get_tile_size(Some(ss)).unwrap();
Loads the authentication cookie from a file.
This function is primarily meant for PulseAudio’s own tunnel modules, which need to load the 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.