WebHID API

HID入力デバイスの最も一般的なカテゴリは、既存の高レベル入力APIを通してウェブプラットフォームできちんとサポートされています。例えば、マウス入力は PointerEventで、キーボード入力は KeyboardEventで利用可能です。これらのデバイスからの入力は、ホストのネイティブHIDドライバーによって処理され、通常デバイス固有のドライバーや設定なしで動作します。WebHIDは、このように高レベル入力APIですでに十分サポートされているデバイスを対象としていません。

一部のHIDデバイスカテゴリでは、ウェブプラットフォームがデバイスの一部機能のみをサポートし、他の機能へのアクセスを制限している場合があります。例えば、[GAMEPAD]は、ほとんどのゲームコントローラーの入力機能をサポートしていますが、LEDインジケーターや音声などあまり一般的でない機能はサポートしていません。これらの機能はホストAPIであまりサポートされないことが多く、ユーザーエージェント内での対応は高い複雑性をもたらします。WebHIDは、高レベルAPIが提供する機能が不十分な場合にアプリケーション側で代替を提供できます。

多くのHIDデバイスは、どのウェブプラットフォームAPIからもサポートされていません。HID仕様では仮想現実コントローラー、フライトシミュレータ、医療機器など、さまざまなデバイスがHIDでサポート可能であると記載されています。WebHIDにより、追加のドライバーやユーザーエージェントの改変無しで、これらのデバイスが利用可能になります。

HIDはプロトタイピングやホビイストの用途に魅力的です。なぜなら、各ホストごとに専用のドライバーを必要とせず、汎用のHIDドライバーを使えるためです。また、簡略化されたインストール手順により、教育者がシステム構成を変更することなく、学生全員のPCに機器を展開しやすくなっています。ウェブプラットフォーム経由でHIDデバイスにアクセスできれば、特定ホスト専用アプリケーションでのみサポートされている現状よりも、インストール要件がさらに減少します。

HID周辺機器は強力な機能を持つ場合があり、ユーザーの明示的な同意なしにページからアクセス可能にすべきではありません。例えば、HID周辺機器が周囲の情報を収集できるセンサーを搭載していることがあります。デバイスが秘匿情報を保存しており、それが漏洩や上書きされるべきではない場合もあります。多くのデバイスはファームウェアアップグレード機能を持っています。OSは通常、HIDデバイスへのアプリケーションからのアクセスを制限していないため、このアクセスが悪用されてデバイスが破損したり、保存されているデータが損なわれたりすることがあります。

場合によっては、Webページから全くアクセス可能にすべきでない機能がデバイスに存在することもあります。特定のデバイスは、vendor IDやproduct IDの認識によってブロックし、列挙時に非表示にすることができます。report descriptor によってデバイスは自らの機能を記述でき、この情報を使えば、vendor IDやproduct IDが事前に判明しない場合でもデバイスカテゴリのブロックが可能です。これは、HID usage値をreport descriptor内のコレクションに割り当てて検査することで実現できます。例えば、キーボード的なデバイスには、そのtop-level collectionにHID usageでキーボードカテゴリが含まれている場合、アクセスを拒否できます。

悪用を防ぐため、ユーザーが明示的に許可を与えるまで、デバイスはページに利用可能となりません。アクセスはまずページからリクエストされ、ユーザーが利用可能デバイスの一覧から選択した後に与えられます。ページがアクセス許可を得た後は、デバイスが使用中であることを示すインジケーターが表示されます。

HIDプロトコルは非常に柔軟であり、これを活用した多様なデバイスが設計されています。そのため、デバイスへのアクセスが、悪意のあるページによってデバイス自体を損傷する様々な可能性があります。ファームウェアアップデートをカスタムHIDレポートで送信できるHID周辺機器も少なくありません。デバイスメーカーは、ファームウェアバイナリが正規のものであることを確認する仕組みをファームウェアアップグレード機構に組み込む必要があり、またダウングレードによってセキュリティが低下しないよう保護するべきです。信頼されていないアップグレードは、デバイスに新機能を追加したり、まったく別のタイプのデバイスを装う原因になり得ます。

一部のデバイスは、予期される範囲外の入力を与えることで損傷する場合があります。例えば、ゲームパッドの振動機能は、不正な振動コマンドがページから送信されると損傷する可能性があります。

一般に、これらの種の攻撃はデバイス固有のものであり、APIレベルでの緩和は困難です。

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

マウスやキーボードは通常HID周辺機器として実装されており、信頼された入力も生成可能です。HIDキーボードやマウスは、プログラマブルマクロのような高度な機能を持つ場合もあり、これにより入力のシーケンスを記録し、後で再生できます。デバイスメーカーは、悪意あるアプリが予期しない入力シーケンスでデバイスを再プログラミングしたり、ユーザーの明示的な同意なしにマクロ再生をトリガーすることがないように注意して設計する必要があります。

セキュリティおよびプライバシーリスクを軽減するため、ユーザーエージェントはデバイスアクセス要求時に選択式のUIフローを実装することが推奨されます。ページがHIDデバイスへのアクセスを要求した場合、ユーザーエージェントはそのページがデバイスにアクセスしたい旨を通知するダイアログを表示すべきです。このダイアログには接続されたHIDデバイスの一覧を表示し、その中からページ上で公開するデバイスをユーザーに選択してもらうよう求めるべきです。偶発的なクリックを減らすため、デバイス選択と、選択の確定・ダイアログの閉鎖とで、少なくとも2度の操作を必要としてください。

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

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

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

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

WebIDL[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);
};

Note

ユーザーエージェントの実装は、Navigator の hid 属性を条件付きで公開することを選択できる場合があります。これは、Navigator の関連グローバルオブジェクトが ServiceWorkerGlobalScope のときです。例えば、 [browserext] のブラウザー拡張機能のコンテキストにおいて。

HID のインスタンスは、次の表に記載の内部スロットとともに作成されます。

内部スロット	初期値	説明（非規範的）
[[devices]]	空の順序付き集合	システムで現在利用可能な HID インターフェイスを表す `HIDDevice` インスタンスの順序付き集合

onconnect 属性: onconnect は、イベントハンドラー IDL 属性であり、 connect イベント型に対応します。
ondisconnect 属性: ondisconnect は、イベントハンドラー IDL 属性であり、 disconnect イベント型に対応します。

システムで HID インターフェイスが利用可能になったとき、次の手順を実行します。

Note

HID インターフェイスは、HID プロトコルを介してデバイスと通信するために使用できる論理的インターフェイスです。各 HID インターフェイスは、そのインターフェイスでサポートされるレポート集合を記述する report descriptor を 1 つだけ持ちます。1 つの物理デバイスが 1 つ以上の HID インターフェイスを公開する場合があります。複数の HID インターフェイスを持つデバイスは、各インターフェイスごとにこれらの手順を 1 回実行します。

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

device を HIDDevice とします。
device.[[vendorId]] を、そのインターフェイスを公開しているデバイスの vendor ID に設定します。
device.[[productId]] を、そのインターフェイスを公開しているデバイスの product ID に設定します。
device.[[productName]] を、そのインターフェイスを公開しているデバイスの product name に設定します。
device.[[collections]] を、 Report descriptor を解析した結果に設定します。
hid を、device の関連グローバルオブジェクトが Window オブジェクトである場合は、その Navigator オブジェクトの hid ゲッターを呼び出した結果とし、そうでない場合は WorkerNavigator オブジェクトの hid ゲッターを呼び出した結果とします。
Append により、device を hid.[[devices]] に追加します。
以前の requestDevice() の呼び出し結果としてユーザーがサイトに device へのアクセスを許可している場合は、queue a global task を関連グローバルオブジェクト上で実行し、HID device task source を用いてイベントを発火し、hid に対して connect という名前のイベントを、HIDConnectionEvent を使用して発生させ、その device 属性を device に初期化します。

