WebHID

現行標準 — 最終更新

参加:
GitHub whatwg/hid (新しい 課題, 未解決の 課題)
Matrix でチャット
コミット:
GitHub whatwg/hid/commits
このコミット時点のスナップショット
テスト:
web-platform-tests hid/ (作業中)
翻訳 (参考):
简体中文
日本語
한국어

概要

この文書は、Human Interface Device(HID)プロトコルをサポートするデバイスへのアクセスを提供する API を記述する。

1. はじめに

この節は規範的ではない。

HID(Human Interface Device)は、人間から入力を受け取る、または人間に出力を提供する種類のデバイスである。また、導入手順を簡素化するために設計された、ホストとデバイス間の双方向通信の標準である HID プロトコルも指す。HID プロトコルは当初 USB デバイス向けに開発されたが、その後 Bluetooth を含む多くの別のプロトコル上にも実装されている。

ウェブプラットフォームは、すでに多くの HID デバイスからの入力をサポートしている。キーボード、ポインティングデバイス、ゲームパッドは、いずれも通常 HID プロトコルを使用して実装される。しかし、このサポートは、HID 入力を高水準の入力 API に変換するオペレーティングシステムの HID ドライバーに依存している。ホストの HID ドライバーが十分にサポートしていないデバイスには、ウェブページからアクセスできないことが多い。同様に、ホストの HID ドライバーがサポートしない大半のデバイスの出力にもアクセスできない。

関連する解説文書も参照されたい。

2. 想定する用途

この節は規範的ではない。

2.1. 特殊用途のデバイス

最も一般的な種類の HID 入力デバイスは、既存の高水準の入力 API を通じて、すでにウェブプラットフォームで十分にサポートされている。たとえば、マウス入力には PointerEvent を通じて、キーボード入力には KeyboardEvent を通じてアクセスできる。これらのデバイスからの入力はホストのネイティブ HID ドライバーを使用して処理され、通常、正しく動作させるためにデバイス固有のドライバーや設定を必要としない。WebHID は、このように高水準の入力 API ですでに十分にサポートされているデバイスを対象としていない。

一部の種類の HID デバイスでは、ウェブプラットフォームがデバイスの一部の機能をサポートする一方、他の機能へのアクセスを制限している。たとえば、[GAMEPAD] は大半のゲームコントローラーの入力機能をサポートするが、LED インジケーターや音声など、あまり一般的でない機能はサポートしない。こうした機能はホスト API でも十分にサポートされていないことが多く、ユーザーエージェント内にサポートを追加すると、著しく複雑になる可能性がある。WebHID は、高水準 API が提供する機能が不十分な場合に、アプリケーションに代替手段を提供する。

多くの HID デバイスは、どのウェブプラットフォーム API でもサポートされていない。HID 仕様には、仮想現実の操作機器、フライトシミュレーター、医療機器など、HID を通じてサポートできる多種多様なデバイスが記述されている。WebHID により、追加のドライバーやユーザーエージェントの変更なしに、これらのデバイスを使用できるようになる。

2.2. 試作、趣味、教育用のデバイス

HID は、デバイスを使用するホストごとにドライバーを用意する代わりに、ホストの汎用 HID ドライバーを利用できるため、試作や趣味の用途に適している。導入手順が簡単になることで、教育者も各ホストのシステム設定を変更することなく、教室の生徒たちにデバイスを配備しやすくなる。ウェブプラットフォームを通じて HID デバイスへのアクセスを提供すれば、とりわけ現在ホスト固有のアプリケーションのみでサポートされているデバイスについて、導入に必要な作業をさらに減らせる。

3. セキュリティとプライバシーに関する考慮事項

この節は規範的ではない。

3.1. デバイスへのアクセスの悪用

HID 周辺機器は、ユーザーの明示的な同意なしにページからアクセス可能にするべきでない強力な機能を公開する場合がある。たとえば、周辺環境の情報を収集できるセンサーを備えることがある。デバイスには、公開したり上書きしたりするべきでない私的情報が保存されている場合もある。多くのデバイスは、ファームウェアを更新する機能を公開する。通常、オペレーティングシステムはアプリケーションから HID デバイスへのアクセスを制限せず、そのアクセスが悪用されて、デバイスが損傷したり保存データが破損したりすることがある。

場合によっては、デバイスがウェブページからまったくアクセス可能にするべきでない機能を公開している。ベンダー ID と製品 ID で特定のデバイスを識別し、列挙時に非表示にすることで、そのデバイスをブロックできる。レポート記述子によってデバイス自身の機能を記述できるため、ベンダー ID と製品 ID を事前に知り得ない場合でも、この情報を使って特定の種類のデバイスをブロックできる。これは、HID 用途の値をレポート記述子内のコレクションについて調べることで実現できる。たとえば、最上位コレクションにキーボードのHID 用途を持つデバイスへのアクセスを拒否すれば、キーボードに類するデバイスへのアクセスを拒否できる。

悪用を緩和するため、ユーザーが明示的にアクセスを許可するまで、デバイスはページから利用できない。まずページがアクセスを要求しなければならず、利用可能なすべてのデバイスを表示する選択画面でユーザーがデバイスを選ぶと、アクセスが許可される。ページにアクセスが許可されると、デバイスが使用中であることを示すインジケーターが表示される。

3.2. デバイスへの攻撃

HID プロトコルはきわめて汎用的で、その汎用性を活用した多種多様なデバイスが設計されている。そのため、悪意あるページがデバイスへのアクセスを利用してデバイス自体を損傷させる方法は数多く考えられる。カスタム HID レポートを使用してファームウェア更新を送信できる HID 周辺機器は比較的一般的である。デバイス製造者は、ファームウェアのバイナリーが真正であることを検証するよう更新機構を慎重に設計しなければならず、デバイスのセキュリティを低下させるダウングレードも防ぐべきである。信頼できない更新により、デバイスに新しい機能を追加したり、まったく別の種類のデバイスを装わせたりできる可能性がある。

想定範囲外の入力が与えられると損傷するデバイスもある。たとえば、ページが無効な振動コマンドを送信すると、ゲームパッドの振動機能が損傷する可能性がある。

一般に、この種の攻撃はデバイス固有であり、API の水準では緩和できない。

3.3. ホストへの攻撃

悪意あるページがデバイスへのアクセスを獲得すると、場合によってはそのアクセスをホストへの攻撃に利用できる。主な懸念は、デバイスを使って信頼された入力イベントを生成できるかどうかである。これらのイベントはユーザーの意図を代弁するものとして扱われ、ウェブプラットフォームのより強力な機能へのアクセスに使用できる。

マウスやキーボードは通常 HID 周辺機器として実装され、信頼された入力を生成することもできる。HID キーボードやマウスには、一連の入力を保存して後で再生できるプログラム可能なマクロなどの高度な機能が含まれることがある。デバイス製造者は、悪意あるアプリが意図しない入力列でデバイスを再プログラムできないよう、こうした機能を慎重に設計しなければならない。また、ユーザーの明示的な同意なしにマクロの再生が開始されないよう保護しなければならない。

3.4. 緩和策

セキュリティとプライバシーのリスクを緩和するため、ユーザーエージェントにはデバイスへのアクセス要求を選択画面に基づく手順で実装することを推奨する。ページが HID デバイスへのアクセスを要求したとき、ユーザーエージェントはページがデバイスへのアクセスを求めていることをユーザーに知らせるダイアログを表示するべきである。そのダイアログには接続された HID デバイスの一覧を表示し、ページに公開するデバイスを選ぶようユーザーに求めるべきである。誤クリックの可能性を減らすため、一覧からデバイスを選ぶ操作と、選択を確定してダイアログを閉じる操作という、別々の二つの操作を要求するべきである。

4. 拡張対象: Navigator インターフェイス

[SecureContext] partial interface Navigator {
    [SameObject] readonly attribute HID hid;
};

4.1. hid 属性

取得時、hid 属性は常に HID オブジェクトの同じインスタンスを返す。

5. 拡張対象: WorkerNavigator インターフェイス

[Exposed=(DedicatedWorker,ServiceWorker), SecureContext]
partial interface WorkerNavigator {
    [SameObject] readonly attribute HID hid;
};

5.1. hid 属性

取得時、hid 属性は常に HID オブジェクトの同じインスタンスを返す。

