Bluetooth: requestDevice() Methode

Syntax

requestDevice()
requestDevice(options)

Parameter

options Optional

Ein Objekt, das Optionen für die Auswahl eines geeigneten Geräts festlegt. Die verfügbaren Optionen sind:

filters Optional

Ein Array von Filterobjekten, die die Eigenschaften von Geräten angeben, die übereinstimmen sollen. Um mit einem Filterobjekt übereinzustimmen, muss ein Gerät mit allen Werten des Filters übereinstimmen: allen angegebenen services, name, namePrefix usw.

Jeder Filter besteht aus einem Array von Objekten mit den folgenden Eigenschaften:

services Optional

Ein Array von Werten, die die Bluetooth GATT (Generic Attribute Profile) Dienste angeben, die ein Bluetooth-Gerät unterstützen muss. Jeder Wert kann ein gültiger Name aus der GATT-zugeordneten Diensteliste sein, wie z.B. 'battery_service' oder 'blood_pressure'. Sie können auch eine vollständige Dienst-UUID wie '0000180F-0000-1000-8000-00805f9b34fb' oder den kurzen 16-Bit (0x180F) oder den 32-Bit-Alias übergeben. Beachten Sie, dass dies die gleichen Werte sind, die an BluetoothUUID.getService() übergeben werden können.

name Optional

Ein String, der den genauen Namen des Geräts enthält, mit dem übereingestimmt werden soll.

namePrefix Optional

Ein String, der das Namenspräfix enthält, das übereinstimmen soll. Alle Geräte, die einen Namen haben, der mit diesem String beginnt, werden übereinstimmen.

manufacturerData Optional

Ein Array von Objekten, die mit Herstellerdaten in den Bluetooth Low Energy (BLE) Werbepaketen übereinstimmen. Jedes Filterobjekt hat die folgenden Eigenschaften:

companyIdentifier

Eine zwingende Nummer, die den Hersteller des Geräts identifiziert. Unternehmenskennungen sind in den Bluetooth-Spezifikationen Assigned numbers, Abschnitt 7, aufgelistet. Um beispielsweise gegen Geräte zu filtern, die von "Digianswer A/S" hergestellt wurden, mit der zugewiesenen Hex-Nummer 0x000C, würden Sie 12 angeben.

dataPrefix Optional

Das Datenpräfix. Ein Buffer, der Werte enthält, die mit den Werten zu Beginn der Herstellerdaten übereinstimmen sollen.

mask Optional

Damit können Sie mit Bytes innerhalb der Herstellerdaten übereinstimmen, indem einige Bytes der Servicedaten dataPrefix maskiert werden.

serviceData Optional

Ein Array von Objekten, die mit Servicedaten in den Bluetooth Low Energy (BLE) Werbepaketen übereinstimmen. Jedes Filterobjekt hat die folgenden Eigenschaften:

service

Der GATT-Dienstname, die Dienst-UUID oder die UUID im 16-Bit- oder 32-Bit-Format. Diese nimmt die gleichen Werte an wie die Elemente des services-Arrays.

dataPrefix Optional

Das Datenpräfix. Ein Buffer, der Werte enthält, die mit den Werten zu Beginn der Servicedaten übereinstimmen sollen.

mask Optional

Damit können Sie mit Bytes innerhalb der Servicedaten übereinstimmen, indem einige Bytes der Servicedaten dataPrefix maskiert werden.

exclusionFilters Optional

Ein Array von Filterobjekten, die die Eigenschaften von Geräten angeben, die von der Übereinstimmung ausgeschlossen werden. Die Eigenschaften der Array-Elemente sind die gleichen wie bei filters.

optionalServices Optional

Ein Array von optionalen Dienstkennungen.

Die Kennungen nehmen die gleichen Werte an wie die Elemente des services-Arrays (ein GATT-Dienstname, Dienst-UUID oder UUID-kurzer 16-Bit- oder 32-Bit-Form).

optionalManufacturerData Optional

Ein optionales Array von Hersteller-Codes als ganze Zahlen. Dies nimmt die gleichen Werte an wie companyIdentifier.

Die Daten werden nicht zum Filtern der Geräte verwendet, aber Anzeigen, die mit dem angegebenen Set übereinstimmen, werden trotzdem in advertisementreceived-Ereignissen geliefert. Dies ist nützlich, weil es Code erlaubt, ein Interesse an Daten, die von Bluetooth-Geräten empfangen werden, anzugeben, ohne den Filter einzuschränken, der bestimmt, welche Geräte dem Benutzer im Berechtigungs-Prompt vorgestellt werden.

acceptAllDevices Optional

Ein boolescher Wert, der angibt, dass das anfordernde Skript alle Bluetooth-Geräte akzeptieren kann. Der Standardwert ist false.

Diese Option ist geeignet, wenn Geräte nicht genug Informationen für ein nützliches Filtern angekündigt haben. Wenn acceptAllDevices auf true gesetzt ist, sollten Sie alle filters und exclusionFilters weglassen und Sie müssen optionalServices festlegen, um das zurückgegebene Gerät verwenden zu können.

Nachdem der Benutzer ein Gerät zum Koppeln im aktuellen Ursprung ausgewählt hat, darf es nur auf Dienste zugreifen, deren UUID in der Diensteliste in einem Element von filters.services oder in optionalServices aufgeführt war. Es ist daher wichtig, die erforderlichen Dienste aufzulisten. Insbesondere beim Filtern nur mit name müssen Sie daran denken, auch die gewünschten Dienste in optionalServices anzugeben.

Rückgabewert

Ein Promise zu einem BluetoothDevice-Objekt.

Ausnahmen

TypeError

Ausgelöst, wenn die angegebenen options keinen Sinn ergeben. Zum Beispiel, wenn options.filters vorhanden ist und options.acceptAllDevices true ist, options.filters nicht vorhanden ist und options.acceptAllDevices false ist, oder options.filters [] ist.

NotFoundError DOMException

Ausgelöst, wenn es kein Bluetooth-Gerät gibt, das den angegebenen Optionen entspricht.

SecurityError DOMException

Ausgelöst, wenn diese Operation in diesem Kontext aufgrund von Sicherheitsbedenken nicht erlaubt ist, wie etwa einem unsicheren Ursprung.

Beispiele

// Discovery options match any devices advertising:
// - The standard heart rate service.
// - Both 16-bit service IDs 0x1802 and 0x1803.
// - A proprietary 128-bit UUID service c48e6067-5295-48d3-8d5c-0395f61792b1.
// - Devices with name "ExampleName".
// - Devices with name starting with "Prefix".
//
// And enables access to the battery service if devices
// include it, even if devices do not advertise that service.
let options = {
  filters: [
    { services: ["heart_rate"] },
    { services: [0x1802, 0x1803] },
    { services: ["c48e6067-5295-48d3-8d5c-0395f61792b1"] },
    { name: "ExampleName" },
    { namePrefix: "Prefix" },
  ],
  optionalServices: ["battery_service"],
};

navigator.bluetooth
  .requestDevice(options)
  .then((device) => {
    console.log(`Name: ${device.name}`);
    // Do something with the device.
  })
  .catch((error) => console.error(`Something went wrong. ${error}`));

Detaillierte Beispiele finden Sie in der Spezifikation und auch in Kommunikation mit Bluetooth-Geräten über JavaScript auf developer.chrome.com.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Kommunikation mit Bluetooth-Geräten über JavaScript auf developer.chrome.com.