report descriptor を解析するには、次の手順を実行します。

Note

システムは通常、デバイスが最初に接続されたときに各 HID インターフェイスの report descriptor のバイト列を読み取り、値をシステムレジストリにキャッシュします。report descriptor が利用できないが、各レポートのレイアウトを再構成するために使用できる情報をシステムが提供する場合、ユーザーエージェントは report descriptor の解析の代わりに別のアルゴリズムを使用してもよいです。

report descriptor の形式は [USBIF-HID-CLASS] の 6.2.2 節に記述されています。以下のアルゴリズムは、その節で説明されている解析アルゴリズムと同じものを実装することを意図しています。

report descriptor には 3 つのクラスのアイテムが含まれます。Main items はデータフィールドの定義とグループ化に使用されます。Global items と Local items はデータフィールドを記述します。 Local items は次の Main item にのみ適用される特性を定義し、Global items は、その後に定義されるすべての Main items に影響する特性を定義します。

各アイテムは、0、1、2、または 4 バイトの当該アイテムに関連するデータを含む item data field と、bSize field という、item data field の格納に使用されるバイト数を記述するフィールドを持ちます。各アイテムには、その種類を識別するタグもあります。

items を、report descriptor のバイト列を list へ変換した結果とし、そのリストの要素は Main items、Global items、および Local items とします。
collections を空の sequence（要素は HIDCollectionInfo）として初期化します。
ancestors を空の list として初期化します。
localState を空の ordered map として初期化します。
usages を空の sequence（要素は unsigned long）として初期化します。
stringIndices を空の list として初期化します。
globalStack を空の stack として初期化します。
initialGlobalState を空の ordered map として初期化します。
reportId を 0 に初期化します。
initialGlobalState["unitSystem"] を "none" に設定します。
initialGlobalState["unitExponent"] を 0 に設定します。
initialGlobalState["unitFactorLengthExponent"] を 0 に設定します。
initialGlobalState["unitFactorMassExponent"] を 0 に設定します。
initialGlobalState["unitFactorTimeExponent"] を 0 に設定します。
initialGlobalState["unitFactorTemperatureExponent"] を 0 に設定します。
initialGlobalState["unitFactorCurrentExponent"] を 0 に設定します。
initialGlobalState["unitFactorLuminousIntensityExponent"] を 0 に設定します。
initialGlobalState["logicalMinimum"] を 0 に設定します。
initialGlobalState["logicalMaximum"] を 0 に設定します。
initialGlobalState["physicalMinimum"] を 0 に設定します。
initialGlobalState["physicalMaximum"] を 0 に設定します。
Push により、 initialGlobalState を globalStack にプッシュします。
For each により、items の各 item について:

Note

Main items は [USBIF-HID-CLASS] の 6.2.2.4 から 6.2.2.6 節に記述されています。Input tag、 Output tag、または Feature tag を持つアイテムは、入力・出力・フィーチャーレポート内のフィールドを定義します。item data field は、Main item が Input tag、Output tag、または Feature tag を持つ場合、データフィールドを記述する複数の真偽値パラメータからなるビットフィールドです。Collection tag を持つアイテムは、現在のコレクション内に新しいコレクションを入れ子に定義するか、現在のコレクションが存在しない場合は新しい top-level collection を定義します。Main item が Collection tag を持つ場合、その item data field には collection type が含まれます。End Collection tag を持つアイテムは、現在のコレクションを閉じます。
- item が Main item の場合:
  1. item が Input tag、Output tag、または Feature tag を持つ場合:
    1. globalState を globalStack の最後の item とします。
    2. reportId を globalState["reportId"] とします。
    3. reportItem を、 HID レポートアイテムを作成した結果（引数: item、localState、 globalState、usages、strings）とします。
    4. For each により、ancestors の各 collection について:
      1. reports を次のようにします:
        
        collection["inputReports"] （item が Input tag を持つ場合）
        
        collection["outputReports"] （item が Output tag を持つ場合）
        
        collection["featureReports"] （item が Feature tag を持つ場合）
      2. reports に、その reportId 属性が reportId に等しい要素が含まれている場合は、report をその要素とします。
        
        それ以外の場合:
        
        report を、 new により作成した HIDReportInfo 辞書とします。
        
        report["reportId"] を reportId に設定します。
        
        report["items"] を、空の sequence （要素は HIDReportItem）に設定します。
        
        Append により report を reports に追加します。
      3. Append により item を report["items"] に追加します。
  2. item が Collection tag を持つ場合:
    1. collection を、 new により作成した HIDCollectionInfo 辞書とします。
    2. usage を、usages の最初の item とします。
    3. もし usages の size が 1 より大きい場合は、 usages の最初の item を削除します。
    4. collection["usagePage"] を globalState["usagePage"] に設定します。
    5. collection["usage"] を usage に設定します。
    6. collection["type"] を、コレクションの種類を表す値に設定します。
    7. collection["children"] を空の sequence（要素は HIDCollectionInfo）に設定します。
    8. collection["inputReports"] を空の sequence（要素は HIDReportInfo）に設定します。
    9. collection["outputReports"] を空の sequence（要素は HIDReportInfo）に設定します。
    10. collection["featureReports"] を空の sequence（要素は HIDReportInfo）に設定します。
    11. もし ancestors が空であれば、append により collection を collections に追加します。
      
      それ以外の場合:
      1. parent を、 ancestors の最後の item とします。
      2. Append により collection を parent["children"] に追加します。
    12. Append により collection を ancestors に追加します。
  3. item が End Collection tag を持つ場合は、 remove により ancestors の最後の item を削除します。
  4. localState を空の ordered map に設定します。
  5. usages を空の sequence（要素は unsigned long）に設定します。
    
    Note
    
    Global items は 6.2.2.7 節に記述されています。 Usage Page tag、 Logical Minimum tag、 Logical Maximum tag、 Physical Minimum tag、 Physical Maximum tag、 Unit Exponent tag、 Unit tag、 Report Size tag、 Report ID tag、および Report Count tag は、グローバルアイテム状態テーブルのそれぞれのフィールドを変更します。Push tag を持つアイテムは、現在のグローバルアイテム状態テーブルのコピーをアイテム状態スタックにプッシュします。Pop tag を持つアイテムは、アイテム状態スタックの先頭の内容でグローバルアイテム状態テーブルを置き換えます。アイテム状態スタックを操作しても、グローバルな Report ID の値は影響を受けません。
  6. item が Global item の場合:
    1. globalState を globalStack の最後の item とします。
    2. value を、 item data field を unsigned long として解釈した値とします。
    3. item が Usage Page tag を持つ場合、 globalState["usagePage"] を value に設定します。
    4. item が Logical Minimum tag を持つ場合、 globalState["logicalMinimum"] を value に設定します。
    5. item が Logical Maximum tag を持つ場合、 globalState["logicalMaximum"] を value に設定します。
    6. item が Physical Minimum tag を持つ場合、 globalState["physicalMinimum"] を value に設定します。
    7. item が Physical Maximum tag を持つ場合、 globalState["physicalMaximum"] を value に設定します。
    8. item が Report Size tag を持つ場合、 globalState["reportSize"] を value に設定します。
    9. item が Report ID tag を持つ場合、 globalState["reportId"] を value に設定します。
    10. item が Report Count tag を持つ場合、 globalState["reportCount"] を value に設定します。
    11. item が Unit tag を持つ場合:
      1. nibbles を、value を低位ビットから 8 個の 4 ビット符号付き 2 の補数整数の sequence として解釈した結果とします。
      2. nibbles[0] が次の場合:
        
        0 のとき、 globalState["unitSystem"] を "none" に設定
        
        1 のとき、 globalState["unitSystem"] を "si-linear" に設定
        
        2 のとき、 globalState["unitSystem"] を "si-rotation" に設定
        
        3 のとき、 globalState["unitSystem"] を "english-linear" に設定
        
        4 のとき、 globalState["unitSystem"] を "english-rotation" に設定
        
        -1 のとき、 globalState["unitSystem"] を "vendor-defined" に設定
        
        それ以外の場合、 globalState["unitSystem"] を "reserved" に設定
      3. globalState["unitFactorLengthExponent"] を nibbles[1] に設定します。
      4. globalState["unitFactorMassExponent"] を nibbles[2] に設定します。
      5. globalState["unitFactorTimeExponent"] を nibbles[3] に設定します。
      6. globalState["unitFactorTemperatureExponent"] を nibbles[4] に設定します。
      7. globalState["unitFactorCurrentExponent"] を nibbles[5] に設定します。
      8. globalState["unitFactorLuminousIntensityExponent"] を nibbles[6] に設定します。
    12. item が Unit Exponent tag を持つ場合、 globalState["unitExponent"] を、 item data field の最下位 4 ビットを符号付き 2 の補数整数として解釈した結果に設定します。
    13. item が Push tag を持つ場合、push により globalState のコピーを globalStack にプッシュします。
    14. item が Pop tag を持つ場合、pop により globalStack からポップします。
  Note
  
  Local items は 6.2.2.8 節に記述されています。 Usage tag、Usage Minimum tag、 Usage Maximum tag、String Index tag、 String Minimum tag、または String Maximum tag を持つアイテムは、ローカルアイテム状態テーブルのそれぞれのフィールドを変更します。ローカルアイテムの状態は各 Main item の後にクリアされます。