6. HID インターフェイス

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HID : EventTarget {
    attribute EventHandler onconnect;
    attribute EventHandler ondisconnect;
    Promise<sequence<HIDDevice>> getDevices();
    [Exposed=Window] Promise<sequence<HIDDevice>> requestDevice(
        HIDDeviceRequestOptions options);
};

注: ユーザーエージェントの実装は、条件付きの公開を選択してもよい。対象は hid 属性であり、これを持つ Navigator の関連するグローバルオブジェクト、すなわち Navigator のものが ServiceWorkerGlobalScope である場合が該当する。たとえば、ブラウザー拡張のコンテキスト([browserext])が挙げられる。

HID のインスタンスは、次の表に記述された内部スロットを持つものとして作成される:

内部スロット 初期値 説明(非規範的)
[[devices]] 空の順序付き集合 次の順序付き集合(要素型: HIDDevice のインスタンス)。これらはHID インターフェイスのうち、現在システムで利用可能なものを表す。
onconnect 属性、 型:EventHandler
onconnect はイベントハンドラー IDL 属性であり、対象はconnect イベント型である。
ondisconnect 属性、 型:EventHandler
ondisconnect はイベントハンドラー IDL 属性であり、対象はdisconnect イベント型である。
次のHID インターフェイスがシステムで利用可能になったとき、以下の手順を実行する:
このHID インターフェイスは、HID プロトコルを通じてデバイスと通信するために使用できる論理インターフェイスである。各HID インターフェイスは、一つだけのレポート記述子を持ち、それがインターフェイスでサポートされるレポートの集合を記述する。一つの物理デバイスは、複数を公開してもよい。その公開対象はHID インターフェイスである。複数のHID インターフェイスを持つデバイスは、インターフェイスごとにこの手順を一度実行する。

たとえば、USB デバイスはインターフェイスの集まりとして実装され、それぞれがインターフェイスクラスを指定してもよい。デバイスに HID クラスを使用する USB インターフェイスが複数ある場合、各インターフェイスは別々のHID インターフェイスとして列挙される。

  1. device を HIDDevice とする。

  2. device.[[vendorId]] を、このインターフェイスを公開するデバイスのベンダー ID に設定する。

  3. device.[[productId]] を、このインターフェイスを公開するデバイスの製品 ID に設定する。

  4. device.[[productName]] を、このインターフェイスを公開するデバイスの製品名に設定する。

  5. device.[[collections]] を、レポート記述子の構文解析の結果に設定する。

  6. hid を次の呼び出し結果とする: device の関連するグローバルオブジェクトの Navigator オブジェクトの hid 取得子。ただし、これは device の関連するグローバルオブジェクトが Window オブジェクトの場合であり、それ以外では、device の関連するグローバルオブジェクトの WorkerNavigator オブジェクトの hid 取得子の呼び出し結果とする。

  7. 追加する: device を hid.[[devices]] に。

  8. ユーザーが以前、サイトによる device へのアクセスを requestDevice() の呼び出しの結果として許可している場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは hid のもので、HID デバイスタスクソースを使用する。タスクではイベントを発火する。イベント名は connect、対象は hid、使用するインターフェイスは HIDConnectionEvent で、その device 属性を device に初期化する。

次の操作、すなわちレポート記述子を構文解析するには、以下の手順を実行する:
通常システムは、レポート記述子の バイト列を各HID インターフェイスについて、デバイスの初回接続時に読み取り、値をシステムレジストリーにキャッシュする。レポート記述子を利用できなくても、各レポートの配置を再構築できる情報をシステムが提供している場合、ユーザーエージェントは別のアルゴリズムを使用してもよい。その場合、省略する構文解析の対象はレポート記述子である.

レポート記述子の形式は、[USBIF-HID-CLASS] の 6.2.2 節に記述されている。以下のアルゴリズムは、その節に記述された構文解析アルゴリズムと同じものを実装することを意図している。

レポート記述子には三つの種類の項目が含まれる。主項目は、データフィールドの定義とグループ化に使用される。大域項目と局所項目はデータフィールドを記述する。局所項目は次の主項目にのみ適用される特性を定義し、大域項目は、その後に定義されるすべての主項目に影響する特性を定義する。

各項目には、その項目に関連する 0、1、2、または 4 バイトのデータを含む項目データフィールドと、bSize フィールドがある。後者は、項目データフィールドの格納に使用するバイト数を記述する。また、各項目には種類を識別するタグがある。

  1. items を、レポート記述子のバイト列をリストに変換した結果とする。その要素は主項目、大域項目、局所項目である。

  2. collections を空の列(要素型: HIDCollectionInfo)として初期化する。

  3. ancestors を空のリストとして初期化する。

  4. localState を空の順序付きマップとして初期化する。

  5. usages を空の列(要素型: unsigned long)として初期化する。

  6. stringIndices を空のリストとして初期化する。

  7. globalStack を空のスタックとして初期化する。

  8. initialGlobalState を空の順序付きマップとして初期化する。

  9. reportId を 0 に初期化する。

  10. initialGlobalState["unitSystem"] を "none" に設定する。

  11. initialGlobalState["unitExponent"] を 0 に設定する。

  12. initialGlobalState["unitFactorLengthExponent"] を 0 に設定する。

  13. initialGlobalState["unitFactorMassExponent"] を 0 に設定する。

  14. initialGlobalState["unitFactorTimeExponent"] を 0 に設定する。

  15. initialGlobalState["unitFactorTemperatureExponent"] を 0 に設定する。

  16. initialGlobalState["unitFactorCurrentExponent"] を 0 に設定する。

  17. initialGlobalState["unitFactorLuminousIntensityExponent"] を 0 に設定する。

  18. initialGlobalState["logicalMinimum"] を 0 に設定する。

  19. initialGlobalState["logicalMaximum"] を 0 に設定する。

  20. initialGlobalState["physicalMinimum"] を 0 に設定する。

  21. initialGlobalState["physicalMaximum"] を 0 に設定する。

  22. プッシュする: initialGlobalState を globalStack に。

  23. 各要素について、item を items から取り出して:

    注: 主項目は [USBIF-HID-CLASS] の 6.2.2.4 節から 6.2.2.6 節に記述されている。Input タグ、Output タグ、Feature タグを持つ項目は、入力、出力、または機能レポート内のフィールドを定義する。項目データフィールドは、主項目が Input タグ、Output タグ、Feature タグのいずれかを持つ場合、データフィールドを記述する複数の真偽値パラメーターを含むビットフィールドである。Collection タグを持つ項目は、現在のコレクション内に入れ子になる新しいコレクションを定義し、現在のコレクションがなければ新しい最上位コレクションを定義する。項目データフィールドは、主項目が Collection タグを持つ場合、コレクションの種類を含む。End Collection タグを持つ項目は、現在のコレクションを閉じる。

