Skip to main content

DeviceRegistry

Struct DeviceRegistry 

Source
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>

Source

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.

Source

pub fn get<R>(&self, id: &str, f: impl FnOnce(&Device<T>) -> R) -> Result<R>

Read something out of a device’s record.

Source

pub fn update(&self, id: &str, f: impl FnOnce(&mut Device<T>))

Modify a device’s record. Silently does nothing if it is gone.

Source

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.

Source

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.

Source

pub fn name(&self, id: &str) -> Option<String>

The device’s name, if it has one.

Source

pub fn is_connected(&self, id: &str) -> bool

Whether the device is recorded as connected.

Source

pub fn generation(&self, id: &str) -> Result<u64>

The device’s current generation, which a handle records when minted.

Source

pub fn ids(&self) -> Vec<String>

Every granted device’s id.

Source

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.

Source

pub fn check_allowed(&self, id: &str, uuid: &BluetoothUuid) -> Result<()>

The per-device allowlist from request_device.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn watch_disconnect(&self, id: &str) -> UnboundedReceiver<()>

A stream that yields once each time the device disconnects.

Source

pub fn mark_disconnected(&self, id: &str)

Mark a device disconnected: drop the link, invalidate every handle into it, and tell anyone watching.

Trait Implementations§

Source§

impl<T> Default for DeviceRegistry<T>

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.