- item が Local item の場合:
  1. value を、 item data field を unsigned long として解釈した値とします。
  2. item が Usage tag を持つ場合:
    1. item の bSize field が 1 または 2 の場合:
      1. usageId を、 value の下位 16 ビットを格納した unsigned short とします。
      2. globalState を、globalStack の最後の item とします。
      3. value を、HID usage に設定し、その値は上位ビットに globalState["usagePage"]、下位ビットに usageId を組み合わせたものとします。
    2. Append により value を usages に追加します。
  3. item が Usage Minimum tag を持つ場合、 localState["usageMinimum"] を value に設定します。
  4. item が Usage Maximum tag を持つ場合、 localState["usageMaximum"] を value に設定します。
  5. item が String Index tag を持つ場合、 append により value を stringIndices に追加します。
  6. item が String Minimum tag を持つ場合、 localState["stringMinimum"] を value に設定します。
  7. item が String Maximum tag を持つ場合、 localState["stringMaximum"] を value に設定します。

HID レポートアイテムを作成するには、item、localState、globalState、usages、stringIndices を用いて次の手順を実行します。

reportItem を、 new により作成した HIDReportItem 辞書とします。
value を、item data field を unsigned long として解釈した値とします。
bitfield を、value の各ビット（低位ビットから）を表す boolean 値の list とします。
reportItem["isConstant"] を bitfield[0] に設定します。
reportItem["isArray"] を !bitfield[1] に設定します。
reportItem["isAbsolute"] を !bitfield[2] に設定します。
reportItem["wrap"] を bitfield[3] に設定します。
reportItem["isLinear"] を !bitfield[4] に設定します。
reportItem["hasPreferredState"] を bitfield[5] に設定します。
reportItem["hasNull"] を bitfield[6] に設定します。
reportItem["isVolatile"] を bitfield[7] に設定します。
reportItem["isBufferedBytes"] を bitfield[8] に設定します。
reportItem["usages"] を usages に設定します。
reportItem["reportSize"] を globalState["reportSize"] に設定します。
reportItem["reportCount"] を globalState["reportCount"] に設定します。
reportItem["unitExponent"] を globalState["unitExponent"] に設定します。
reportItem["unitSystem"] を globalState["unitSystem"] に設定します。
reportItem["unitFactorLengthExponent"] を globalState["unitFactorLengthExponent"] に設定します。
reportItem["unitFactorMassExponent"] を globalState["unitFactorMassExponent"] に設定します。
reportItem["unitFactorTimeExponent"] を globalState["unitFactorTimeExponent"] に設定します。
reportItem["unitFactorTemperatureExponent"] を globalState["unitFactorTemperatureExponent"] に設定します。
reportItem["unitFactorCurrentExponent"] を globalState["unitFactorCurrentExponent"] に設定します。
reportItem["unitFactorLuminousIntensityExponent"] を globalState["unitFactorLuminousIntensityExponent"] に設定します。
reportItem["logicalMinimum"] を globalState["logicalMinimum"] に設定します。
reportItem["logicalMaximum"] を globalState["logicalMaximum"] に設定します。
もし localState に "usageMinimum" が含まれている場合、 reportItem["usageMinimum"] を localState["usageMinimum"] に設定します。
もし localState に "usageMaximum" が含まれている場合、 reportItem["usageMaximum"] を localState["usageMaximum"] に設定します。
reportItem["isRange"] を、reportItem["usageMinimum"] が reportItem["usageMaximum"] より小さい場合は true、それ以外は false に設定します。
もし localState に "stringMinimum" と "stringMaximum" が存在する場合:
1. Append により、 the range の localState["stringMinimum"] から localState["stringMaximum"] までの item を stringIndices に追加します。
For each により、stringIndices の各 stringIndex について:
1. string を、インデックス stringIndex の文字列ディスクリプタを読み取った結果とします。
2. Append により string を reportItem["strings"] に追加します。
reportItem を返します。

システムで HID インターフェイスが利用できなくなった場合、次の手順を実行します。

device を、hid.[[devices]] の中で当該インターフェイスを表す HIDDevice とします。
hid を、device の関連グローバルオブジェクトが Window オブジェクトである場合は、その Navigator オブジェクトの hid ゲッターを呼び出した結果とし、そうでない場合は WorkerNavigator オブジェクトの hid ゲッターを呼び出した結果とします。
Remove により device を hid.[[devices]] から削除します。
以前の requestDevice() の呼び出し結果としてユーザーがサイトに device へのアクセスを許可している場合は、queue a global task を関連グローバルオブジェクト上で実行し、HID device task source を用いてイベントを発火し、hid に対して disconnect という名前のイベントを、HIDConnectionEvent を使用して発生させ、その device 属性を device に初期化します。

getDevices() メソッドの手順は次のとおりです:

