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.

Example

// Watch returns a handle — hold it to keep the subscription alive
let volume = speaker.volume.watch()?;

// Access the current value via Deref
if let Some(v) = &*volume {
    println!("Volume: {}%", v.value());
}

// Changes will appear in system.iter() while the handle is alive
for event in system.iter() {
    // Re-watch each frame to refresh the snapshot
    let volume = speaker.volume.watch()?;
    println!("Volume: {:?}", volume.value());
}

pub fn is_watched(&self) -> bool

Check if this property is currently being watched

Returns true while a WatchHandle for this property is alive, or during the grace period after the last handle was dropped.

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 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.