次の操作、すなわちHID レポート項目を作成する操作を、item, localState, globalState, usagesおよびstringIndicesを用いて実行するには、以下の手順を実行する:
  1. reportItem を新しい HIDReportItem 辞書とする。

  2. value を、項目データフィールドを unsigned long として解釈した値とする。

  3. bitfield をリストとし、その boolean 値は value のビットを下位ビットから順に並べたものとする。

  4. reportItem["isConstant"] を bitfield[0] に設定する。

  5. reportItem["isArray"] を !bitfield[1] に設定する。

  6. reportItem["isAbsolute"] を !bitfield[2] に設定する。

  7. reportItem["wrap"] を bitfield[3] に設定する。

  8. reportItem["isLinear"] を !bitfield[4] に設定する。

  9. reportItem["hasPreferredState"] を !bitfield[5] に設定する。

  10. reportItem["hasNull"] を bitfield[6] に設定する。

  11. reportItem["isVolatile"] を bitfield[7] に設定する。

  12. reportItem["isBufferedBytes"] を bitfield[8] に設定する。

  13. reportItem["usages"] を usages に設定する。

  14. reportItem["reportSize"] を globalState["reportSize"] に設定する。

  15. reportItem["reportCount"] を globalState["reportCount"] に設定する。

  16. reportItem["unitExponent"] を globalState["unitExponent"] に設定する。

  17. reportItem["unitSystem"] を globalState["unitSystem"] に設定する。

  18. reportItem["unitFactorLengthExponent"] を globalState["unitFactorLengthExponent"] に設定する。

  19. reportItem["unitFactorMassExponent"] を globalState["unitFactorMassExponent"] に設定する。

  20. reportItem["unitFactorTimeExponent"] を globalState["unitFactorTimeExponent"] に設定する。

  21. reportItem["unitFactorTemperatureExponent"] を globalState["unitFactorTemperatureExponent"] に設定する。

  22. reportItem["unitFactorCurrentExponent"] を globalState["unitFactorCurrentExponent"] に設定する。

  23. reportItem["unitFactorLuminousIntensityExponent"] を globalState["unitFactorLuminousIntensityExponent"] に設定する。

  24. reportItem["logicalMinimum"] を globalState["logicalMinimum"] に設定する。

  25. reportItem["logicalMaximum"] を globalState["logicalMaximum"] に設定する。

  26. reportItem["physicalMinimum"] を globalState["physicalMinimum"] に設定する。

  27. reportItem["physicalMaximum"] を globalState["physicalMaximum"] に設定する。

  28. "usageMinimum" と "usageMaximum" の両方が localState にあり、かつ localState["usageMinimum"] が localState["usageMaximum"] 以下である場合は reportItem["isRange"] を true に設定し、それ以外の場合は false に設定する。

  29. reportItem["isRange"] が true である場合、reportItem["usageMinimum"] を localState["usageMinimum"] に設定する。

  30. reportItem["isRange"] が true である場合、reportItem["usageMaximum"] を localState["usageMaximum"] に設定する。

  31. "stringMinimum" が localState に含まれ、かつ "stringMaximum" が localState に含まれる場合:

    1. 追加する: すべての項目を、その範囲が localState["stringMinimum"] から localState["stringMaximum"] までとなるように、stringIndices に。

  32. 各要素について、stringIndex を stringIndices から取り出して:

    1. string を、インデックス stringIndex の文字列記述子を読み取った結果とする。

    2. 追加する: string を reportItem["strings"] に。

  33. reportItem を返す。

次のHID インターフェイスがシステムで利用できなくなったとき、以下の手順を実行する:
  1. device を、HIDDevice のうち hid.[[devices]] 内でこのインターフェイスを表すものとする。

  2. hid を次の呼び出し結果とする: device の関連するグローバルオブジェクトの Navigator オブジェクトの hid 取得子。ただし、これは device の関連するグローバルオブジェクトが Window オブジェクトの場合であり、それ以外では、device の関連するグローバルオブジェクトの WorkerNavigator オブジェクトの hid 取得子の呼び出し結果とする。

  3. 削除する: device を hid.[[devices]] から。

  4. ユーザーが以前、サイトによる device へのアクセスを requestDevice() の呼び出しの結果として許可している場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは hid のもので、HID デバイスタスクソースを使用する。タスクではイベントを発火する。イベント名は disconnect、対象は hid、使用するインターフェイスは HIDConnectionEvent で、その device 属性を device に初期化する。

6.1. getDevices() メソッド

このgetDevices() メソッドの手順は次のとおりである:
  1. promise を新しいプロミスとする。

  2. document を null とする。

  3. this の関連するグローバルオブジェクトが DedicatedWorkerGlobalScope または window オブジェクトである場合、document を this の関連するグローバルオブジェクトの関連付けられた Document に設定する。

  4. this の関連するグローバルオブジェクトが ServiceWorkerGlobalScope オブジェクトであり、関連付けられたサービスワーカークライアントがウィンドウクライアントである場合、document を関連付けられた Document、すなわち関連付けられたサービスワーカークライアントのグローバルオブジェクトに対応するものに設定する。

  5. document が null であるか、document に使用が許可されていないポリシー制御機能の名前が "hid" である場合、拒否する: promise を "SecurityError" DOMException で。その後 promise を返す。

  6. 以下の手順を並列に実行する:

    1. devices を空の列(要素型: HIDDevice)とする。

    2. 各要素について、device を this.[[devices]] から取り出して:

      1. ユーザーが以前、サイトによる device へのアクセスを requestDevice() の呼び出しの結果として許可しており、かつ device.[[state]] が "forgotten" でない場合、追加する: device を devices に。

    3. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を devices で。

  7. promise を返す。

6.2. requestDevice() メソッド

次のrequestDevice() の権限ダイアログは、接続されたデバイスの一覧を提示し、そのうち一つを選ぶようユーザーに求める。

デバイスが複数のHID インターフェイスを持つ場合、ダイアログはそれらすべてを表す一つの項目のみを提示してもよい。ユーザーが複数のHID インターフェイスを表す項目を選択した場合、ユーザーエージェントはアクセスを許可しなければならない。対象はデバイスが公開するすべてのHID インターフェイスである。

次のrequestDevice() メソッドの手順は次のとおりである:
  1. promise を新しいプロミスとする。

  2. this の関連するグローバルオブジェクトの関連付けられた Document に使用が許可されていないポリシー制御機能の名前が "hid" である場合、拒否する: promise を "SecurityError" DOMException で。その後 promise を返す。

  3. 関連するグローバルオブジェクト(this のもの)が window でない場合、拒否する: promise を "NotSupportedError" DOMException で。その後 promise を返す。

  4. 関連するグローバルオブジェクト(this のもの)が一時的な活性化を持たない場合、拒否する: promise を "SecurityError" DOMException で。その後 promise を返す。

  5. options["filters"] が存在する場合、以下の手順を各要素について実行する。filter は options["filters"] の各要素とする:

    1. filter が有効なフィルターでない場合、拒否する: promise を TypeError で。その後 promise を返す。

  6. options["exclusionFilters"] が存在する場合、以下の手順を実行する:

    1. options["exclusionFilters"] が空である場合、拒否する: promise を TypeError で。その後 promise を返す。

    2. 各要素について、exclusionFilter を options["exclusionFilters"] から取り出して:

      1. exclusionFilter が有効なフィルターでない場合、拒否する: promise を TypeError で。その後 promise を返す。

  7. 以下の手順を並列に実行する:

    1. availableDevices を空のリストとして初期化する。

    2. 各要素について、device を this.[[devices]] から取り出して:

      1. device がいずれかのフィルターに一致する対象が options["filters"] であり、かつ device がいずれかのフィルターに一致することが options["exclusionFilters"] についてはない場合、追加する: device を availableDevices に。

    3. availableDevices 内のデバイス一覧を提示し、サイトによる HID デバイスへのアクセスを許可するようユーザーに求める。

      注: ユーザーエージェントは、ユーザーへの提示前にデバイス一覧を変更してもよい。たとえば、複数のHID インターフェイスを持つデバイスは、一つの項目で表現するべきであり、その項目を選択すると、デバイスが公開するすべてのインターフェイスへのアクセスが許可されるようにする。デバイスが単一のインターフェイスで実装されているか、その集まりで実装されているかは、ユーザーが知らないこともあり得る実装詳細であり、デバイスへのアクセス権限に関係するものと考慮するべきではない。

    4. devices を空の列(要素型: HIDDevice)とする。

    5. ユーザーがデバイスを選択しなかった場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を devices で。タスクをキューに入れたら、この手順を中止する。

    6. 各要素について、device を this.[[devices]] から取り出して:

      1. device がHID インターフェイスのうち選択されたデバイスが公開するものを表す場合、device.[[state]] を "closed" に設定し、追加する: device を devices に。

    7. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは device のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を devices で。

  8. promise を返す。

6.2.1. HIDDeviceRequestOptions 辞書

dictionary HIDDeviceRequestOptions {
    required sequence<HIDDeviceFilter> filters;
    sequence<HIDDeviceFilter> exclusionFilters;
};
filters メンバー、 型: sequence<HIDDeviceFilter>
HID デバイスのフィルター。
exclusionFilters メンバー、 型: sequence<HIDDeviceFilter>
HID デバイスの除外フィルター。

6.2.2. HIDDeviceFilter 辞書

dictionary HIDDeviceFilter {
    unsigned short vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};
vendorId メンバー、 型:unsigned short
照合対象のベンダー ID。
productId メンバー、 型:unsigned short
照合対象の製品 ID。vendorId メンバーが存在しない場合、productId は無視される。
usagePage メンバー、 型:unsigned short
照合対象の最上位コレクションの 用途ページ。
usage メンバー、 型:unsigned short
照合対象の最上位コレクションの 用途 ID。usagePage メンバーが存在しない場合、usage は無視される。
デバイスフィルターは、選択ダイアログでユーザーに提示するデバイス一覧を絞り込むために使用される。そのダイアログを作成するのはrequestDevice()である。フィルターが指定されていない場合、除外フィルターのどれにも一致しない接続済みデバイスがすべて含まれる。一つ以上のフィルターが指定されている場合、いずれかのフィルターに一致し、除外フィルターには一つも一致しないデバイスが含まれる。