promise を、新しい Promise とします。
document を null とします。
this の関連グローバルオブジェクトが DedicatedWorkerGlobalScope または window オブジェクトである場合、document を this の関連グローバルオブジェクトの関連付けられた Document に設定します。
this の関連グローバルオブジェクトが ServiceWorkerGlobalScope オブジェクトで、関連する service worker client が window client の場合、document を、関連する service worker client のグローバルオブジェクトの関連付けられた Document に設定します。
もし document が null である、または document が使用が許可されていないポリシー制御機能（名前 "hid"）である場合、reject により promise を "SecurityError" の DOMException で拒否して、 promise を返します。
次の手順を並行して実行します:
1. devices を空の sequence（要素は HIDDevice）として設定します。
2. For each により、device ∈ this.[[devices]] について:
  1. 以前の requestDevice() の結果としてユーザーがサイトに device へのアクセスを許可しており、かつ device.[[state]] が "forgotten" でない場合、 append により device を devices に追加します。
3. Queue a global task により、関連グローバルオブジェクト上で this を用い、HID device task source を使って resolve し、 promise を devices で解決します。
promise を返します。

Note

requestDevice() の許可ダイアログは、接続されたデバイスの一覧を提示し、ユーザーに 1 つを選択させます。

デバイスに複数の HID インターフェイスがある場合、ダイアログは MAY（〜してもよい）としてそれらすべてを代表する 1 つの項目のみを表示することがあります。ユーザーが複数の HID インターフェイスを表す項目を選択した場合、ユーザーエージェントはデバイスが公開するすべての HID インターフェイスへのアクセスを MUST（必ず）付与しなければなりません。

requestDevice() メソッドの手順は次のとおりです:

promise を、新しい Promise とします。
this の関連付けられた Document が、使用が許可されていないポリシー制御機能（名前 "hid"）である場合、reject により promise を "SecurityError" の DOMException で拒否して、 promise を返します。
関連グローバルオブジェクトが this のものであり、それが window でない場合、 reject により promise を "NotSupportedError" の DOMException で拒否して、 promise を返します。
関連グローバルオブジェクト（this のもの）に transient activation がない場合、reject により promise を "SecurityError" の DOMException で拒否して、 promise を返します。
もし options["filters"] が存在する場合、次の手順を for each で filter ∈ options["filters"] について実行します:
1. filter が有効なフィルターでない場合、reject により promise を TypeError で拒否して、promise を返します。
もし options["exclusionFilters"] が存在する場合、次の手順を実行します:
1. options["exclusionFilters"] が空であれば、reject により promise を TypeError で拒否して promise を返します。
2. For each により、exclusionFilter ∈ options["exclusionFilters"] について:
  1. exclusionFilter が有効なフィルターでない場合、 reject により promise を TypeError で拒否して promise を返します。
次の手順を並行して実行します:
1. availableDevices を空の list として初期化します。
2. For each により、device ∈ this.[[devices]] について:
  1. もし device が options["filters"] のいずれかのフィルターに一致し、かつ device が options["exclusionFilters"] のいずれのフィルターにも一致しない場合、 append により device を availableDevices に追加します。
3. availableDevices のデバイス一覧を提示して、サイトに対して HID デバイスへのアクセスを許可するようユーザーに求めます。
  
  Note
  
  ユーザーに提示する前に、ユーザーエージェントはデバイス一覧を変更してもよい場合があります。例えば、複数の HID インターフェイスを持つデバイスは、SHOULD（すべき）として 1 つの項目で表され、その項目を選択すると当該デバイスが公開するすべてのインターフェイスへのアクセスが付与されるべきです。デバイスが単一のインターフェイスとして実装されているか、インターフェイスの集合として実装されているかは実装の詳細であり、ユーザーには認識されない場合があり、デバイスアクセス許可に関して考慮すべき関連事項ではありません。
4. devices を空の sequence（要素は HIDDevice）とします。
5. ユーザーがデバイスを選択しない場合、queue a global task を関連グローバルオブジェクト（this のもの）上で実行し、HID device task source を用いて resolve により promise を devices で解決し、これらの手順を中止します。
6. For each により、device ∈ this.[[devices]] について:
  1. もし device が、選択されたデバイスにより公開される HID インターフェイスを表している場合、 device.[[state]] を "closed" に設定し、append により device を devices に追加します。
7. Queue a global task により、関連グローバルオブジェクト上で device を用い、HID device task source を使って resolve し、 promise を devices で解決します。
promise を返します。

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

filters メンバー: HID デバイスのフィルター。
exclusionFilters メンバー: HID デバイスの除外フィルター。

WebIDLdictionary HIDDeviceFilter {
    unsigned long vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};

vendorId メンバー: 一致させるベンダー ID。
productId メンバー: 一致させるプロダクト ID。vendorId メンバーが存在しない場合、productId は無視されます。
usagePage メンバー: 一致させるトップレベルコレクションの usage page。
usage メンバー: 一致させるトップレベルコレクションの usage ID。usagePage メンバーが存在しない場合、 usage は無視されます。

Note

デバイスフィルターは、requestDevice() により作成されるチューザーダイアログでユーザーに提示されるデバイスの一覧を絞り込むために使用されます。フィルターが提供されない場合、いずれの除外フィルターにも一致しないすべての接続済みデバイスが含まれます。1 つ以上のフィルターが提供された場合、いずれかのフィルターに一致し、かつどの除外フィルターにも一致しないデバイスが含まれます。

すべての HIDDeviceFilter のメンバーは任意です。各メンバーは 1 つの規則を指定します。HIDDeviceFilter に一致するには、すべての規則を満たす必要があります。空の HIDDeviceFilter は任意のデバイスに一致します。

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

Usage 規則は、デバイスのトップレベルコレクションに割り当てられた HID usage によってデバイスを選択するために使用されます。これは、アプリケーションが標準的なデバイスクラスで動作するよう設計されている場合に有用です。デバイスに一致するには、少なくとも 1 つのコレクションがすべての usage 規則に一致しなければなりません。 usagePage 規則を含めると、デバイスに指定された usage page を持つコレクションが含まれている場合にのみ一致します。さらに usage 規則も含めた場合、フィルターは指定された usage page と usage ID を持つデバイスにのみ一致します。 usage は、 usagePage 規則なしで指定された場合は無視されます。

デバイス ID 規則と usage 規則は組み合わせることができます。例えば、特定のベンダーのデバイスに一致させつつ、特定のデバイスクラスを実装するデバイスのみに限定したい場合があります。

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

HIDDeviceFilter の filter が有効なフィルターであるのは、次の手順が true を返す場合です:

filter が空であれば、false を返します。
filter["productId"] が存在し、 filter["vendorId"] が存在しない場合は、 false を返します。
filter["usage"] が存在し、 filter["usagePage"] が存在しない場合は、 false を返します。
true を返します。

HIDDevice の device が、 sequence filters（HIDDeviceFilter）内のいずれかのフィルターに一致するのは、次の手順が true を返す場合です:

filters が空であれば、 true を返します。
For each により、filter ∈ filters について:
1. もし filter が device のデバイス ID に一致し、かつ filter が device のいずれかのコレクションに一致する場合、 true を返します。
false を返します。

HIDDeviceFilter の filter がデバイス ID に一致するのは、次の手順が true を返す場合です:

"vendorId" が filter に含まれる場合:
1. もし filter["vendorId"] が device.vendorId と等しくない場合、 false を返します。
2. もし "productId" が filter に含まれ、 filter["productId"] が device.productId と等しくない場合、 false を返します。
true を返します。

HIDDeviceFilter の filter がいずれかのコレクションに一致するのは、次の手順が true を返す場合です:

