Struct aldrin::Discoverer

pub struct Discoverer<Key> { /* private fields */ }

Discovers objects with multiple services on the bus.

Discovers are similar to BusListeners, in that they watch the bus for objects and services, and emit events in certain situations. The key difference is, that they focus on objects with specific sets of services. They then emit only one event, that gives access to all related IDs. A BusListeners on the other hand, would emit multiple events, one for the object and one per service.

The set of objects (and associated services) that a Discoverer looks for is configured in advance through a DiscovererBuilder, which can be created directly from a Handle:

let builder = Discoverer::builder(&handle);
let builder = DiscovererBuilder::new(&handle); // Alternative 1
let builder = handle.create_discoverer(); // Alternative 2

When configuring objects, you must choose whether the Discoverer matches only on a specific ObjectUuid or not. Set an ObjectUuid when you are looking for a single specific object on the bus. Do not set an ObjectUuid when you are looking for potentially multiple objects with the same set of services.

You can configure arbitrarily many objects. To help distinguish them when events are emitted, the Discoverer associates each object with a key. DiscovererEvents then give access to the key they are related to. Good candidates for keys are either integers or custom enums.

In the following example, a discoverer is configured for 2 different kinds of objects. One specific object with a fixed UUID and 2 services. And second, a class of objects with just 1 service.

const OBJECT_UUID: ObjectUuid = ObjectUuid(uuid!("730c1d68-212b-4181-9813-811948813809"));
const SERVICE_UUID_1: ServiceUuid = ServiceUuid(uuid!("25b952af-7447-4275-9a68-1f9b689d96a4"));
const SERVICE_UUID_2: ServiceUuid = ServiceUuid(uuid!("5456b1f9-5c2e-46b0-b0d7-bad82cbc957b"));

let mut discoverer = Discoverer::builder(&handle)
    .specific(1, OBJECT_UUID, [SERVICE_UUID_1, SERVICE_UUID_2])
    .any(2, [SERVICE_UUID_1])
    .build()
    .await?;

let mut obj = handle.create_object(OBJECT_UUID).await?;
let svc1 = obj.create_service(SERVICE_UUID_1, 0).await?;

// At this point, `obj` satisfies the requirements of the object configured with the key 2.
let ev = discoverer.next_event().await.unwrap();
assert_eq!(*ev.key(), 2);
assert_eq!(ev.kind(), DiscovererEventKind::Created);
assert_eq!(ev.object_id(), obj.id());
assert_eq!(ev.service_id(SERVICE_UUID_1), svc1.id());

let svc2 = obj.create_service(SERVICE_UUID_2, 0).await?;

// Now `obj` completes the requirements the object configured with the key 1.
let ev = discoverer.next_event().await.unwrap();
assert_eq!(*ev.key(), 1);
assert_eq!(ev.kind(), DiscovererEventKind::Created);
assert_eq!(ev.object_id(), obj.id());
assert_eq!(ev.service_id(SERVICE_UUID_1), svc1.id());
assert_eq!(ev.service_id(SERVICE_UUID_2), svc2.id());

Implementations

impl<Key> Discoverer<Key>

pub fn builder(client: &Handle) -> DiscovererBuilder<'_, Key>

Create a builder for a Discoverer.

pub async fn start(&mut self) -> Result<(), Error>

Starts the discoverer after it has been stopped.

Discoverers are initially started already. This function fails if trying to start a discoverer that isn’t stopped.

pub async fn start_current_only(&mut self) -> Result<(), Error>

Starts the discoverer and configures it to consider only current objects and services.

Unlike start, the discoverer will consider only those objects and services that exist already on the bus.

Discoverers are initially started already. This function fails if trying to start a discoverer that isn’t stopped.

pub async fn stop(&mut self) -> Result<(), Error>

Stops the discoverer.

Discoverers always begin started. Stopping a discoverer will cause next_event to return None after all enqueued events have been drained.

Be very careful with function, as the discoverer might miss events from the broker and its internal state might become invalid. There should normally not be any reason to stop a discoverer.

pub fn finished(&self) -> bool

Indicates whether the discoverer can return more events.

Discoverers can only finish if they are considering only current objects and services, i.e. built with build_current_only or started with start_current_only.

pub fn poll_next_event( &mut self, cx: &mut Context<'_> ) -> Poll<Option<DiscovererEvent<'_, Key>>>

Poll the discoverer for an event.

pub async fn next_event(&mut self) -> Option<DiscovererEvent<'_, Key>>

Await an event from the discoverer.

Trait Implementations

impl<Key: Debug> Debug for Discoverer<Key>

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

Formats the value using the given formatter.