Struct aldrin::Discoverer
source · pub struct Discoverer<Key> { /* private fields */ }
Expand description
Discovers objects with multiple services on the bus.
Discover
s are similar to BusListener
s, 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 BusListener
s 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. DiscovererEvent
s then
give access to the key they are related to. Good candidates for keys are either integers or
custom enum
s.
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 info = ServiceInfo::new(0);
let svc1 = obj.create_service(SERVICE_UUID_1, info).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, info).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§
source§impl<Key> Discoverer<Key>
impl<Key> Discoverer<Key>
sourcepub fn builder(client: &Handle) -> DiscovererBuilder<'_, Key>
pub fn builder(client: &Handle) -> DiscovererBuilder<'_, Key>
Create a builder for a Discoverer
.
sourcepub fn client(&self) -> &Handle
pub fn client(&self) -> &Handle
Returns a handle to the client that was used to create the discoverer.
sourcepub async fn restart(&mut self) -> Result<(), Error>
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
.
sourcepub async fn restart_current_only(&mut self) -> Result<(), Error>
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
.
sourcepub fn is_finished(&self) -> bool
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
.
sourcepub fn object_id(&self, key: Key, object: ObjectUuid) -> Option<ObjectId>
pub fn object_id(&self, key: Key, object: ObjectUuid) -> Option<ObjectId>
Queries a specific object id.
sourcepub fn service_id(
&self,
key: Key,
object: ObjectUuid,
service: ServiceUuid,
) -> Option<ServiceId>
pub fn service_id( &self, key: Key, object: ObjectUuid, service: ServiceUuid, ) -> Option<ServiceId>
Queries a specific service id.
sourcepub fn entry(&self, key: Key) -> Option<&DiscovererEntry<Key>>
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
.
sourcepub fn iter(&self) -> DiscovererIter<'_, Key> ⓘ
pub fn iter(&self) -> DiscovererIter<'_, Key> ⓘ
Returns an iterator over all found objects.
sourcepub fn entry_iter(&self, key: Key) -> Option<DiscovererEntryIter<'_, Key>>
pub fn entry_iter(&self, key: Key) -> Option<DiscovererEntryIter<'_, Key>>
Returns an iterator over all found objects corresponding to a specific key.
sourcepub fn poll_next_event(
&mut self,
cx: &mut Context<'_>,
) -> Poll<Option<DiscovererEvent<Key>>>
pub fn poll_next_event( &mut self, cx: &mut Context<'_>, ) -> Poll<Option<DiscovererEvent<Key>>>
Polls the discoverer for an event.
sourcepub async fn next_event(&mut self) -> Option<DiscovererEvent<Key>>
pub async fn next_event(&mut self) -> Option<DiscovererEvent<Key>>
Awaits an event from the discoverer.
Trait Implementations§
source§impl<Key: Debug> Debug for Discoverer<Key>
impl<Key: Debug> Debug for Discoverer<Key>
source§impl<Key> FusedStream for Discoverer<Key>
impl<Key> FusedStream for Discoverer<Key>
source§fn is_terminated(&self) -> bool
fn is_terminated(&self) -> bool
true
if the stream should no longer be polled.source§impl<'a, Key> IntoIterator for &'a Discoverer<Key>
impl<'a, Key> IntoIterator for &'a Discoverer<Key>
source§impl<Key> Stream for Discoverer<Key>
impl<Key> Stream for Discoverer<Key>
source§type Item = DiscovererEvent<Key>
type Item = DiscovererEvent<Key>
impl<Key> Unpin for Discoverer<Key>
Auto Trait Implementations§
impl<Key> Freeze for Discoverer<Key>
impl<Key> !RefUnwindSafe for Discoverer<Key>
impl<Key> Send for Discoverer<Key>where
Key: Send,
impl<Key> Sync for Discoverer<Key>where
Key: Sync,
impl<Key> !UnwindSafe for Discoverer<Key>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> StreamExt for T
impl<T> StreamExt for T
source§fn next(&mut self) -> Next<'_, Self>where
Self: Unpin,
fn next(&mut self) -> Next<'_, Self>where
Self: Unpin,
source§fn into_future(self) -> StreamFuture<Self>
fn into_future(self) -> StreamFuture<Self>
source§fn map<T, F>(self, f: F) -> Map<Self, F>
fn map<T, F>(self, f: F) -> Map<Self, F>
source§fn enumerate(self) -> Enumerate<Self>where
Self: Sized,
fn enumerate(self) -> Enumerate<Self>where
Self: Sized,
source§fn filter<Fut, F>(self, f: F) -> Filter<Self, Fut, F>
fn filter<Fut, F>(self, f: F) -> Filter<Self, Fut, F>
source§fn filter_map<Fut, T, F>(self, f: F) -> FilterMap<Self, Fut, F>
fn filter_map<Fut, T, F>(self, f: F) -> FilterMap<Self, Fut, F>
source§fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F>
fn then<Fut, F>(self, f: F) -> Then<Self, Fut, F>
source§fn collect<C>(self) -> Collect<Self, C>
fn collect<C>(self) -> Collect<Self, C>
source§fn unzip<A, B, FromA, FromB>(self) -> Unzip<Self, FromA, FromB>
fn unzip<A, B, FromA, FromB>(self) -> Unzip<Self, FromA, FromB>
source§fn concat(self) -> Concat<Self>
fn concat(self) -> Concat<Self>
source§fn count(self) -> Count<Self>where
Self: Sized,
fn count(self) -> Count<Self>where
Self: Sized,
source§fn fold<T, Fut, F>(self, init: T, f: F) -> Fold<Self, Fut, T, F>
fn fold<T, Fut, F>(self, init: T, f: F) -> Fold<Self, Fut, T, F>
source§fn any<Fut, F>(self, f: F) -> Any<Self, Fut, F>
fn any<Fut, F>(self, f: F) -> Any<Self, Fut, F>
true
if any element in stream satisfied a predicate. Read moresource§fn all<Fut, F>(self, f: F) -> All<Self, Fut, F>
fn all<Fut, F>(self, f: F) -> All<Self, Fut, F>
true
if all element in stream satisfied a predicate. Read moresource§fn flatten(self) -> Flatten<Self>
fn flatten(self) -> Flatten<Self>
source§fn scan<S, B, Fut, F>(self, initial_state: S, f: F) -> Scan<Self, S, Fut, F>
fn scan<S, B, Fut, F>(self, initial_state: S, f: F) -> Scan<Self, S, Fut, F>
StreamExt::fold
that holds internal state
and produces a new stream. Read moresource§fn skip_while<Fut, F>(self, f: F) -> SkipWhile<Self, Fut, F>
fn skip_while<Fut, F>(self, f: F) -> SkipWhile<Self, Fut, F>
true
. Read moresource§fn take_while<Fut, F>(self, f: F) -> TakeWhile<Self, Fut, F>
fn take_while<Fut, F>(self, f: F) -> TakeWhile<Self, Fut, F>
true
. Read moresource§fn take_until<Fut>(self, fut: Fut) -> TakeUntil<Self, Fut>
fn take_until<Fut>(self, fut: Fut) -> TakeUntil<Self, Fut>
source§fn for_each<Fut, F>(self, f: F) -> ForEach<Self, Fut, F>
fn for_each<Fut, F>(self, f: F) -> ForEach<Self, Fut, F>
source§fn take(self, n: usize) -> Take<Self>where
Self: Sized,
fn take(self, n: usize) -> Take<Self>where
Self: Sized,
n
items of the underlying stream. Read moresource§fn skip(self, n: usize) -> Skip<Self>where
Self: Sized,
fn skip(self, n: usize) -> Skip<Self>where
Self: Sized,
n
items of the underlying stream. Read moresource§fn zip<St>(self, other: St) -> Zip<Self, St>
fn zip<St>(self, other: St) -> Zip<Self, St>
source§fn peekable(self) -> Peekable<Self>where
Self: Sized,
fn peekable(self) -> Peekable<Self>where
Self: Sized,
peek
method. Read moresource§fn inspect<F>(self, f: F) -> Inspect<Self, F>
fn inspect<F>(self, f: F) -> Inspect<Self, F>
source§fn left_stream<B>(self) -> Either<Self, B>
fn left_stream<B>(self) -> Either<Self, B>
source§fn right_stream<B>(self) -> Either<B, Self>
fn right_stream<B>(self) -> Either<B, Self>
source§fn poll_next_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>where
Self: Unpin,
fn poll_next_unpin(&mut self, cx: &mut Context<'_>) -> Poll<Option<Self::Item>>where
Self: Unpin,
Stream::poll_next
on Unpin
stream types.