Struct SonosClient 

pub struct SonosClient { /* private fields */ }

A client for executing Sonos operations against actual devices

This client bridges the gap between the stateless operation definitions and actual network requests to Sonos speakers. It uses the soap-client crate to handle the underlying SOAP communication.

Subscription Management

The primary API for managing UPnP event subscriptions is create_managed_subscription(), which returns a ManagedSubscription that handles all lifecycle management:

use sonos_api::{SonosClient, Service};

let client = SonosClient::new();
let subscription = client.create_managed_subscription(
    "192.168.1.100",
    Service::AVTransport,
    "http://callback.url",
    1800
)?;

// Subscription handles renewal and cleanup automatically

Implementations

impl SonosClient

pub fn new() -> Self

Create a new Sonos client using the shared SOAP client

This uses the global shared SOAP client instance for maximum resource efficiency. All SonosClient instances created this way share the same underlying HTTP client and connection pool, reducing memory usage and improving performance.

pub fn with_soap_client(soap_client: SoapClient) -> Self

Create a Sonos client with a custom SOAP client (for advanced use cases)

Most applications should use SonosClient::new() instead. This method is provided for cases where custom SOAP client configuration is needed.

pub fn execute<Op: SonosOperation>( &self, ip: &str, request: &Op::Request, ) -> Result<Op::Response>

Execute a Sonos operation against a device

This method takes any operation that implements SonosOperation, constructs the appropriate SOAP request, sends it to the device, and parses the response.

Arguments

• ip - The IP address of the Sonos device
• request - The operation request data

Returns

The parsed response data or an error

Example

use sonos_api::client::SonosClient;
use sonos_api::services::av_transport::{GetTransportInfoOperation, GetTransportInfoRequest};

let client = SonosClient::new();
let request = GetTransportInfoRequest { instance_id: 0 };
let response = client.execute::<GetTransportInfoOperation>("192.168.1.100", &request)?;

pub fn execute_enhanced<Op: UPnPOperation>( &self, ip: &str, operation: ComposableOperation<Op>, ) -> Result<Op::Response>

Execute an enhanced UPnP operation with composability features

This method executes a ComposableOperation that was built using the new enhanced operation framework with validation, retry policies, and timeouts.

Arguments

• ip - The IP address of the Sonos device
• operation - A ComposableOperation instance

Returns

The parsed response data or an error

Example

use sonos_api::operation::{OperationBuilder, ValidationLevel};
use sonos_api::services::av_transport;

let client = SonosClient::new();
let play_op = av_transport::play("1".to_string())
    .with_validation(ValidationLevel::Comprehensive)
    .build()?;

let response = client.execute_enhanced("192.168.1.100", play_op)?;

pub fn subscribe( &self, ip: &str, service: Service, callback_url: &str, ) -> Result<ManagedSubscription>

Subscribe to UPnP events from a service

This creates a subscription to the specified service’s event endpoint. The device will then stream events (state changes) to the provided callback URL. This is separate from control operations - subscriptions go to /Event endpoints while control operations go to /Control endpoints.

Arguments

• ip - The IP address of the Sonos device
• service - The service to subscribe to (e.g., Service::AVTransport)
• callback_url - URL where the device will send event notifications

Returns

A managed subscription that handles lifecycle, renewal, and cleanup

Example

use sonos_api::{SonosClient, Service};

let client = SonosClient::new();

// Subscribe to AVTransport events (play/pause state changes, etc.)
let subscription = client.subscribe(
    "192.168.1.100",
    Service::AVTransport,
    "http://192.168.1.50:8080/callback"
)?;

// Now execute control operations separately
let play_op = av_transport::play("1".to_string()).build()?;
client.execute("192.168.1.100", play_op)?;

// The subscription will receive events about the state changes

pub fn subscribe_with_timeout( &self, ip: &str, service: Service, callback_url: &str, timeout_seconds: u32, ) -> Result<ManagedSubscription>

Subscribe to UPnP events with custom timeout

Same as subscribe() but allows specifying a custom timeout for the subscription.

Arguments

• ip - The IP address of the Sonos device
• service - The service to subscribe to
• callback_url - URL where the device will send event notifications
• timeout_seconds - How long the subscription should last (max: 86400 = 24 hours)

Returns

A managed subscription that handles lifecycle, renewal, and cleanup

pub fn create_managed_subscription( &self, ip: &str, service: Service, callback_url: &str, timeout_seconds: u32, ) -> Result<ManagedSubscription>

Create a managed subscription with lifecycle management

This method creates a UPnP subscription and returns a ManagedSubscription that provides lifecycle management methods.

Arguments

• ip - The IP address of the Sonos device
• service - The service to subscribe to
• callback_url - The URL where events should be sent
• timeout_seconds - Initial timeout for the subscription

Returns

A ManagedSubscription that provides renewal and cleanup methods

Example

use sonos_api::{SonosClient, Service};

let client = SonosClient::new();
let subscription = client.create_managed_subscription(
    "192.168.1.100",
    Service::AVTransport,
    "http://192.168.1.50:8080/callback",
    1800
)?;

// Check if renewal is needed and renew if so
if subscription.needs_renewal() {
    subscription.renew()?;
}

// Clean up when done
subscription.unsubscribe()?;

Trait Implementations

impl Clone for SonosClient

fn clone(&self) -> SonosClient

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SonosClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SonosClient

fn default() -> Self

Returns the “default value” for a type.