pub struct DeviceRegistry<T> { /* private fields */ }Expand description
Every device this session has been granted, and what it may reach.
Shared by all six backends: the allowlist, the generation counter that invalidates stale handles, and the disconnect and service-changed watchers are the same problem everywhere.
Implementations§
Source§impl<T> DeviceRegistry<T>
impl<T> DeviceRegistry<T>
Sourcepub fn insert(
&self,
id: &str,
name: Option<String>,
allowed: Grant,
connected: bool,
inner: T,
)
pub fn insert( &self, id: &str, name: Option<String>, allowed: Grant, connected: bool, inner: T, )
Grant access to a device. Record a grant, merging it with anything this device was already granted.
Merging, not replacing, because that is what the specification says:
“add the contents of allowedDevice.allowedServices to
grantedServiceUUIDs”. A second requestDevice for the same device
with narrower options must not take away what the first one granted —
a caller still holding a service from the earlier grant would start
getting SecurityError for something it was legitimately given.
The generation is carried forward for a harder reason. It counts how
many times every handle into this device became stale, and
check_generation compares a handle’s copy against it. Resetting it to
zero would let a handle captured before a disconnect match again
afterwards, so a re-grant would quietly revive objects that point at
attributes the peer may have rearranged. It only ever goes forwards.
Sourcepub fn get<R>(&self, id: &str, f: impl FnOnce(&Device<T>) -> R) -> Result<R>
pub fn get<R>(&self, id: &str, f: impl FnOnce(&Device<T>) -> R) -> Result<R>
Read something out of a device’s record.
Sourcepub fn update(&self, id: &str, f: impl FnOnce(&mut Device<T>))
pub fn update(&self, id: &str, f: impl FnOnce(&mut Device<T>))
Modify a device’s record. Silently does nothing if it is gone.
Sourcepub fn update_where(
&self,
matches: impl Fn(&Device<T>) -> bool,
f: impl FnOnce(&mut Device<T>),
) -> Option<String>
pub fn update_where( &self, matches: impl Fn(&Device<T>) -> bool, f: impl FnOnce(&mut Device<T>), ) -> Option<String>
Find a device by something only the backend can recognise — a peripheral pointer, an object path — and modify it.
Only the Apple backend needs this: its events carry a CBPeripheral
rather than an id, so the device has to be found by identity.
Sourcepub fn find(&self, matches: impl Fn(&Device<T>) -> bool) -> Option<String>
pub fn find(&self, matches: impl Fn(&Device<T>) -> bool) -> Option<String>
The id of a device matching a backend-specific predicate.
Unused where a backend’s events already carry the device id rather than
a platform handle — linux-hci, Windows and the web all do.
Sourcepub fn is_connected(&self, id: &str) -> bool
pub fn is_connected(&self, id: &str) -> bool
Whether the device is recorded as connected.
Sourcepub fn generation(&self, id: &str) -> Result<u64>
pub fn generation(&self, id: &str) -> Result<u64>
The device’s current generation, which a handle records when minted.
Sourcepub fn remove(&self, id: &str) -> Option<Device<T>>
pub fn remove(&self, id: &str) -> Option<Device<T>>
Revoke a grant, returning the record so the backend can tear down its side of it.
Sourcepub fn check_allowed(&self, id: &str, uuid: &BluetoothUuid) -> Result<()>
pub fn check_allowed(&self, id: &str, uuid: &BluetoothUuid) -> Result<()>
The per-device allowlist from request_device.
Sourcepub fn allowed_services(&self, id: &str) -> Result<AllowedServices>
pub fn allowed_services(&self, id: &str) -> Result<AllowedServices>
What this device was granted access to.
A set is not enough on its own: a grant can name every service rather
than a list of them, and a caller handed a set has no way to say so —
it would filter discovery down to the empty set and report a device
with nothing on it. AllowedServices answers contains for both
shapes, so the filtering call sites cannot get this wrong.
Sourcepub fn grant(&self, id: &str) -> Grant
pub fn grant(&self, id: &str) -> Grant
The company identifiers this device’s grant covers.
Empty means none were asked for, which is the common case and means no
manufacturer data is reported at all.
Everything id was granted, or an empty grant if it is not known.
An unknown device getting an empty grant rather than a full one is the safe direction: it reports nothing rather than everything.
Sourcepub fn check_generation(&self, id: &str, generation: u64) -> Result<()>
pub fn check_generation(&self, id: &str, generation: u64) -> Result<()>
Fail if handles minted at generation are stale, or the link is down.
Whether a handle taken at generation may still be used on id.
The two failures are distinct, and the specification orders them: it
checks gatt.connected before it checks whether the object still
represents anything. The distinction is worth keeping because it tells
the caller what to do about it — a disconnection is something to
reconnect from and retry, whereas a stale handle survives reconnecting
and has to be rediscovered. Collapsing them into one error loses that.
Sourcepub async fn gatt_lock(&self, id: &str) -> Result<OwnedMutexGuard<()>>
pub async fn gatt_lock(&self, id: &str) -> Result<OwnedMutexGuard<()>>
Take this device’s GATT lock, held across one operation.
Unused on the web: navigator.bluetooth serialises GATT operations
itself, so taking a second lock here would only add contention.
Sourcepub fn watch_services_changed(&self, id: &str) -> UnboundedReceiver<()>
pub fn watch_services_changed(&self, id: &str) -> UnboundedReceiver<()>
Watch for this device’s service set changing — the specification’s
serviceadded, servicechanged and serviceremoved between them.
One signal rather than three, because that is what the platforms give: each reports that the set changed and that existing handles are stale, not which service it was. Inventing the distinction would mean reporting detail nobody actually has.
Sourcepub fn mark_services_changed(&self, id: &str)
pub fn mark_services_changed(&self, id: &str)
The service set changed: invalidate every handle into the device and tell anyone watching.
Only the platforms that detect it call this — CoreBluetooth’s
didModifyServices: and Android’s onServiceChanged. BlueZ, WinRT and
a raw ATT socket give no such signal, so on those targets this is
compiled and never reached; watch_services_changed there returns a
stream that stays silent rather than one that does not exist.
Every handle into this device is now stale, but the link is still up.
Called by every backend, each from whatever its platform calls this:
CoreBluetooth’s didModifyServices:, Android’s onServiceChanged,
BlueZ’s GATT objects appearing and vanishing, WinRT’s
GattServicesChanged, the browser’s serviceschanged, and — for
linux-hci, which has no stack to inherit it from — an indication on
the peer’s own Service Changed characteristic.
Sourcepub fn watch_disconnect(&self, id: &str) -> UnboundedReceiver<()>
pub fn watch_disconnect(&self, id: &str) -> UnboundedReceiver<()>
A stream that yields once each time the device disconnects.
Sourcepub fn mark_disconnected(&self, id: &str)
pub fn mark_disconnected(&self, id: &str)
Mark a device disconnected: drop the link, invalidate every handle into it, and tell anyone watching.