For each により、collection ∈ device.collections について:
1. もし filter が collection に対してコレクションに一致するなら、 true を返します。
false を返します。

HIDDeviceFilter の filter がコレクションに一致する collection なのは、次の手順が true を返す場合です:

"usagePage" が filter に含まれる場合:
1. もし filter["usagePage"] が collection.usagePage と等しくない場合、 false を返します。
2. もし "usage" が filter に含まれ、 filter["usage"] が collection.usage と等しくない場合、 false を返します。
true を返します。

WebIDL[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 device task source に作業をキューイングします。

HIDDevice のインスタンスは、次の表に記載の内部スロットとともに作成されます。

内部スロット	初期値	説明（非規範的）
[[state]]	`"closed"`	`HIDDevice` のアクティブ状態を追跡します
[[vendorId]]	0	デバイスの vendor ID
[[productId]]	0	デバイスの product ID
[[productName]]	`""`	デバイスの product name
[[collections]]	空の sequence（要素は `HIDCollectionInfo`）	report descriptor を解析して作成された top-level collections
[[pendingSendReportPromises]]	空の list	保留中の `sendReport()` の `Promise`
[[pendingSendFeatureReportPromises]]	空の list	保留中の `sendFeatureReport()` の `Promise`
[[pendingReceiveFeatureReportPromises]]	空の list	保留中の `receiveFeatureReport()` の `Promise`

oninputreport 属性

oninputreport は、イベントハンドラー IDL 属性であり、 inputreport イベント型に対応します。

opened 属性

HIDDevice がデータ転送の準備ができていることを示すフラグです。

opened ゲッターの手順は次のとおりです:

this.[[state]] が opened であれば、true を返す。
false を返す。

vendorId 属性

vendor ID は、デバイスの製造元を識別するために vendor ID の発行元によって割り当てられる unsigned short 値です。

vendorId 属性は、デバイスの vendor ID です。デバイスに vendor ID がない、または vendor ID にアクセスできない場合、この属性は MUST 0 でなければなりません。

vendorId ゲッターの手順は次のとおりです:

this.[[vendorId]] を返す。

productId 属性

product ID は、製品を識別するためにデバイスの製造元によって割り当てられる unsigned short 値です。

productId 属性は、デバイスの product ID です。デバイスに product ID がない、または product ID にアクセスできない場合、この属性は MUST 0 でなければなりません。

productId ゲッターの手順は次のとおりです:

this.[[productId]] を返す。

productName 属性

製品を識別する文字列です。

USB HID デバイスでは、product name は、デバイスディスクリプタで指定されたインデックス iProduct にある文字列ディスクリプタの値を含む SHOULD（含めるべき）です。Bluetooth HID デバイスでは、 product name はデバイス名特性（Device Name characteristic）の値を含む SHOULD（含めるべき）です。デバイスに product name がない、または product name が空もしくはアクセスできない場合、この属性は空文字列を返す MUST（必ず）があります。

productName 文字列には、デバイスを一意に識別し得るシリアル番号や Bluetooth デバイスアドレスなどの識別子を含める SHOULD NOT（含めるべきではありません）。

productName ゲッターの手順は次のとおりです:

this.[[productName]] を返す。

collections 属性

sequence（要素は HIDCollectionInfo）であり、 report descriptor 内の top-level collections を表します。

collections ゲッターの手順は次のとおりです:

this.[[collections]] を返す。

Note

Top-level collections は、デバイス内で同様の目的に役立つアイテムをグループ化します。アプリケーションは、デバイスを識別するために HID usage が top-level collections にどのように適用されているかを確認します。デバイスが特定の種類の慣例に従っていない場合、アプリケーションはそのデバイスを認識しない可能性があります。標準的な HID デバイスの慣例的な動作の詳細については [USBIF-HID-USAGE] を参照してください。

入力レポートが device から受信されたとき、次の手順を実行します:

入力レポートが blocked report である場合、これらの手順を中止する。
reportId をこのレポートのレポート ID、または HID interface が use report IDs しない場合は 0 とする。
data を、入力レポートを表す byte sequence 上に作成された DataView とする。 HID interface が uses report IDs する場合、その byte sequence にはレポート ID バイトを含めては MUST NOT なりません。
Queue a global task により、 this の relevant global object 上で、 HID device task source を用いてイベントを発火し、 inputreport という名前のイベントを device に対して発生させる。HIDInputReportEvent を使用し、その device 属性を device に、 reportId 属性を reportId に、 data 属性を data に初期化する。

open() メソッドの手順は次のとおりです:

promise を新しい promise とする。
this.[[state]] が "closed" でない場合、 reject により promise を "InvalidStateError" の DOMException で拒否し、 promise を返す。
this.[[state]] を "opening" に設定する。
次の手順を並行して実行する:
1. オペレーティングシステムに対して HID デバイスを開くよう要求する。
2. 何らかの理由で失敗した場合、 queue a global task により this の relevant global object 上で HID device task source を用いて reject により promise を "NetworkError" の DOMException で拒否し、これらの手順を中止する。
3. this.[[state]] を "opened" に設定する。
4. Queue a global task により、 this の relevant global object 上で HID device task source を用いて resolve し、 promise を undefined で解決する。
promise を返す。

close() メソッドの手順は次のとおりです:

promise を新しい promise とする。
this.[[state]] が "forgotten" または "forgetting" の場合、reject により promise を "InvalidStateError" の DOMException で拒否し、 promise を返す。
this.[[state]] を "closing" に設定する。
For each により、 pendingPromise ∈ this.[[pendingSendReportPromises]] について:
1. Reject により pendingPromise を "AbortError" の DOMException で拒否する。
Empty により this.[[pendingSendReportPromises]] を空にする。
For each により、 pendingPromise ∈ this.[[pendingSendFeatureReportPromises]] について:
1. Reject により pendingPromise を "AbortError" の DOMException で拒否する。
Empty により this.[[pendingSendFeatureReportPromises]] を空にする。
For each により、 pendingPromise ∈ this.[[pendingReceiveFeatureReportPromises]] について:
1. Reject により pendingPromise を "AbortError" の DOMException で拒否する。
Empty により this.[[pendingReceiveFeatureReportPromises]] を空にする。
次の手順を並行して実行する:
1. オペレーティングシステムに対して HID デバイスを閉じ、関連するリソースを解放するよう要求する。
2. this.[[state]] を "closed" に設定する。
3. Queue a global task により、 this の relevant global object 上で HID device task source を用いて resolve し、 promise を undefined で解決する。
promise を返す。

Note

ユーザーエージェントは API をまたいで権限を統合することを MAY（してもよい）あります。例えば、 WebHID と WebUSB のデバイスアクセスを統一された低レベルデバイスアクセス権限で追跡するなどです。そのため、このメソッドは将来的に追加の（未特定の）権限も取り消す可能性があります。

forget() メソッドの手順は次のとおりです:

promise を新しい promise とする。
次の手順を並行して実行する:
1. For each により、 device ∈ this.[[devices]] について:
  1. device が HIDDevice とデバイスアクセス権限を共有しない場合、次のデバイスへ進む。
  2. device.[[state]] を "forgetting" に設定する。
  3. For each により、 pendingPromise ∈ device.[[pendingSendReportPromises]] について:
    1. Reject により pendingPromise を "AbortError" の DOMException で拒否する。
  4. Empty により device.[[pendingSendReportPromises]] を空にする。
  5. For each により、 pendingPromise ∈ device.[[pendingSendFeatureReportPromises]] について:
    1. Reject により pendingPromise を "AbortError" の DOMException で拒否する。
  6. Empty により device.[[pendingSendFeatureReportPromises]] を空にする。
  7. For each により、 pendingPromise ∈ device.[[pendingReceiveFeatureReportPromises]] について:
    1. Reject により pendingPromise を "AbortError" の DOMException で拒否する。
  8. Empty により device.[[pendingReceiveFeatureReportPromises]] を空にする。
  9. ユーザーエージェントに、device が公開するすべての HID interfaces へのアクセスを取り消すよう要求する。
  10. device.[[state]] を "forgotten" に設定する。
2. Queue a global task により、 this の relevant global object 上で HID device task source を用いて resolve し、 promise を undefined で解決する。
promise を返す。

Note

sendReport() メソッドは、指定された reportId と data を持つ出力レポートを送信するために使用されます。 HID interface が use report IDs しない場合は、レポート ID の代わりに 0 を渡します。

HID interfaces のうち use report IDs するものでは、レポート ID の値 0 は予約済みであり使用すべきではありません。

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

promise を新しい promise とする。
this.[[state]] が "opened" でない場合、 reject により promise を "InvalidStateError" の DOMException で拒否し、 promise を返す。
reportId が 0 で、 HID interface（ this が表す）が uses report IDs する場合、あるいは reportId が 0 でなく、そのインターフェイスが use report IDs しない場合、 reject により promise を "TypeError" の DOMException で拒否し、 promise を返す。
Append により promise を this.[[pendingSendReportPromises]] に追加する。
次の手順を並行して実行する:
1. このレポートが blocked report の場合、 queue a global task により this の relevant global object 上で HID device task source を用いて reject により promise を "NotAllowedError" の DOMException で拒否し、これらの手順を中止する。
2. オペレーティングシステムに、指定された reportId と data を持つ出力レポートを送信するよう要求する。
3. 何らかの理由で失敗した場合、 queue a global task により this の relevant global object 上で HID device task source を用いて reject により promise を "NetworkError" の DOMException で拒否し、これらの手順を中止する。
4. Queue a global task により、 this の relevant global object 上で HID device task source を用いて resolve し、 promise を undefined で解決する。
promise を返す。

Note

sendFeatureReport() メソッドは、指定された reportId と data を持つフィーチャーレポートを送信するために使用されます。 HID interface が use report IDs しない場合は、レポート ID の代わりに 0 を渡します。

HID interfaces のうち use report IDs するものでは、レポート ID の値 0 は予約済みであり使用すべきではありません。

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

promise を新しい promise とする。
this.[[state]] が "opened" でない場合、 reject により promise を "InvalidStateError" の DOMException で拒否し、 promise を返す。
reportId が 0 で、 HID interface（ this が表す）が uses report IDs する場合、あるいは reportId が 0 でなく、そのインターフェイスが use report IDs しない場合、 reject により promise を "TypeError" の DOMException で拒否し、 promise を返す。
Append により promise を this.[[pendingSendFeatureReportPromises]] に追加する。
次の手順を並行して実行する:
1. このレポートが blocked report の場合、 queue a global task により this の relevant global object 上で HID device task source を用いて reject により promise を "NotAllowedError" の DOMException で拒否し、これらの手順を中止する。
2. オペレーティングシステムに、指定された reportId と data を持つフィーチャーレポートを送信するよう要求する。
3. 何らかの理由で失敗した場合、 queue a global task により this の relevant global object 上で HID device task source を用いて reject により promise を "NetworkError" の DOMException で拒否し、これらの手順を中止する。
4. Queue a global task により、 this の relevant global object 上で HID device task source を用いて resolve し、 promise を undefined で解決する。
promise を返す。

Note

receiveFeatureReport() メソッドは、指定された reportId を持つフィーチャーレポートを要求するために使用されます。 HID interface が use report IDs しない場合は、レポート ID の代わりに 0 を渡します。

HID interfaces のうち use report IDs するものでは、レポート ID の値 0 は予約済みであり使用すべきではありません。

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

promise を新しい promise とする。
this.[[state]] が "opened" でない場合、 reject により promise を "InvalidStateError" の DOMException で拒否し、 promise を返す。
reportId が 0 で、 HID interface（ this が表す）が uses report IDs する場合、あるいは reportId が 0 でなく、そのインターフェイスが use report IDs しない場合、 reject により promise を "TypeError" の DOMException で拒否し、 promise を返す。
Append により promise を this.[[pendingReceiveFeatureReportPromises]] に追加する。
次の手順を並行して実行する:
1. このレポートが blocked report の場合、 queue a global task により this の relevant global object 上で HID device task source を用いて reject により promise を "NotAllowedError" の DOMException で拒否し、これらの手順を中止する。
2. data を、指定された reportId を持つフィーチャーレポートの読み取りをオペレーティングシステムに実行させた結果を表す byte sequence 上に作成された DataView とする。
  
  Note
  
  data には、オペレーティングシステムから受信したレポートデータがそのまま含まれます。デバイスが uses report IDs する場合、先頭バイトがレポート ID である可能性があります。デバイスがレポート ID の代わりに他のデータで応答する場合があるため、このバイトは含まれています。
3. フィーチャーレポートの読み取りが何らかの理由で失敗した場合、 queue a global task により this の relevant global object 上で HID device task source を用いて reject により promise を "NetworkError" の DOMException で拒否し、これらの手順を中止する。
4. Queue a global task により、 this の relevant global object 上で HID device task source を用いて resolve し、 data をもって promise を解決する。
promise を返す。

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

device 属性: 接続または切断されたデバイスを表す HIDDevice インスタンス。

WebIDLdictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};

