Bluetooth: requestDevice() メソッド

構文

requestDevice()
requestDevice(options)

引数

options 省略可

機器の選択に関するオプションを設定するオブジェクトです。 以下のオプションが利用可能です。

filters 省略可

照合する機器のプロパティを示すフィルターオブジェクトの配列です。 フィルターオブジェクトに照合するには、機器はフィルターのすべての値（指定する services、name、namePrefix など）に一致しなければなりません。

各フィルターは以下のプロパティを持つオブジェクトの配列で構成されます。

services 省略可

Bluetooth 機器が対応しなければならない Bluetooth GATT (Generic Attribute Profile) サービスを示す値の配列。 それぞれの値は GATT 割り当てられたサービスリストにある有効な名前、例えば 'battery_service' や 'blood_pressure' です。 また、'0000180F-0000-1000-8000-00805f9b34fb' のようなサービスの完全な UUID、または短い 16 ビット (0x180F) または 32 ビットのエイリアスを渡すこともできます。 これらは BluetoothUUID.getService() に渡すことができる値と同じであることに注意してください。

name 省略可

照合する端末の正確な名前を格納した文字列。

namePrefix 省略可

照合する接頭辞を格納した文字列。 この文字列で始まる名前の機器すべてに一致します。

manufacturerData 省略可

Bluetooth Low Energy (BLE) の広告パケットの製造元データと照合するオブジェクトの配列。 それぞれのフィルターオブジェクトには以下のプロパティがあります。

companyIdentifier

必須で端末の製造元を識別する番号。 会社識別子は、Bluetooth 仕様書の割り当て番号の第 7 節に掲載されています。 例えば、"Digianswer A/S" によって製造され、割り当てられた 16 進数が 0x000C である端末と照合するには、12 を指定します。

dataPrefix 省略可

データの接頭辞。 製造者データの広告の先頭にある値と照合する値を格納するバッファー。

mask 省略可

これにより、サービスデータの dataPrefix の一部のバイトをマスクすることで、製造者データ内の一部のバイトに対して照合することができます。

serviceData 省略可

Bluetooth Low Energy (BLE) の広告パケット内のサービスデータと照合するオブジェクトの配列。 それぞれのフィルターオブジェクトには以下のプロパティがあります。

service

GATT サービス名、サービス UUID、または UUID 16 ビットまたは 32 ビットフォーム。 これは services 配列の要素と同じ値を取ります。

dataPrefix 省略可

データの接頭辞。 サービスデータの広告の先頭にある値と照合する値を格納するバッファー。

mask 省略可

これにより、サービスデータの dataPrefix の一部のバイトをマスクして、サービスデータ内の一部のバイトに対して照合することができます。

exclusionFilters 省略可

照合から除外する端末の特性を示すフィルターオブジェクトの配列。 配列要素のプロパティは filters と同じです。

optionalServices 省略可

オプションのサービス識別子の配列。

識別子は services 配列の要素（GATT サービス名、サービスワーカースクリプト (service UUID)、UUID short 16-bit または 32-bit form）と同じ値を導きます。

optionalManufacturerData 省略可

オプションで、整数による製造者コードの配列。 これは companyIdentifier と同じ値を取ります。

このデータは機器のフィルタリングには使用しませんが、指定した設定に一致する広告は advertisementreceived イベントで配信されます。 これは、許可プロンプトでユーザーに表示する機器を制御するフィルターに制約されることなく、Bluetooth 機器から受信したデータへの関心をコードで指定することができるので便利です。

acceptAllDevices 省略可

リクエストされたスクリプトがすべての Bluetooth 端末を受け入れることができることを示す論理値。 既定値は false です。

このオプションは、機器がフィルタリングに有益な情報が十分に広告されていない場合に適しています。 acceptAllDevices を true に設定した場合、filters と exclusionFilters をすべて除外し、optionalServices を設定しなければ、返された端末を使用することができません。

ユーザーが現在のオリジンでペアリングする端末を選択した後、filters.services または optionalServices のいずれかの要素のサービスリストに UUID が掲載されているサービスにのみアクセスすることができます。 そのため、要求されるサービスをリストアップすることが重要です。 具体的な例としては、name だけでフィルターをかける場合は、optionalServices で必要なサービスを指定する必要があります。

返値

BluetoothDevice オブジェクトで解決する Promise を返します。

例外

TypeError

指定された options が意味をなさないとき発生します。 たとえば、options.filters が存在して、かつ options.acceptAllDevices が true に設定されている場合や、options.filters が存在せず、かつ options.acceptAllDevices が false に設定されている場合に発生します。 options.filters が [] に設定されている場合も発生します。

NotFoundError DOMException

指定のオプションに合致する Bluetooth 機器が存在しないとき発生します。

SecurityError DOMException

安全でないオリジンで呼び出されたときなど、現在のコンテキストでセキュリティの懸念によりこの操作が許可されないとき発生します。

例

// 以下の広告をしている機器にマッチする検索オプションを使用します。
// ・標準の心拍数サービス
// ・16 ビットのサービス ID が 0x1802 と 0x1803
// ・プロプライエタリーの 128 ビット UUID c48e6067-5295-48d3-8d5c-0395f61792b1 を持つサービス
// ・名前 "ExampleName" を持つ機器
// ・名前が "Prefix" で始まる機器
//
// そして、機器が該当のサービスを広告していない場合でも、
// 機器に存在すれば、バッテリーサービスへのアクセスを有効化します。
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(`名前: ${device.name}`);
    // 機器に何かをする
  })
  .catch((error) => console.error(`何かがうまくいきませんでした。 ${error}`));

詳細な例が仕様書にあります。

仕様書

ブラウザーの互換性

関連情報

• Communicating with Bluetooth devices over JavaScript (developer.chrome.com)