すべての HIDDeviceFilter メンバーは任意である。各メンバーは一つの規則を指定する。HIDDeviceFilter に一致するには、すべての規則を満たさなければならない。空の HIDDeviceFilter は、どのデバイスにも一致する。

デバイス ID 規則は、ベンダー ID と製品 ID によってデバイスを選択するために使用する。アプリケーションが特定のデバイス専用に設計されている場合や、ベンダー固有の機能に依存する場合に有用である。vendorId 規則を含めると、フィルターは指定したベンダー ID を持つデバイスにのみ一致する。productId 規則も含めると、フィルターは指定したベンダー ID と製品 ID を持つデバイスにのみ一致する。productId は、vendorId 規則なしで指定された場合は無視される。

用途規則は、HID 用途のうちデバイスの最上位コレクションに割り当てられたものによって、デバイスを選択するために使用する。標準的な種類のデバイスを対象に設計されたアプリケーションに有用である。デバイスに一致するには、デバイスのコレクションの少なくとも一つが、すべての用途規則に一致しなければならない。usagePage 規則を含めると、フィルターは指定した用途ページを持つコレクションがデバイスに含まれる場合にのみ一致する。usage 規則も含めると、フィルターは指定した用途ページと用途 ID を持つデバイスにのみ一致する。usage は、usagePage 規則なしで指定された場合は無視される。

デバイス ID 規則と用途規則は組み合わせて使用してもよい。たとえば、アプリケーションは、特定のベンダーのデバイスのうち特定のデバイスクラスを実装するものだけに一致させることを求めてもよい。

exclusionFilters オプションを使用すると、アプリケーションは、requestDevice() が作成する選択ダイアログでユーザーに提示されるデバイスのうち、たとえば特定のデバイスクラスを実装していても期待どおり動作しないことが分かっているものを除外できる。

このHIDDeviceFilter filterについて、有効なフィルターであるのは、以下の手順が次の値を返す場合である:true:
  1. filter が空である場合、false を返す。

  2. filter["productId"] が存在し、filter["vendorId"] が存在しない場合、false を返す。

  3. filter["usage"] が存在し、filter["usagePage"] が存在しない場合、false を返す。

  4. true を返す。

このHIDDevice device がいずれかのフィルターに一致する対象は、次の列 filters(要素型:HIDDeviceFilter)である。ただし、以下の手順が次の値を返す場合に一致する:true:
  1. filters が空である場合、true を返す。

  2. 各要素について、filter を filters から取り出して:

    1. filter がデバイス ID に一致する対象が device であり、かつ filter がいずれかのコレクションに一致する対象が device である場合、true を返す。

  3. false を返す。

このHIDDeviceFilter filter がデバイス ID に一致する(対象: device)。以下の手順が次の値を返す場合に一致する:true:
  1. "vendorId" が filter に含まれる場合:

    1. filter["vendorId"] が device.vendorId に等しくない場合、false を返す。

    2. "productId" が filter に含まれ、filter["productId"] が device.productId に等しくない場合、false を返す。

  2. true を返す。

このHIDDeviceFilter filter がいずれかのコレクションに一致する(対象: device)。以下の手順が次の値を返す場合に一致する:true:
  1. 各要素について、collection を device.collections から取り出して:

    1. filter がコレクションに一致する対象が collection である場合、true を返す。

  2. false を返す。

このHIDDeviceFilter filter がコレクションに一致する(対象: collection)のは、以下の手順が次の値を返す場合である:true:
  1. "usagePage" が filter に含まれる場合:

    1. filter["usagePage"] が collection.usagePage に等しくない場合、false を返す。

    2. "usage" が filter に含まれ、filter["usage"] が collection.usage に等しくない場合、false を返す。

  2. true を返す。

7. HIDDevice インターフェイス

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDDevice : EventTarget {
    attribute EventHandler oninputreport;
    readonly attribute boolean opened;
    readonly attribute unsigned short vendorId;
    readonly attribute unsigned short productId;
    readonly attribute DOMString productName;
    readonly attribute FrozenArray<HIDCollectionInfo> collections;
    Promise<undefined> open();
    Promise<undefined> close();
    Promise<undefined> forget();
    Promise<undefined> sendReport([EnforceRange] octet reportId, BufferSource data);
    Promise<undefined> sendFeatureReport(
        [EnforceRange] octet reportId,
        BufferSource data);
    Promise<DataView> receiveFeatureReport([EnforceRange] octet reportId);
};

このインターフェイスのメソッドは通常、HID デバイスタスクソースに処理をキューに入れ、非同期に完了する。

HIDDevice のインスタンスは、次の表に記述された内部スロットを持つものとして作成される:

内部スロット 初期値 説明(非規範的)
[[state]] "closed" 次のものの動作状態を追跡する:HIDDevice
[[vendorId]] 0 次のベンダー ID(デバイスのもの)
[[productId]] 0 次の製品 ID(デバイスのもの)
[[productName]] "" 次の製品名(デバイスのもの)
[[collections]] 空の列、要素型: HIDCollectionInfo 次の最上位コレクション(作成方法: レポート記述子の構文解析)
[[pendingSendReportPromises]] 空のリスト 処理待ちのsendReport() Promiseの集合
[[pendingSendFeatureReportPromises]] 空のリスト 処理待ちのsendFeatureReport() Promiseの集合
[[pendingReceiveFeatureReportPromises]] 空のリスト 処理待ちのreceiveFeatureReport() Promiseの集合
oninputreport 属性、 型:EventHandler
oninputreport はイベントハンドラー IDL 属性であり、対象はinputreport イベント型である。
opened 属性、 型:boolean、読み取り専用
次のものについて、HIDDeviceがデータを転送できる状態であることを示すフラグ。
次のopened 取得子の手順は次のとおりである:
  1. this.[[state]] が opened である場合、true を返す。

  2. false を返す。

vendorId 属性、 型:unsigned short、読み取り専用
このベンダー IDは次の型のunsigned short値であり、ベンダー ID の発行元によって割り当てられ、デバイスの製造者を識別する。

vendorId 属性は、デバイスのベンダー ID である。デバイスがベンダー ID を持たないか、ベンダー ID にアクセスできない場合、属性は 0 でなければならない。

次のvendorId 取得子の手順は次のとおりである:
  1. this.[[vendorId]] を返す。

productId 属性、 型:unsigned short、読み取り専用
この製品 IDは次の型のunsigned short値であり、デバイスの製造者によって割り当てられ、製品を識別する。

productId 属性は、デバイスの製品 ID である。デバイスが製品 ID を持たないか、製品 ID にアクセスできない場合、属性は 0 でなければならない。

次のproductId 取得子の手順は次のとおりである:
  1. this.[[productId]] を返す。

productName 属性、 型:DOMString、読み取り専用
製品を識別する文字列。

USB HID デバイスでは、製品名には、デバイス記述子に指定されたインデックス iProduct の文字列記述子の値を含めるべきである。Bluetooth HID デバイスでは、製品名には Device Name 特性の値を含めるべきである。デバイスが製品名を持たないか、製品名が空またはアクセス不能である場合、属性は空文字列を返さなければならない。

productName 文字列には、シリアル番号や Bluetooth デバイスアドレスなど、デバイスを一意に識別するために使用できる識別子を含めるべきではない。

次のproductName 取得子の手順は次のとおりである:
  1. this.[[productName]] を返す。

collections 属性、 型: FrozenArray<HIDCollectionInfo>、読み取り専用
次の列(要素型: HIDCollectionInfo)。これは最上位コレクションを表す。その記述元はレポート記述子である.
次のcollections 取得子の手順は次のとおりである:
  1. this.[[collections]] を返す。

注: 最上位コレクションは、デバイス内で同様の目的を果たす項目をまとめる。アプリケーションはHID 用途を、最上位コレクションに適用されたものについて調べ、デバイスを識別する。特定の種類のデバイスに関する慣例に従わない場合、アプリケーションがデバイスを認識しないこともあり得る。標準的な HID デバイスの慣例的な動作の詳細は、[USBIF-HID-USAGE] を参照されたい。