device メンバー: このイベントに関連付けられたデバイス。

WebIDL[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 属性: 入力レポートを送信した HID インターフェイスを表す HIDDevice インスタンス。
reportId 属性: このレポートの 1 バイトの識別プレフィックス。HID インターフェイスが report ID を使用しない場合は 0。
data 属性: 入力レポートのデータを含む DataView。 HID インターフェイスが report ID を使用する場合は reportId バイトを除外。

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

device メンバー: このイベントに関連付けられたデバイス。
reportId メンバー: 入力レポートの report ID。
data メンバー: 入力レポートのデータ。

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

デバイスがシステムに初めて接続されたとき、システムはそのデバイスが公開する各 HID インターフェイスのレポート記述子を取得しなければならない (MUST)。レポート記述子は各レポートの構成を記述する階層的なデータ構造に展開できるバイト列である。このデータ構造の要素は item と呼ばれる。関係を共有する item のグループは collection と呼ばれる。

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

inputReports、 outputReports、および featureReports 属性には、この collection 内で記述される各レポートについての情報を与える sequence の HIDReportInfo が含まれる。トップレベル collection では、 HIDReportInfo はレポートを構成する全 item の平坦化ビューを表す。平坦化ビューでは、入れ子の collection 内の item とトップレベル collection 内の item が交互に並ぶ。入れ子の collection では、HIDReportInfo は当該 collection とその入れ子 collection に含まれる item のみを含む。

usagePage メンバー

この collection に関連付けられた HID usage の usage page 要素。

HID usages は、アプリケーションが item や collection の目的・意味を識別するために解釈できる定数である。 HID usage は、上位ビットの unsigned short な usage page と、下位ビットの unsigned short な usage ID からなる unsigned long 値である。標準的な HID usage の値は [USBIF-HID-CLASS] および USB Implementers Forum の他の文書で記載されている。

デバイスが公開するトップレベル collection の HID usage は、一般的なデバイス種別の識別に用いられる。

usage メンバー

この collection に関連付けられた HID usage の usage ID 要素。

usage ID は、 usage page 上の個々の HID usage を選択するために使われる。慣例により、usage ID の 0x01〜0x1F はトップレベル collection に予約されている。

type メンバー

collection type を表す値。

Collection type	値
Physical	0x00
Application	0x01
Logical	0x02
Report	0x03
Named Array	0x04
Usage Switch	0x05
Usage Modified	0x06
将来の使用のために予約	0x07 〜 0x7F
ベンダー定義	0x80 〜 0xFF

各 collection type は、グループ化された item 間の異なる種類の関係を記述する。 USBIF-HID-CLASS の 6.2.2.6 節を参照のこと。

children メンバー

この collection 内に入れ子になっている collection を表す sequence の HIDCollectionInfo。

inputReports メンバー

この collection 内で記述される入力レポートを表す sequence の HIDReportInfo。

outputReports メンバー

この collection 内で記述される出力レポートを表す sequence の HIDReportInfo。

featureReports メンバー

この collection 内で記述されるフィーチャーレポートを表す sequence の HIDReportInfo。

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

HIDReportInfo は、レポート記述子内の 1 つの入力・出力・フィーチャーレポートを表す。

reportId メンバー: HID インターフェイスが各レポート転送の先頭に 1 バイトの識別プレフィックスを付与する場合、それは report ID を使用しているという。インターフェイスが report ID を使用しているときは reportId メンバーがそのプレフィックスであり、そうでなければ 0。
items メンバー: このレポートのフィールドを表す sequence の HIDReportItem。

WebIDLdictionary 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 メンバー

データが絶対値（固定の原点に基づく）の場合は true。データが相対値（前回レポートからの変化量を示す）の場合は false。

isArray メンバー

各データフィールドが押下されたボタンやキーに対応するインデックスを含む配列データフィールドをレポートに生成する場合は true。各データフィールドが値を含む可変データフィールドをレポートに生成する場合は false。

isBufferedBytes メンバー

固定サイズのバイトストリームを出力する項目であれば true、数値量であれば false。

isConstant メンバー

項目が変更不能な静的読み取り専用フィールドであれば true。修正可能なデバイスデータを含むレポートフィールドを定義する場合は false。

isLinear メンバー

測定値と報告値の間に線形の関係がある場合は true、何らかの処理が施されている場合は false。

isRange メンバー

項目が usageMinimum と usageMaximum により定義される HID usage 範囲から usage を割り当てる場合は true。項目が sequence の HID usage 値を usages に持つ場合は false。

isVolatile メンバー

ホストの操作なしに値が変化し得る場合は true、値がホストによってのみ変更されるべき場合は false。

フィーチャーおよび出力項目でのみ使用。

hasNull メンバー

項目が意味のあるデータを送信していない null 状態を持つ場合は true、持たない場合は false。 null 状態では、項目は指定された logicalMinimum と logicalMaximum の範囲外の値を報告する。

hasPreferredState メンバー

ユーザーが物理的に操作していないときに戻る好ましい状態を持つ場合は true、そうでない場合は false。

wrap メンバー

値が上下限に達したときにロールオーバーする場合は true、ロールオーバーしない場合は false。

usages メンバー

isRange が true の場合、またはこの項目に関連付けられた HID usage 値がない場合、 usages は未定義でなければならない (MUST)。

isRange が false の場合、 usages はこの項目に関連付けられた HID usage 値の sequence である。

usageMinimum メンバー

isRange が true の場合、 usageMinimum はこの項目に関連付けられた usage 範囲の最小の HID usage 値を含む。

isRange が false の場合、 usageMinimum は未定義でなければならない (MUST)。

usageMaximum メンバー

isRange が true の場合、 usageMaximum はこの項目に関連付けられた usage 範囲の最大の HID usage 値を含む。

isRange が false の場合、 usageMaximum は未定義でなければならない (MUST)。

reportSize メンバー

各レポートデータフィールドのビット数。 reportSize は 0 より大きくなければならない (MUST)。

reportCount メンバー

この項目に対してレポートに含まれるフィールドの数。 reportCount は 0 より大きくなければならない (MUST)。

unitExponent メンバー

単位指数の値。項目に単位定義がない場合は 0。

unitSystem メンバー

単位定義の単位系を指定する HIDUnitSystem 列挙値。項目に単位定義がない場合は "none"。

unitFactorLengthExponent メンバー

単位定義における長さ（センチメートル、ラジアン、インチ、度）の指数。項目に単位定義がない場合は 0。

unitFactorMassExponent メンバー

単位定義における質量（グラムまたは slug）の指数。項目に単位定義がない場合は 0。

unitFactorTimeExponent メンバー

単位定義における時間（秒）の指数。項目に単位定義がない場合は 0。

unitFactorTemperatureExponent メンバー

単位定義における温度（ケルビンまたは華氏度）の指数。項目に単位定義がない場合は 0。

unitFactorCurrentExponent メンバー

単位定義における電流（アンペア）の指数。項目に単位定義がない場合は 0。

unitFactorLuminousIntensityExponent メンバー

単位定義における光度（カンデラ）の指数。項目に単位定義がない場合は 0。

logicalMinimum メンバー

この項目の論理単位での最小範囲。変数項目や配列項目が報告する最小の値。

logicalMaximum メンバー

この項目の論理単位での最大範囲。変数項目や配列項目が報告する最大の値。

physicalMinimum メンバー

この項目の物理的範囲の最小値。これは単位が適用された logicalMinimum を表す。

physicalMaximum メンバー

この項目の物理的範囲の最大値。これは単位が適用された logicalMaximum を表す。

strings メンバー

この項目に関連付けられた文字列。関連付けられた文字列がない場合は空の sequence。

[USBIF-HID-CLASS] の 6.2.2.7 節は 4 つの標準的な単位系を定義している： SI 直線、SI 回転、英米直線、英米回転。各項目はこれら 4 つの単位系のいずれか、ベンダー定義の単位系、または単位系なしを使用する。

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

"none": 単位系なし。項目に単位定義がないことを示す。
"si-linear": SI 直線の単位系は centimeter, gram, second, Kelvin, Ampere, Candela を用いる。
"si-rotation": SI 回転の単位系は radian, gram, second, Kelvin, Ampere, Candela を用いる。
"english-linear": 英米直線の単位系は inch, slug, second, degree Fahrenheit, Ampere, Candela を用いる。
"english-rotation": 英米回転の単位系は degree, slug, second, degree Fahrenheit, Ampere, Candela を用いる。
"vendor-defined": ベンダー定義の単位系。
"reserved": デバイスが単位系に予約値を使用したことを示す。

例 1

このページからアクセス可能なデバイスの一覧を取得する。デフォルトでは、ページにどのデバイスへのアクセス権も付与されていないため、何もアクセスできない。

document.addEventListener('DOMContentLoaded', async () => {
  let devices = await navigator.hid.getDevices();
  devices.forEach(device => {
    console.log(`HID: ${device.productName}`);
  });
});

例 2

HID デバイスの接続および切断のイベントリスナーを登録する。

navigator.hid.addEventListener('connect', ({device}) => {
  console.log(`HID connected: ${device.productName}`);
});

navigator.hid.addEventListener('disconnect', ({device}) => {
  console.log(`HID disconnected: ${device.productName}`);
});

例 3

デバイスへのアクセス許可が付与されるまで、 getDevices() でデバイスにはアクセスできず、接続イベントも生成されない。ページは requestDevice() を用いて許可を要求できる。この例では、ベンダー ID が 0xABCD のデバイスへのアクセスを要求する。そのデバイスは usage page Consumer (0x000C) と usage ID Consumer Control (0x0001) を持つ collection も必要である。プロダクト 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}`);
  }
});

例 4

入力レポートイベント用のイベントリスナーを登録する。

device.oninputreport = ({device, reportId, data}) => {
  console.log(`Input report ${reportId} from ${device.productName}:`,
              new Uint8Array(data.buffer));
};

if (!device.opened)
  await device.open();

例 5

出力レポートを送信する。

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.")
}

例 6

フィーチャーレポートの読み取りと書き込み。

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.")
}

本仕様は、ウェブサイトがアクセス可能な HID デバイスの集合を制限するために、 https://github.com/WICG/webhid リポジトリ内のブロックリストファイルに依存する。

URL url にあるブロックリストを解析した結果は、 sequence の辞書オブジェクトであり、 url を取得して、その内容を JSON として解析することで生成される。

HID ブロックリストは、ブロックリストの解析を https://github.com/WICG/webhid/blob/main/blocklist.txt で行った結果である。

次の手順が true を返す場合、レポートはブロックされたレポートである：

各 rule ∈ HID ブロックリストについて:
1. レポートがブロックリストの規則 rule によりブロックされる場合、 true を返す。
false を返す。

次の手順が true を返す場合、レポートは規則 rule によりブロックされる：

reportId を、そのレポートの report ID とし、 HID インターフェイスが report ID を使用しない場合は 0 とする。
reportType を、レポートが入力レポートなら "input"、出力レポートなら "output"、フィーチャーレポートなら "feature" とする。
collection を、レポートを含むトップレベル collection とする。
rule が "vendor" を含み、かつ rule["vendor"] が device.vendorId と一致しない場合は false を返す。
rule が "product" を含み、かつ rule["product"] が device.productId と一致しない場合は false を返す。
rule が "reportId" を含み、かつ rule["reportId"] が reportId と一致しない場合は false を返す。
rule が "reportType" を含み、かつ rule["reportType"] が reportType と一致しない場合は false を返す。
rule が "usagePage" を含み、かつ rule["usagePage"] が collection["usagePage"] と一致しない場合は false を返す。
rule が "usage" を含み、かつ rule.["usage"] が collection["usage"] と一致しない場合は false を返す。
true を返す。

本仕様は、hid 属性が Navigator オブジェクト上で公開されるかどうかを制御する機能を定義する。

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

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

非規範と明記されたセクションに加え、この仕様のすべての作成ガイドライン、図、例、注記は非規範である。これ以外のすべては規範である。

本文書における MAY, MUST, MUST NOT, SHOULD, SHOULD NOT というキーワードは、 BCP 14 [RFC2119] および [RFC8174] に従って解釈される。ただし、ここに示すようにすべて大文字で現れる場合に限る。

[dom]: DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[html]: HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]: Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[permissions-policy]: Permissions Policy. Ian Clelland. W3C. 24 July 2024. W3C Working Draft. URL: https://www.w3.org/TR/permissions-policy-1/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[service-workers]: Service Workers. Jake Archibald; Marijn Kruisselbrink. W3C. 12 July 2022. W3C Candidate Recommendation. URL: https://www.w3.org/TR/service-workers/
[USBIF-HID-CLASS]: Device Class Definition for Human Interface Devices (HID) version 1.11. Mike Bergman et al. USB Implementers Forum. May 27, 2001. Specification. URL: https://www.usb.org/document-library/device-class-definition-hid-111
[WEBIDL]: Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

[browserext]: Browser Extensions. Mike Pietraszak. W3C. October 2016. Draft Community Group Report. URL: https://browserext.github.io/browserext/
[GAMEPAD]: Gamepad. Steve Agoston; Matthew Reynolds. W3C. 9 August 2024. W3C Working Draft. URL: https://www.w3.org/TR/gamepad/
[pointerevents]: Pointer Events. Jacob Rossi; Matt Brubeck. W3C. 4 April 2019. W3C Recommendation. URL: https://www.w3.org/TR/pointerevents/
[uievents]: UI Events. Gary Kacmarcik; Travis Leithead. W3C. 7 September 2024. W3C Working Draft. URL: https://www.w3.org/TR/uievents/
[USBIF-HID-USAGE]: HID Usage Tables for Universal Serial Bus (USB) version 1.22. David Abzarian et al. USB Implementers Forum. April 6, 2021. Specification. URL: https://www.usb.org/document-library/hid-usage-tables-122

WebHID API

概要

この文書のステータス

1. 序章

2. 動機付けとなる応用例

2.1 ニッチデバイス

2.2 プロトタイピング、ホビイスト、教育用デバイス

3. セキュリティとプライバシーの考慮事項

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

3.2 デバイスへの攻撃

3.3 ホストへの攻撃

3.4 緩和策

4. Navigator インターフェイスへの拡張

4.1 hid 属性

5. WorkerNavigator インターフェイスへの拡張

5.1 hid 属性

6. HID インターフェイス

6.1 getDevices() メソッド

6.2 requestDevice() メソッド

6.2.1 HIDDeviceRequestOptions 辞書

6.2.2 HIDDeviceFilter 辞書

7. HIDDevice インターフェイス

7.1 open() メソッド

7.2 close() メソッド

7.3 forget() メソッド

7.4 sendReport() メソッド

7.5 sendFeatureReport() メソッド

7.6 receiveFeatureReport() メソッド

8. HIDConnectionEvent インターフェイス

8.1 HIDConnectionEventInit 辞書

9. HIDInputReportEvent インターフェイス

9.1 HIDInputReportEventInit 辞書

10. HIDCollectionInfo 辞書

11. HIDReportInfo 辞書

12. HIDReportItem 辞書

13. HIDUnitSystem 列挙

14. 使用例

15. HID ブロックリスト

16. 連携

16.1 Permissions Policy

17. 適合性

A. 謝辞

B. 参考文献

B.1 規範参照

B.2 参考情報

4. `Navigator` インターフェイスへの拡張

4.1 `hid` 属性

5. `WorkerNavigator` インターフェイスへの拡張

5.1 `hid` 属性

6. `HID` インターフェイス

6.1 `getDevices()` メソッド

6.2 `requestDevice()` メソッド

6.2.1 `HIDDeviceRequestOptions` 辞書

6.2.2 `HIDDeviceFilter` 辞書

7. `HIDDevice` インターフェイス

7.1 `open()` メソッド

7.2 `close()` メソッド

7.3 `forget()` メソッド

7.4 `sendReport()` メソッド

7.5 `sendFeatureReport()` メソッド

7.6 `receiveFeatureReport()` メソッド

8. `HIDConnectionEvent` インターフェイス

8.1 `HIDConnectionEventInit` 辞書

9. `HIDInputReportEvent` インターフェイス

9.1 `HIDInputReportEventInit` 辞書

10. `HIDCollectionInfo` 辞書

11. `HIDReportInfo` 辞書

12. `HIDReportItem` 辞書

13. `HIDUnitSystem` 列挙