Struct PropertyHandle 

pub struct PropertyHandle<P: SonosProperty> { /* private fields */ }

Generic property handle providing get/fetch/watch/unwatch pattern

This is the core abstraction for the DOM-like API. Each property on a Speaker is accessed through a PropertyHandle that provides consistent methods for reading cached values, fetching fresh values, and watching for changes.

Type Parameter

• P: The property type, must implement SonosProperty

Example

// Get cached value (instant, no network call)
let volume = speaker.volume.get();

// Fetch fresh value from device (blocking API call)
let fresh_volume = speaker.volume.fetch()?;

// Watch for changes — hold the handle to keep the subscription alive
let handle = speaker.volume.watch()?;
println!("Volume: {:?}", handle.value());
// Dropping handle starts 50ms grace period

Implementations

impl<P: SonosProperty> PropertyHandle<P>

pub fn new(context: Arc<SpeakerContext>) -> Self

Create a new PropertyHandle from a shared SpeakerContext

pub fn get(&self) -> Option<P>

Get cached property value (sync, instant, no network call)

Returns the currently cached value for this property, or None if no value has been cached yet. This method never makes network calls.

Example

if let Some(volume) = speaker.volume.get() {
    println!("Current volume: {}%", volume.value());
}

pub fn watch(&self) -> Result<WatchHandle<P>, SdkError>

Start watching this property for changes (sync)

Returns a WatchHandle that keeps the subscription alive. Hold the handle for as long as you need updates — dropping it starts a 50ms grace period before the UPnP subscription is torn down.

Acquire the handle once and keep it: WatchHandle::value reads the store on every call, so one handle held across a whole render loop reports every change. Re-watching per frame is not needed to refresh the value.

Example

// Acquire once, outside the loop — the handle is a live view
let volume = speaker.volume.watch()?;

if let Some(v) = volume.value() {
    println!("Volume: {}%", v.value());
}

// Changes appear in system.iter() while the handle is alive, and the
// same handle reports the new value.
for _event in system.iter() {
    println!("Volume: {:?}", volume.value());
}

pub fn is_watched(&self) -> bool

Check if this property is currently being watched

Returns true while any WatchHandle for this property is alive, or during the grace period after the last handle was dropped. Watches are reference-counted, so dropping one of several handles leaves this true.

Example

let handle = speaker.volume.watch()?;
assert!(speaker.volume.is_watched());

drop(handle); // starts 50ms grace period
// is_watched() remains true during grace period

pub fn speaker_id(&self) -> &SpeakerId

Get the speaker ID this handle is associated with

pub fn speaker_ip(&self) -> IpAddr

Get the speaker IP address

impl<P: Fetchable> PropertyHandle<P>

pub fn watch_or_fetch(&self) -> Result<WatchHandle<P>, SdkError>

Watch with lazy fetch: subscribes to events, and if the cache is empty, performs a one-time fetch to seed the value.

Use this instead of watch() when you need a value on the first frame without waiting for a UPnP event to arrive.

pub fn fetch(&self) -> Result<P, SdkError>

Fetch fresh value from device + update cache (sync)

This makes a synchronous UPnP call to the device and updates the local state cache with the result.

Example

// Fetch fresh volume from device
let volume = speaker.volume.fetch()?;
println!("Current volume: {}%", volume.value());

// The cache is now updated, so get() returns the same value
assert_eq!(speaker.volume.get(), Some(volume));

impl PropertyHandle<GroupMembership>

pub fn fetch(&self) -> Result<GroupMembership, SdkError>

Fetch fresh value from device using speaker context + update cache (sync)

The response is interpreted using the speaker_id to extract the relevant property value from the full topology response.

Trait Implementations

impl<P: Clone + SonosProperty> Clone for PropertyHandle<P>

fn clone(&self) -> PropertyHandle<P>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.