入力レポートの受信元が次のものであるとき:device、以下の手順を実行する:
  1. 入力レポートがブロックされたレポートである場合、この手順を中止する。

  2. reportId を、このレポートのレポート ID とする。ただし、HID インターフェイスがレポート ID を使用するのでない場合は、0 とする。

  3. data を DataView とし、入力レポートを表すバイト列上に作成する。HID インターフェイスがレポート ID を使用する場合、バイト列にレポート ID のバイトを含めてはならない。

  4. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクではイベントを発火する。名前は inputreport、対象は device、使用するインターフェイスは HIDInputReportEvent で、その device 属性を device に、reportId 属性を reportId に、data 属性を data に初期化する。

7.1. open() メソッド

次のopen() メソッドの手順は次のとおりである:
  1. promise を新しいプロミスとする。

  2. this.[[state]] が "closed" でない場合、拒否する: promise を "InvalidStateError" DOMException で。その後 promise を返す。

  3. this.[[state]] を "opening" に設定する。

  4. 以下の手順を並列に実行する:

    1. オペレーティングシステムを呼び出して HID デバイスを開く。

    2. 何らかの理由でこれに失敗した場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは拒否する: promise を "NetworkError" DOMException で。タスクをキューに入れたら、この手順を中止する。

    3. this.[[state]] を "opened" に設定する。

    4. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を undefined で。

  5. promise を返す。

7.2. close() メソッド

次のclose() メソッドの手順は次のとおりである:
  1. promise を新しいプロミスとする。

  2. this.[[state]] が "forgotten"、"forgetting"、"opening"、または "closing" のいずれかである場合、拒否する: promise を "InvalidStateError" DOMException で。その後 promise を返す。

  3. this.[[state]] を "closing" に設定する。

  4. 各要素について、pendingPromise を this.[[pendingSendReportPromises]] から取り出して:

    1. 拒否する: pendingPromise を "AbortError" DOMException で。

  5. 空にする: this.[[pendingSendReportPromises]] を。

  6. 各要素について、pendingPromise を this.[[pendingSendFeatureReportPromises]] から取り出して:

    1. 拒否する: pendingPromise を "AbortError" DOMException で。

  7. 空にする: this.[[pendingSendFeatureReportPromises]] を。

  8. 各要素について、pendingPromise を this.[[pendingReceiveFeatureReportPromises]] から取り出して:

    1. 拒否する: pendingPromise を "AbortError" DOMException で。

  9. 空にする: this.[[pendingReceiveFeatureReportPromises]] を。

  10. 以下の手順を並列に実行する:

    1. オペレーティングシステムを呼び出して HID デバイスを閉じ、関連するすべてのリソースを解放する。

    2. this.[[state]] を "closed" に設定する。

    3. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を undefined で。

  11. promise を返す。

7.3. forget() メソッド

注: ユーザーエージェントは、API 間で権限を統合してもよい。たとえば、WebHID と WebUSB のデバイスアクセスを、統一された低水準デバイスアクセス権限で追跡することが考えられる。このため、このメソッドは将来、追加の(まだ規定されていない)権限も取り消すことがあり得る。

次のforget() メソッドの手順は次のとおりである:
  1. promise を新しいプロミスとする。

  2. 以下の手順を並列に実行する:

    1. 各要素について、device を this.[[devices]] から取り出して:

      1. device が HIDDevice とデバイスアクセス権限を共有していない場合、次のデバイスに進む。

      2. device.[[state]] を "forgetting" に設定する。

      3. 各要素について、pendingPromise を device.[[pendingSendReportPromises]] から取り出して:

        1. 拒否する: pendingPromise を "AbortError" DOMException で。

      4. 空にする: device.[[pendingSendReportPromises]] を。

      5. 各要素について、pendingPromise を device.[[pendingSendFeatureReportPromises]] から取り出して:

        1. 拒否する: pendingPromise を "AbortError" DOMException で。

      6. 空にする: device.[[pendingSendFeatureReportPromises]] を。

      7. 各要素について、pendingPromise を device.[[pendingReceiveFeatureReportPromises]] から取り出して:

        1. 拒否する: pendingPromise を "AbortError" DOMException で。

      8. 空にする: device.[[pendingReceiveFeatureReportPromises]] を。

      9. ユーザーエージェントを呼び出して、すべてのHID インターフェイスのうち device が公開するものへのアクセスを取り消す。

      10. device.[[state]] を "forgotten" に設定する。

    2. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を undefined で。

  3. promise を返す。

7.4. sendReport() メソッド

次のsendReport() メソッドは、出力レポートを送信するために使用し、指定する値はreportIdとdataである。次のHID インターフェイスが、次の動作、すなわちレポート ID を使用することをしない場合、レポート ID の代わりに 0 を渡す。

HID インターフェイスがレポート ID を使用する場合、レポート ID 値 0 は予約されているため、使用するべきではない。

sendReport() メソッドの手順は次のとおりである:

  1. promise を新しいプロミスとする。

  2. this.[[state]] が "opened" でない場合、拒否する: promise を "InvalidStateError" DOMException で。その後 promise を返す。

  3. reportId が 0 であり、HID インターフェイスのうち this が表すものがレポート ID を使用する場合、または、reportId が 0 でなく、そのインターフェイスがレポート ID を使用するのでない場合、拒否する: promise を "TypeError" DOMException で。その後 promise を返す。

  4. 追加する: promise を this.[[pendingSendReportPromises]] に。

  5. 以下の手順を並列に実行する:

    1. このレポートがブロックされたレポートである場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは拒否する: promise を "NotAllowedError" DOMException で。タスクをキューに入れたら、この手順を中止する。

    2. オペレーティングシステムを呼び出し、指定された reportId と data を持つ出力レポートを送信する。

    3. 何らかの理由でこれに失敗した場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは拒否する: promise を "NetworkError" DOMException で。タスクをキューに入れたら、この手順を中止する。

    4. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を undefined で。

  6. promise を返す。

7.5. sendFeatureReport() メソッド

次のsendFeatureReport() メソッドは、機能レポートを送信するために使用し、指定する値はreportIdとdataである。次のHID インターフェイスが、次の動作、すなわちレポート ID を使用することをしない場合、レポート ID の代わりに 0 を渡す。

HID インターフェイスがレポート ID を使用する場合、レポート ID 値 0 は予約されているため、使用するべきではない。

sendFeatureReport() メソッドの手順は次のとおりである:

  1. promise を新しいプロミスとする。

  2. this.[[state]] が "opened" でない場合、拒否する: promise を "InvalidStateError" DOMException で。その後 promise を返す。

  3. reportId が 0 であり、HID インターフェイスのうち this が表すものがレポート ID を使用する場合、または、reportId が 0 でなく、そのインターフェイスがレポート ID を使用するのでない場合、拒否する: promise を "TypeError" DOMException で。その後 promise を返す。

  4. 追加する: promise を this.[[pendingSendFeatureReportPromises]] に。

  5. 以下の手順を並列に実行する:

    1. このレポートがブロックされたレポートである場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは拒否する: promise を "NotAllowedError" DOMException で。タスクをキューに入れたら、この手順を中止する。

    2. オペレーティングシステムを呼び出し、指定された reportId と data を持つ機能レポートを送信する。

    3. 何らかの理由でこれに失敗した場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは拒否する: promise を "NetworkError" DOMException で。タスクをキューに入れたら、この手順を中止する。

    4. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を undefined で。

  6. promise を返す。

7.6. receiveFeatureReport() メソッド

次のreceiveFeatureReport() メソッドは、機能レポートを要求するために使用し、指定する値はreportIdである。次のHID インターフェイスが、次の動作、すなわちレポート ID を使用することをしない場合、レポート ID の代わりに 0 を渡す。

HID インターフェイスがレポート ID を使用する場合、レポート ID 値 0 は予約されているため、使用するべきではない。

