Struct Proxy 

pub struct Proxy<T: HasProxy + Refcounted> { /* private fields */ }

Proxies are a central concept to how clients interact with a PipeWire server. The server has a list of objects (either instantiated locally, or by other clients). A number of these objects are exported to other clients to enumerate, interact with (call methods on) and be notified when they change (via events).

Clients discover exported objects using a Registry (itself also a proxy), which can be created using Core::registry(). The RegistryEvents::global event is triggered for each existing exported object (and subsequenty when new objects are created).

If an object is of interest, clients can “bind” to that object using Registry::bind(). This provides an object on which methods may be called, and event notifications may be received.

The object itself will be a specific type (such as Client, but will also have an associated Proxy<T> type (in this example, Proxy<Client>). The specific type provides methods and events that are specific to the object itself. In addition, the Proxy<T> type provides more general proxy-related methods and events.

Specific types implement the HasProxy trait, which allows maintaining a generic collection of these objects, while having the ability to downcast to the specific type. The HasProxy::proxy() method can be used to get the corresponding Proxy object.

Note that there are two IDs associated with a proxy. One is a “local” ID, which represents the client’s view of the object. The other is a “global” ID, which is the server’s view of the object. Due to the asynchronous nature of the protocol, it is possible that the client has a view of server objects that is not current. Global IDs might be reused, and this mechanism allows the server to keep track of what each client’s view of the server state is and avoid calling methods on objects that have gone away.

Implementations

impl<T: HasProxy + Refcounted> Proxy<T>

pub fn id(&self) -> Id

The “local” ID for this object.

pub fn object(&self) -> Option<T>

Retrieves the specific object corresponding to this Proxy. Because the proxy holds a weak reference to the object, the returned value is an Option.

pub fn bound_id(&self) -> Option<Id>

The “global” ID for this object.

pub fn add_listener(&self, events: ProxyEvents) -> HookId

Register a listener for proxy events.

pub fn remove_listener(&self, hook_id: HookId)

Remove a set of event listeners.

Trait Implementations

impl<T: Clone + HasProxy + Refcounted> Clone for Proxy<T>

fn clone(&self) -> Proxy<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: HasProxy + Refcounted> Refcounted for Proxy<T>

type WeakRef = WeakProxy<T>

The type of a weak reference to the object

fn upgrade(this: &Self::WeakRef) -> Option<Self>

Try to convert a weak reference to a strong reference. If the underlying object isstill alive, returns a Some continaing the value. If the underlying object’s strong reference count dropped to zero, and was thus freed, this returns None.

fn downgrade(&self) -> Self::WeakRef

Create a weak reference to the object. This reference does not impact the object’s lifecycle, and merely allows us the option to try to retrieve the object using Self::upgrade().

impl<T: HasProxy + Refcounted> Send for Proxy<T>

impl<T: HasProxy + Refcounted> Sync for Proxy<T>