Bluetooth: requestDevice() メソッド
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。
安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。
Bluetooth.requestDevice()
は Bluetooth
インターフェイスのメソッドで、指定のオプションに合致する BluetoothDevice
オブジェクトで履行される Promise
を返します。
選択用の UI が無い場合は、このメソッドは基準に合致する最初の機器を返します。
構文
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
で必要なサービスを指定する必要があります。
メモ:
たとえ options
引数が技術的にはオプションであっても、結果を返すためには filters
に値を設定するか、acceptAllDevices
に true
を設定する必要があります。
返値
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}`));
詳細な例が仕様書にあります。
仕様書
Specification |
---|
Web Bluetooth # dom-bluetooth-requestdevice |
ブラウザーの互換性
BCD tables only load in the browser
関連情報
- Communicating with Bluetooth devices over JavaScript (developer.chrome.com)