receiveFeatureReport() メソッドの手順は次のとおりである:

  1. promise を新しいプロミスとする。

  2. this.[[state]] が "opened" でない場合、拒否する: promise を "InvalidStateError" DOMException で。その後 promise を返す。

  3. reportId が 0 であり、HID インターフェイスのうち this が表すものがレポート ID を使用する場合、または、reportId が 0 でなく、そのインターフェイスがレポート ID を使用するのでない場合、拒否する: promise を "TypeError" DOMException で。その後 promise を返す。

  4. 追加する: promise を this.[[pendingReceiveFeatureReportPromises]] に。

  5. 以下の手順を並列に実行する:

    1. このレポートがブロックされたレポートである場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは拒否する: promise を "NotAllowedError" DOMException で。タスクをキューに入れたら、この手順を中止する。

    2. data を DataView とし、バイト列上に作成する。そのバイト列は、オペレーティングシステムを呼び出して指定された reportId の機能レポートを読み取った結果を表す。

      注: data には、オペレーティングシステムから受信したレポートデータがそのまま含まれる。デバイスがレポート ID を使用する場合、最初のバイトはレポート ID であることもあり得る。このバイトを含めるのは、デバイスがレポート ID の代わりに別のデータを返すこともあり得るためである。

    3. 何らかの理由で機能レポートの読み取りに失敗した場合、グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは拒否する: promise を "NetworkError" DOMException で。タスクをキューに入れたら、この手順を中止する。

    4. グローバルタスクをキューに入れる。対象の関連するグローバルオブジェクトは this のもので、HID デバイスタスクソースを使用する。タスクでは解決する: promise を data で。

  6. promise を返す。

8. HIDConnectionEvent インターフェイス

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDConnectionEvent : Event {
    constructor(DOMString type, HIDConnectionEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
};
device 属性、 型:HIDDevice、読み取り専用
次のHIDDevice インスタンスであり、接続された、または切断されたデバイスを表す。

8.1. HIDConnectionEventInit 辞書

dictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};
device メンバー、 型:HIDDevice
イベントに関連付けられたデバイス。

