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(&discoverer, 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(&discoverer, SERVICE_UUID_1), svc1.id());
assert_eq!(ev.service_id(&discoverer, SERVICE_UUID_2), svc2.id());

Implementations

impl<Key> Discoverer<Key>

where Key: Copy + Eq + Hash,

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

Create a builder for a Discoverer.

pub fn client(&self) -> &Handle

Returns a handle to the client that was used to create the discoverer.

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

Restarts the discoverer.

All pending events will be discarded. The discoverer will be configured to consider all objects and services on the bus, as if it was built again with DiscovererBuilder::build.

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

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

All pending events will be discarded. The discoverer will be configured to consider only current objects and services on the bus, as if it was built again with DiscovererBuilder::build_current_only.

pub fn is_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 restarted with restart_current_only.

pub fn object_id(&self, key: Key, object: ObjectUuid) -> Option<ObjectId>

Queries a specific object ID.

pub fn service_id( &self, key: Key, object: ObjectUuid, service: ServiceUuid, ) -> Option<ServiceId>

Queries a specific service ID.

pub fn entry(&self, key: Key) -> Option<&DiscovererEntry<Key>>

Returns an entry of the Discoverer.

Entries are directly associated with the keys and correspond to the object, specific and any calls on the DiscovererBuilder.

pub fn iter(&self) -> DiscovererIter<'_, Key>

Returns an iterator over all found objects.

pub fn entry_iter(&self, key: Key) -> Option<DiscovererEntryIter<'_, Key>>

Returns an iterator over all found objects corresponding to a specific key.

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

Polls the discoverer for an event.

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

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

impl<Key> FusedStream for Discoverer<Key>

where Key: Copy + Eq + Hash,

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl<'a, Key> IntoIterator for &'a Discoverer<Key>

where Key: Copy + Eq + Hash,

type IntoIter = DiscovererIter<'a, Key>

Which kind of iterator are we turning this into?

type Item = DiscovererIterEntry<'a, Key>

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Key> Stream for Discoverer<Key>

where Key: Copy + Eq + Hash,

type Item = DiscovererEvent<Key>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<Key> Unpin for Discoverer<Key>