9. HIDInputReportEvent インターフェイス

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDInputReportEvent : Event {
    constructor(DOMString type, HIDInputReportEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
    readonly attribute octet reportId;
    readonly attribute DataView data;
};
device 属性、 型:HIDDevice、読み取り専用
次のHIDDevice インスタンスであり、次のHID インターフェイスのうち入力レポートを送信したものを表す。
reportId 属性、 型:octet、読み取り専用
このレポートの 1 バイトの識別接頭辞。ただし、HID インターフェイスが次の動作を行わない場合は 0 とする: レポート ID を使用する.
data 属性、 型:DataView、読み取り専用
次のDataViewに入力レポートのデータを格納したもの。ただし、除外するのはreportId のバイトである。ただし、これはHID インターフェイス がレポート ID を使用する場合に限る.

9.1. HIDInputReportEventInit 辞書

dictionary HIDInputReportEventInit : EventInit {
    required HIDDevice device;
    required octet reportId;
    required DataView data;
};
device メンバー、 型:HIDDevice
イベントに関連付けられたデバイス。
reportId メンバー、 型:octet
入力レポートのレポート ID。
data メンバー、 型:DataView
入力レポートのデータ。

10. HIDCollectionInfo 辞書

dictionary HIDCollectionInfo {
    unsigned short usagePage;
    unsigned short usage;
    octet type;
    sequence<HIDCollectionInfo> children;
    sequence<HIDReportInfo> inputReports;
    sequence<HIDReportInfo> outputReports;
    sequence<HIDReportInfo> featureReports;
};

デバイスがシステムに初めて接続されたとき、システムはレポート記述子を、デバイスが公開する各HID インターフェイスについて取得しなければならない。レポート記述子はバイト列であり、デバイスがサポートする各レポートの配置を記述する階層的なデータ構造に展開できる。このデータ構造の要素を項目という。互いに関係を持つ項目の集まりをコレクションという。

HIDCollectionInfo オブジェクトは、レポート記述子内の一つのコレクションを表す。コレクションが入れ子のコレクションを含む場合、入れ子のコレクションは children の要素として含まれる。

inputReports、outputReports、featureReports の各属性は列を含み、その要素である HIDReportInfo は、このコレクション内に記述された各レポートに関する情報を提供する。最上位コレクションの場合、HIDReportInfo はレポートを構成するすべての項目を平坦化した表現である。この表現では、入れ子のコレクション内の項目を最上位コレクション内の項目と混在させる。入れ子のコレクションの場合、HIDReportInfo には、そのコレクションとその入れ子のコレクションに含まれる項目のみを含める。

usagePage メンバー、 型:unsigned short
次の用途ページの成分。これはHID 用途のうち、このコレクションに関連付けられたものに属する。

HID 用途は、アプリケーションが解釈して項目またはコレクションの目的と意味を識別できる定数である。HID 用途は unsigned long 値であり、unsigned short 型の用途ページを上位ビットに、unsigned short 型の用途 ID を下位ビットにして構成する。標準的なHID 用途の値は、[USBIF-HID-CLASS] およびUSB Implementers Forum が発行するその他の文書に記述されている。

HID 用途のうち、デバイスが公開する最上位コレクションのものは、デバイスの大まかな種類を識別するために使用される。

usage メンバー、 型:unsigned short
次の用途 IDの成分。これはHID 用途のうち、このコレクションに関連付けられたものに属する。

用途 ID は、個々のHID 用途を用途ページ上で選択するために使用される。慣例により、用途 ID の 0x01 から 0x1F は最上位コレクション用に予約されている。

type メンバー、 型:octet
次のものを表す値:コレクションの種類.
コレクションの種類 値
物理 0x00
アプリケーション 0x01
論理 0x02
レポート 0x03
名前付き配列 0x04
用途切り替え 0x05
用途変更 0x06
将来の使用のために予約 0x07 から 0x7F
ベンダー定義 0x80 から 0xFF

各コレクションの種類は、まとめられた項目間の異なる関係を記述する。[USBIF-HID-CLASS] の 6.2.2.6 節に、コレクションの種類の詳細がある。

children メンバー、 型: sequence<HIDCollectionInfo>
次の列(要素型: HIDCollectionInfo)。このコレクション内に入れ子になったコレクションを表す。
inputReports メンバー、 型: sequence<HIDReportInfo>
次の列(要素型: HIDReportInfo)。このコレクション内に記述された入力レポートを表す。
outputReports メンバー、 型: sequence<HIDReportInfo>
次の列(要素型: HIDReportInfo)。このコレクション内に記述された出力レポートを表す。
featureReports メンバー、 型: sequence<HIDReportInfo>
次の列(要素型: HIDReportInfo)。このコレクション内に記述された機能レポートを表す。

11. HIDReportInfo 辞書

dictionary HIDReportInfo {
    octet reportId;
    sequence<HIDReportItem> items;
};

HIDReportInfo は、レポート記述子内の一つの入力、出力、または機能レポートを表す。

reportId メンバー、 型:octet
このHID インターフェイス がレポート ID を使用するとは、レポートの転送ごとに 1 バイトの識別接頭辞を先頭に付けることをいう。reportId メンバーは、このレポートの接頭辞である(インターフェイスがレポート ID を使用する場合)。それ以外の場合は 0 である。
items メンバー、 型: sequence<HIDReportItem>
次の列(要素型: HIDReportItem)。このレポートのフィールドを表す。

12. HIDReportItem 辞書

dictionary HIDReportItem {
    boolean isAbsolute;
    boolean isArray;
    boolean isBufferedBytes;
    boolean isConstant;
    boolean isLinear;
    boolean isRange;
    boolean isVolatile;
    boolean hasNull;
    boolean hasPreferredState;
    boolean wrap;
    sequence<unsigned long> usages;
    unsigned long usageMinimum;
    unsigned long usageMaximum;
    unsigned short reportSize;
    unsigned short reportCount;
    byte unitExponent;
    HIDUnitSystem unitSystem;
    byte unitFactorLengthExponent;
    byte unitFactorMassExponent;
    byte unitFactorTimeExponent;
    byte unitFactorTemperatureExponent;
    byte unitFactorCurrentExponent;
    byte unitFactorLuminousIntensityExponent;
    long logicalMinimum;
    long logicalMaximum;
    long physicalMinimum;
    long physicalMaximum;
    sequence<DOMString> strings;
};
isAbsolute メンバー、 型:boolean
true(データが絶対値、つまり固定した原点に基づく場合)。またはfalse(データが相対値、つまり前回のレポートからの値の変化を示す場合)。
isArray メンバー、 型:boolean
true(項目がレポート内に配列データフィールドを作成し、各データフィールドが押されたボタンまたはキーに対応するインデックスを含む場合)。またはfalse(項目がレポート内に可変データフィールドを作成し、各データフィールドが値を含む場合)。
isBufferedBytes メンバー、 型:boolean
true(項目が固定長のバイトストリームを出力する場合)。またはfalse(項目が数値量である場合)。
isConstant メンバー、 型:boolean
true(項目が静的な読み取り専用フィールドであり、変更できない場合)。またはfalse(項目が、変更可能なデバイスデータを含むレポートフィールドを定義する場合)。
isLinear メンバー、 型:boolean
true(項目が、測定対象と報告値の間の線形関係を表す場合)。またはfalse(データが何らかの方法で処理されている場合)。
isRange メンバー、 型:boolean
true(項目が用途を次のHID 用途の範囲から割り当てる場合。その範囲の定義はusageMinimumとusageMaximumである)。またはfalse(項目が持つのは次の列であり、その要素はHID 用途の値である)。格納先は usages.
isVolatile メンバー、 型:boolean
true(項目の値がホストとのやり取りなしに変わり得る場合)。またはfalse(項目の値を変更するのはホストのみにするべき場合)。

Feature 項目と Output 項目にのみ使用される。

hasNull メンバー、 型:boolean
true(項目が、有意なデータを送信しないヌル状態を持つ場合)。またはfalse(ヌル状態を持たない場合)。ヌル状態では、項目は指定された次の範囲外の値を報告する:logicalMinimumとlogicalMaximum.
hasPreferredState メンバー、 型:boolean
true(ユーザーが操作部を物理的に操作していないときに戻る優先状態を、項目が持つ場合)。またはfalse(項目が優先状態を持たない場合)。
wrap メンバー、 型:boolean
true(項目の値が上限または下限に達すると折り返す場合)。またはfalse(項目の値が折り返さない場合)。
usages メンバー、 型:sequence<unsigned long>
もしisRange がtrueであるか、この項目に関連付けられたHID 用途の値が存在しない場合、usagesは undefined でなければならない。

isRange が false である場合、usages は列であり、その値はこの項目に関連付けられたHID 用途である。

usageMinimum メンバー、 型:unsigned long
もしisRange がtrueである場合、usageMinimumには、最小のHID 用途値(この項目に関連付けられた用途範囲内)が含まれる。

isRange が false である場合、usageMinimum は undefined でなければならない。

usageMaximum メンバー、 型:unsigned long
もしisRange がtrueである場合、usageMaximumには、最大のHID 用途値(この項目に関連付けられた用途範囲内)が含まれる。

isRange が false である場合、usageMaximum は undefined でなければならない。

reportSize メンバー、 型:unsigned short
各レポートデータフィールドのサイズ(ビット単位)。reportSizeは 0 より大きくなければならない。
reportCount メンバー、 型:unsigned short
この項目についてレポートに含まれるフィールド数。reportCountは 0 より大きくなければならない。
unitExponent メンバー、 型:byte
単位指数の値。項目に単位定義がない場合は 0。
unitSystem メンバー、 型:HIDUnitSystem
次のHIDUnitSystemの列挙値で、単位定義の単位系を指定する。または"none"(項目に単位定義がない場合)。
unitFactorLengthExponent メンバー、 型:byte
単位定義における長さの単位(センチメートル、ラジアン、インチ、または度)の指数の値。項目に単位定義がない場合は 0。
unitFactorMassExponent メンバー、 型:byte
単位定義における質量の単位(グラムまたはスラグ)の指数の値。項目に単位定義がない場合は 0。
unitFactorTimeExponent メンバー、 型:byte
単位定義における時間の単位(秒)の指数の値。項目に単位定義がない場合は 0。
unitFactorTemperatureExponent メンバー、 型:byte
単位定義における温度の単位(ケルビンまたは華氏度)の指数の値。項目に単位定義がない場合は 0。
unitFactorCurrentExponent メンバー、 型:byte
単位定義における電流の単位(アンペア)の指数の値。項目に単位定義がない場合は 0。
unitFactorLuminousIntensityExponent メンバー、 型:byte
単位定義における光度の単位(カンデラ)の指数の値。項目に単位定義がない場合は 0。
logicalMinimum メンバー、 型:long
論理単位での、この項目の最小範囲。可変項目または配列項目が報告する最小値である。
logicalMaximum メンバー、 型:long
論理単位での、この項目の最大範囲。可変項目または配列項目が報告する最大値である。
physicalMinimum メンバー、 型:long
この項目の物理的な範囲の最小値。これはlogicalMinimumに単位を適用したものを表す。
physicalMaximum メンバー、 型:long
この項目の物理的な範囲の最大値。これはlogicalMaximumに単位を適用したものを表す。
strings メンバー、 型: sequence<DOMString>
この項目に関連付けられた文字列。または、空の列(この項目に関連付けられた文字列がない場合)。

13. HIDUnitSystem 列挙型

[USBIF-HID-CLASS] の 6.2.2.7 節は、SI 線形、SI 回転、英国式線形、英国式回転という四つの標準単位系を定義する。各項目は、これら四つの単位系のいずれか、ベンダー定義の単位系、または単位系なしを使用する。

enum HIDUnitSystem {
    "none", "si-linear", "si-rotation", "english-linear",
    "english-rotation", "vendor-defined", "reserved"
};
"none"
単位系なし。項目が単位定義を持たないことを示す。
"si-linear"
SI 線形単位系は、センチメートル、グラム、秒、ケルビン、アンペア、カンデラを使用する。
"si-rotation"
SI 回転単位系は、ラジアン、グラム、秒、ケルビン、アンペア、カンデラを使用する。
"english-linear"
英国式線形単位系は、インチ、スラグ、秒、華氏度、アンペア、カンデラを使用する。
"english-rotation"
英国式回転単位系は、度、スラグ、秒、華氏度、アンペア、カンデラを使用する。
"vendor-defined"
ベンダー定義の単位系。
"reserved"
デバイスが単位系として予約値を使用したことを示す。

14. 使用例

ページからアクセス可能なデバイスの一覧を取得する。既定では、ページはどのデバイスへのアクセス権限も付与されていないため、何にもアクセスできない。
document.addEventListener('DOMContentLoaded', async () => {
  let devices = await navigator.hid.getDevices();
  devices.forEach(device => {
    console.log(`HID: ${device.productName}`);
  });
});
HID デバイスの接続と切断のイベントリスナーを登録する。
navigator.hid.addEventListener('connect', ({device}) => {
  console.log(`HID connected: ${device.productName}`);
});

navigator.hid.addEventListener('disconnect', ({device}) => {
  console.log(`HID disconnected: ${device.productName}`);
});
デバイスは次のメソッドからはアクセスできず、getDevices()接続イベントも生成しない。ただし、デバイスへのアクセス権限が付与された後は可能になる。ページは権限を要求してもよい。そのために使用するのはrequestDevice()である。この例では、ページは次のベンダー ID 0xABCDを持つデバイスへのアクセスを要求する。また、デバイスは条件を満たさなければならない。その条件は、コレクションを持ち、その用途ページが Consumer(0x000C)、その用途 IDが Consumer Control(0x0001)であること。次の製品 ID 0x1234を持つデバイスは、正常に動作しないことが報告されている。
let requestButton = document.getElementById("request-hid-device");
requestButton.addEventListener("click", async () => {
  let device;
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          vendorId: 0xabcd,
          usagePage: 0x000c,
          usage: 0x0001,
        },
      ],
      exclusionFilters: [
        {
          vendorId: 0xabcd,
          productId: 0x1234,
        }
      ],
    });
    device = devices[0];
  } catch (error) {
    console.log("An error occurred.");
  }

  if (!device) {
    console.log("No device was selected.");
  } else {
    console.log(`HID: ${device.productName}`);
  }
});
入力レポートイベントのイベントリスナーを登録する。
device.oninputreport = ({device, reportId, data}) => {
  console.log(`Input report ${reportId} from ${device.productName}:`,
              new Uint8Array(data.buffer));
};

if (!device.opened)
  await device.open();
出力レポートを送信する。
try {
  if (!device.opened)
    await device.open();

  const outputReportData = new Uint8Array([0x12, 0x34, 0x56, 0x78]);
  await device.sendReport(0x05, outputReportData);
  console.log("Output report sent");
} catch (error) {
  console.log("An error occurred.")
}
機能レポートの読み取りと書き込みを行う。
try {
  if (!device.opened)
    await device.open();

  const oldFeatureData = await device.receiveFeatureReport(0x80);
  console.log("Feature report received:", new Uint8Array(oldFeatureData.buffer));

  const newFeatureData = new Uint8Array([0x12, 0x34, 0x56, 0x78]);
  await device.sendFeatureReport(0x80, newFeatureData);
  console.log("Feature report sent");
} catch (error) {
  console.log("An error occurred.")
}

15. HID ブロックリスト

この仕様は、https://github.com/whatwg/hid リポジトリー内のブロックリストファイルに依存して、ウェブサイトがアクセスできる HID デバイスの集合を制限する。

次の操作、すなわちブロックリストの構文解析を URLurlに対して行った結果は、次の列であり、その要素は辞書オブジェクトである。これは次の URL を取得し、urlその内容を JSON として構文解析することで生成する。

HID ブロックリストは、ブロックリストの構文解析を https://hid.spec.whatwg.org/blocklist.txt に対して行った結果である。

レポートがブロックされたレポートであるのは、以下の手順が次の値を返す場合である:true:
  1. 各要素について、rule をHID ブロックリストから取り出して:

    1. レポートがブロックリスト規則によってブロックされる対象の規則が rule である場合、true を返す。

  2. false を返す。

レポートがブロックリスト規則によってブロックされる(対象の規則: rule)のは、以下の手順が次の値を返す場合である:true:
  1. reportId を、このレポートのレポート ID とする。ただし、HID インターフェイスがレポート ID を使用するのでない場合は、0 とする。

  2. reportType を、入力レポートの場合は "input"、出力レポートの場合は "output"、機能レポートの場合は "feature" とする。

  3. collection を、このレポートを含む最上位コレクションとする。

  4. rule が "vendor" を含み、rule["vendor"] が device.vendorId でない場合、false を返す。

  5. rule が "product" を含み、rule["product"] が device.productId でない場合、false を返す。

  6. rule が "reportId" を含み、rule["reportId"] が reportId でない場合、false を返す。

  7. rule が "reportType" を含み、rule["reportType"] が reportType でない場合、false を返す。

  8. rule が "usagePage" を含み、rule["usagePage"] が collection["usagePage"] でない場合、false を返す。

  9. rule が "usage" を含み、rule.["usage"] が collection["usage"] でない場合、false を返す。

  10. true を返す。

16. 他の仕様との統合

16.1. 権限ポリシー

この仕様は、hid 属性を Navigator オブジェクト上に公開するかどうかを制御する機能を定義する。

この機能の機能名は "hid" である。

この機能の既定の許可リストは 'self' である。

謝辞

すばらしい貢献をしてくれた Feras Aldahlawi、François Beaufort、Jack Hsieh、Jeffrey Yasskin、Jonas Due Vesterheden、Kagami Sascha Rosylight、Marcos Cáceres、Peter Høy Andersen、Reilly Grant、Rob Pitkin、Ted Mielczarek、Thomas Steiner、Tim Steiner、Vincent Scheib に感謝する。

この標準の執筆者は Matt Reynolds(Google、mattreynolds@google.com)である。

知的財産権

Copyright © WHATWG(Apple、Google、Mozilla、Microsoft)。この著作物は、クリエイティブ・コモンズ 表示 4.0 国際ライセンスの下で提供される。その一部がソースコードに組み込まれる場合、ソースコード内のその部分には、代わりにBSD 3 条項ライセンスが適用される。

索引

この仕様で定義する用語

参照先で定義される用語

参考文献

規範的な参考文献

[DOM]
Anne van Kesteren.DOM Standard。現行標準。URL:https://dom.spec.whatwg.org/
[HTML]
Anne van Kesteren ほか。HTML Standard。現行標準。URL:https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola.Infra Standard。現行標準。URL:https://infra.spec.whatwg.org/
[PERMISSIONS-POLICY-1]
Ian Clelland; Ari Chivukula.権限ポリシー。URL:https://w3c.github.io/webappsec-permissions-policy/
[POINTEREVENTS3]
Patrick Lauke; Robert Flack.Pointer Events。URL:https://w3c.github.io/pointerevents/
[SERVICE-WORKERS]
Monica CHINTALA; Yoshisato Yanagisawa.Service Workers Nightly。URL:https://w3c.github.io/ServiceWorker/
[UIEVENTS]
Xiaoqian Wu.UI Events。URL:https://w3c.github.io/uievents/
[USBIF-HID-CLASS]
Mike Bergman ほか。Device Class Definition for Human Interface Devices (HID) version 1.11。2001年5月27日。仕様。URL:https://www.usb.org/document-library/device-class-definition-hid-111
[WEBIDL]
Edgar Chen; Timothy Gu.Web IDL Standard。現行標準。URL:https://webidl.spec.whatwg.org/

参考情報の文献

[BROWSEREXT]
Mike Pietraszak.Browser Extensions。2016年10月。コミュニティグループ報告書草案。URL:https://browserext.github.io/browserext/
[GAMEPAD]
Steve Agoston; Matthew Reynolds.Gamepad。URL:https://w3c.github.io/gamepad/
[USBIF-HID-USAGE]
David Abzarian ほか。HID Usage Tables for Universal Serial Bus (USB) version 1.22。2021年4月6日。仕様。URL:https://www.usb.org/document-library/hid-usage-tables-122

IDL 索引

[SecureContext] partial interface Navigator {
    [SameObject] readonly attribute HID hid;
};

[Exposed=(DedicatedWorker,ServiceWorker), SecureContext]
partial interface WorkerNavigator {
    [SameObject] readonly attribute HID hid;
};

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HID : EventTarget {
    attribute EventHandler onconnect;
    attribute EventHandler ondisconnect;
    Promise<sequence<HIDDevice>> getDevices();
    [Exposed=Window] Promise<sequence<HIDDevice>> requestDevice(
        HIDDeviceRequestOptions options);
};

dictionary HIDDeviceRequestOptions {
    required sequence<HIDDeviceFilter> filters;
    sequence<HIDDeviceFilter> exclusionFilters;
};

dictionary HIDDeviceFilter {
    unsigned short vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDDevice : EventTarget {
    attribute EventHandler oninputreport;
    readonly attribute boolean opened;
    readonly attribute unsigned short vendorId;
    readonly attribute unsigned short productId;
    readonly attribute DOMString productName;
    readonly attribute FrozenArray<HIDCollectionInfo> collections;
    Promise<undefined> open();
    Promise<undefined> close();
    Promise<undefined> forget();
    Promise<undefined> sendReport([EnforceRange] octet reportId, BufferSource data);
    Promise<undefined> sendFeatureReport(
        [EnforceRange] octet reportId,
        BufferSource data);
    Promise<DataView> receiveFeatureReport([EnforceRange] octet reportId);
};

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDConnectionEvent : Event {
    constructor(DOMString type, HIDConnectionEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
};

dictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDInputReportEvent : Event {
    constructor(DOMString type, HIDInputReportEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
    readonly attribute octet reportId;
    readonly attribute DataView data;
};

dictionary HIDInputReportEventInit : EventInit {
    required HIDDevice device;
    required octet reportId;
    required DataView data;
};

dictionary HIDCollectionInfo {
    unsigned short usagePage;
    unsigned short usage;
    octet type;
    sequence<HIDCollectionInfo> children;
    sequence<HIDReportInfo> inputReports;
    sequence<HIDReportInfo> outputReports;
    sequence<HIDReportInfo> featureReports;
};

dictionary HIDReportInfo {
    octet reportId;
    sequence<HIDReportItem> items;
};

dictionary HIDReportItem {
    boolean isAbsolute;
    boolean isArray;
    boolean isBufferedBytes;
    boolean isConstant;
    boolean isLinear;
    boolean isRange;
    boolean isVolatile;
    boolean hasNull;
    boolean hasPreferredState;
    boolean wrap;
    sequence<unsigned long> usages;
    unsigned long usageMinimum;
    unsigned long usageMaximum;
    unsigned short reportSize;
    unsigned short reportCount;
    byte unitExponent;
    HIDUnitSystem unitSystem;
    byte unitFactorLengthExponent;
    byte unitFactorMassExponent;
    byte unitFactorTimeExponent;
    byte unitFactorTemperatureExponent;
    byte unitFactorCurrentExponent;
    byte unitFactorLuminousIntensityExponent;
    long logicalMinimum;
    long logicalMaximum;
    long physicalMinimum;
    long physicalMaximum;
    sequence<DOMString> strings;
};

enum HIDUnitSystem {
    "none", "si-linear", "si-rotation", "english-linear",
    "english-rotation", "vendor-defined", "reserved"
};