USB デバイスとの対話、開始から終了まで (UWP アプリ)

[アーティクル]
04/12/2024

この記事では、USB デバイスと通信する UWP アプリを作成するエンドツーエンドのチュートリアルを提供します。

Windows ランタイム API を使用して、ユーザーが周辺機器の USB デバイスにアクセスできるようにする UWP アプリを作成します。そのようなアプリは、ユーザーが指定した条件に基づいてデバイスに接続したり、デバイスに関する情報を取得したり、デバイスにデータを送信したり、逆にデバイスからデータストリームを取得したり、デバイスをポーリングして割り込みデータを取得したりできます。

ここでは、UWP アプリでこれらのタスクを実装する方法と、Windows.Devices.Usb に含まれるクラスの使用方法を示す例へのリンクについて説明します。アプリマニフェストで必要なデバイス機能と、デバイスが接続したときにアプリを起動する方法について説明します。さらに、バッテリ寿命を節約するためにアプリが一時停止されているときでも、バックグラウンドでデータ転送タスクを実行する方法について説明します。

チュートリアル—USB デバイス用の UWP アプリの作成

この記事の手順に従うか、「カスタム USB デバイスアクセスサンプル」に直接スキップします。このコンパニオンサンプルでは、ここでのすべての手順を実装していますが、動きを維持するため、コードの手順については説明しません。特定の手順には、コードをすばやく見つけるのに役立つ「サンプルで確認する」セクションがあります。サンプルのソースファイルの構造はシンプルでフラットなため、複数のソースファイルをドリルダウンしなくても簡単にコードを見つけることができます。ただし、独自のプロジェクトを別の方法で分割して整理することもできます。

Microsoft WinUSB ドライバーのインストール

マイクロソフトによって提供される WinUSB ドライバーをデバイスのファンクションドライバーとしてインストールします。

クイックスタート:WinUSB (Winusb.sys) のインストール

Winusb.sys は、次の方法でインストールできます。

デバイスを接続すると、デバイスが WinUSB デバイスであるため、Windows により Winusb.sys が自動的に読み込まれることに気付く場合があります。
デバイスマネージャーでシステム提供のデバイスクラスを指定し、ドライバーをインストールします。
カスタム INF を使用してドライバーをインストールします。次の 2 つの方法のいずれかで INF を取得できます。
- ハードウェアベンダーから INF を取得します。
- マイクロソフトにより提供された Winusb.inf ファイルを参照するカスタム INF を記述します。詳細については、「WinUSB (Winusb.sys) のインストール」を参照してください。

デバイスに関する情報の取得

デバイスに関するデバイスインターフェイス GUID、ハードウェア ID、およびデバイスクラス情報を取得します。

その情報は、デバイスの製造元から入手できます。

ベンダーと製品の識別子

デバイスマネージャーで、デバイスのプロパティを表示します。 [詳細] タブで、[ハードウェア ID] プロパティの値を表示します。この値は、これら 2 つの識別子の組み合わせです。たとえば、SuperMUTT デバイスの場合、 ハードウェア ID は「USB\VID_045E&PID_F001」、ベンダー ID は「0x045E」で、製品 ID は「0xF001」です。
デバイスクラス、サブクラス、プロトコルコード
デバイスインターフェイス GUID

または、レジストリの情報を表示することもできます。詳細については、「USB デバイスのレジストリエントリ」を参照してください。

USB API セットでデバイスクラス、サブクラス、プロトコルが許可されているかどうかを確認する

デバイスのデバイスクラス、サブクラス、プロトコルコードが次の一覧にある場合、UWP アプリを記述できます。

name:cdcControl, classId:02 * *
name:physical, classId:05 * *
name:personalHealthcare, classId:0f 00 00
name:activeSync, classId:ef 01 01
name:palmSync, classId:ef 01 02
name:deviceFirmwareUpdate, classId:fe 01 01
name:irda, classId:fe 02 00
name:measurement, classId:fe 03 *
name:vendorSpecific, classId:ff * *

基本的な Visual Studio プロジェクトの作成

このチュートリアルで拡張できる基本的な Visual Studio プロジェクトを作成します。

詳細については、「UWP アプリの概要」を参照してください。

アプリマニフェストへの USB デバイス機能の追加

アプリマニフェストに USB デバイス機能を追加する方法について説明します。

クイックスタート:アプリマニフェストに USB デバイス機能を追加する方法

テキストエディターで Package.appxmanifest ファイルを開き、この例に示すように Name 属性が "usb" に設定された DeviceCapability 要素を追加します。

Note

Visual Studio で USB デバイスの機能を変更することはできません。 ソリューションエクスプローラーで Package.appxmanifestファイルを右クリックし、[プログラムから開く] を選択し、[XML (テキスト) エディター] を選択する必要があります。ファイルはプレーン XML で開きます。

<Capabilities>
  <!--When the device's classId is FF * *, there is a predefined name for the class.
      You can use the name instead of the class id.
      There are also other predefined names that correspond to a classId.-->
  <m2:DeviceCapability Name="usb">
    <!--SuperMutt Device-->
    <m2:Device Id="vidpid:045E 0611">
      <!--<wb:Function Type="classId:ff * *"/>-->
      <m2:Function Type="name:vendorSpecific"/>
    </m2:Device>
  </m2:DeviceCapability>
</Capabilities>

サンプルで確認する: USB デバイスの機能は Package.appxmanifest ファイルにあります。

通信用にデバイスを開く

アプリを拡張して、通信用にデバイスを開きます。

クイックスタート:USB デバイスに接続する方法 (UWPアプリ)

列挙されたデバイスコレクション内のデバイスを検索するための検索条件を含む高度なクエリ構文 (AQS) 文字列を作成し、デバイスを検索します。
次の 2 つの方法のいずれかでデバイスを開きます。
- AQS を FindAllAsync に渡し、デバイスの DeviceInformation オブジェクトを取得します。
  
  詳しくは、「クイックスタート: よく使用されるデバイスの列挙」をご覧ください。
- DeviceWatcher オブジェクトを作成することにより、デバイスがシステムに追加またはシステムから削除されるタイミングを検出します。
  1. AQS を CreateWatcher に渡し、DeviceWatcher オブジェクトを取得します。
  2. DeviceWatcher オブジェクトにイベントハンドラーを登録します。
  3. Added イベントハンドラーで、デバイスの DeviceInformation オブジェクトを取得します。
  4. DeviceWatcher オブジェクトを開始および停止します。
  詳細については、「デバイスが追加、削除、または変更された場合に通知を受け取る方法」を参照してください。
DeviceInformation.Id プロパティからデバイスインスタンスを取得します。
デバイスインスタンス文字列を渡して FromIdAsync を呼び出し、UsbDevice オブジェクトを取得します。

サンプルで確認する: Scenario1_DeviceConnect という名前のファイルを参照してください。

USB デバイスのレイアウトの調査

USB デバイスのレイアウトを調べます。

デバイスの構成とデータ転送の実行に関する基本的な USB の概念を確認します: すべての USB 開発者向けの概念。

デバイス構成記述子、サポートされている各代替設定のインターフェイス記述子、およびそのエンドポイント記述子を表示します。 USBView を使用して、すべての USB コントローラーと接続されている USB デバイスを参照し、デバイスの構成を調べることができます。

UI での USB 記述子の取得および表示

UI で USB 記述子を取得して表示するようアプリを拡張します。

クイックスタート:USB 記述子を取得する方法 (UWP アプリ)

UsbDevice.DeviceDescriptor 値を取得することにより、デバイス記述子を取得します。
UsbConfiguration.ConfigurationDescriptor 値を取得することにより、構成記述子を取得します。
- UsbConfiguration.Descriptors プロパティを取得することにより、完全な構成記述子セットを取得します。
UsbConfiguration.UsbInterfaces プロパティを取得して、構成内のインターフェイスの配列を取得します。
UsbInterface.InterfaceSettings を取得して、代替設定の配列を取得します。
アクティブな代替設定内で、パイプを列挙し、関連付けられたエンドポイントを取得します。

これらのオブジェクトは、エンドポイント記述子を表します。
- UsbBulkInEndpointDescriptor
- UsbBulkOutEndpointDescriptor
- UsbInterruptInEndpointDescriptor
- UsbInterruptOutEndpointDescriptor

サンプルで確認する:Scenario5_UsbDescriptors という名前のファイルを参照してください。

ベンダーによって定義された USB コントロール転送の送信

ベンダーによって定義された USB コントロール転送を送信するようアプリを拡張します。

クイックスタート:USB コントロール転送要求を送信する方法 (UWP アプリ)

デバイスのハードウェア仕様からベンダーコマンドを取得します。
UsbSetupPacket オブジェクトを作成し、さまざまなプロパティを設定してセットアップパケットを設定します。
転送の方向に応じて、次のメソッドによってコントロール転送を送信する非同期操作を開始します。
- SendControlInTransferAsync
- SendControlOutTransferAsync

サンプルで確認する: Scenario2_ControlTransfer という名前のファイルを参照してください。

一括データの読み取りまたは書き込み

アプリを拡張し、一括データの読み取りまたは書き込みを行います。

クイックスタート:USB 一括転送要求を送信する方法 (UWP アプリ)

一括パイプオブジェクト (UsbBulkOutPipe または UsbBulkInPipe) を取得します。
ポリシーパラメーターを設定するよう一括パイプを構成します。
DataReader オブジェクトまたは DataWriter オブジェクトを使用して、データストリームを設定します。
DataReader.LoadAsync または DataWriter.StoreAsync を呼び出して、非同期転送操作を開始します。
転送操作の結果を取得します。

サンプルで確認する: Scenario4_BulkPipes という名前のファイルを参照してください。

ハードウェア割り込みデータの取得

ハードウェア割り込みデータを取得するようアプリを拡張します。

クイックスタート:USB 割り込み転送要求を送信する方法 (UWP アプリ)

割り込みパイプオブジェクト (UsbInterruptInPipe または UsbInterruptOutPipe) を取得します。
DataReceived イベントの割り込みハンドラーを実装します。
イベントハンドラーを登録して、データの受信を開始します。
イベントハンドラーの登録を解除して、データの受信を停止します。

サンプルで確認する: Scenario3_InterruptPipes という名前のファイルを参照してください。

現在アクティブではないインターフェイス設定の選択

現在アクティブではないインターフェイス設定を選択するようアプリを拡張します。

クイックスタート:USB インターフェイス設定を選択する方法 (UWP アプリ)

デバイスを通信用に開くと、既定のインターフェイスとその最初の設定が選択されます。この設定を変更する場合、次の手順を実行します。

UsbInterfaceSetting.Selected 値を使用することにより、USB インターフェイスのアクティブな設定を取得します。
UsbInterfaceSetting.SelectSettingAsync を呼び出して非同期操作を開始して、USB インターフェイス設定を設定します。

デバイスを閉じる

アプリを拡張してデバイスを閉じます。

クイックスタート:USB デバイスに接続する方法 (UWPアプリ)

UsbDevice オブジェクトの使用が完了したら、デバイスを閉じます。

C++ アプリでは、delete キーワードを使用して参照を解放する必要があります。 C#/VB アプリでは、UsbDevice.Dispose メソッドを呼び出す必要があります。 JavaScript アプリは UsbDevice.Close を呼び出す必要があります。

サンプルで確認する: Scenario1_DeviceConnect という名前のファイルを参照してください。

デバイスメタデータパッケージの作成

アプリのデバイスメタデータパッケージを作成します。

ツール:デバイスメタデータ作成ウィザード

Windows ドライバーキット (WDK) がインストールされている場合、ドライバー>デバイスメタデータ>作成を開きます。
スタンドアロン SDK がインストールされている場合、ツールは <install_path>\bin\x86\DeviceMetadataWizardexe にあります。

ウィザードの手順に従って、アプリをデバイスに関連付けます。デバイスに関するこの情報を入力します。

[デバイス情報] ページで、[モデル名]、[製造元]、[説明] を入力します。
ハードウェア情報ページで、デバイスのハードウェア ID を入力します。

アプリをデバイスの特権アプリとして宣言するには、以下の手順に従います。

アプリ情報ページの [特権アプリケーション] グループで、[パッケージ名]、[発行元名]、[UWP アプリ ID] を入力します。

Note

[カスタムドライバーにアクセスする] オプションはオンにしないでください。
[完了] タブを開きます。[パッケージをシステムのローカルメタデータストアにコピーする] チェックボックスをオンにします。
デバイスを接続し、コントロールパネルで [デバイスとプリンターの表示] を開き、デバイスのアイコンが正しいことを確認します。

サンプルで確認する: DeviceMetadata フォルダーを参照してください。

自動再生のアクティブ化の実装

自動再生のアクティブ化を実装してアプリを拡張し、デバイスがシステムに接続されたときにアプリを起動します。

クイックスタート: 自動再生デバイスのアプリを登録する

自動再生機能を追加して、デバイスがシステムに接続されたときにアプリが起動するようにすることができます。すべての UWP アプリに対して自動再生を有効にできます (特権または他の権限)。

デバイスメタデータパッケージで、デバイスが自動再生通知に応答する方法を指定する必要があります。 [Windows 情報] タブで、[UWP デバイスアプリ] オプションを選択し、次のようにアプリ情報を入力します。
アプリマニフェストで、次に示すように、自動再生デバイス宣言と起動情報を追加します。
App クラスの OnActivated メソッドで、デバイスがアプリをアクティブ化したかどうかをチェックします。その場合、メソッドは、DeviceInformation.Id プロパティ値を含む DeviceEventArgs パラメーター値を受け取ります。これは、「通信のためにデバイスを開く」で説明されているのと同じ値です。

サンプルで確認する: 自動再生という名前のファイルを参照してください。 JavaScript については、default.js を参照してください。

バックグラウンドタスクの実装

アプリを拡張し、デバイスへの長時間の転送を実行できるバックグラウンドタスク (アプリが中断されることなくファームウェアを更新するなど) を実装します。

バックグラウンドタスクを実装するには、2 つのクラスが必要です。

バックグラウンドタスククラスは IBackgroundTask インターフェイスを実装し、周辺機器を同期または更新するために作成する実際のコードを含みます。バックグラウンドタスククラスは、バックグラウンドタスクがトリガーされたときに、アプリのアプリケーションマニフェストで指定されたエントリポイントから実行されます。

Note

Windows 8.1 によって提供されるデバイスのバックグラウンドタスクインフラストラクチャ。 Windows バックグラウンドタスクの詳細については、「バックグラウンドタスクによるアプリのサポート」をご覧ください。

バックグラウンドタスククラス

Windows バックグラウンドタスクインフラストラクチャで必要な IBackgroundTask インターフェイスを実装します。
Run メソッドでそのクラスに渡される DeviceUseDetails インスタンスを取得し、このインスタンスを使用して Microsoft Store アプリに進行状況を報告し、キャンセルイベントに登録します。
Run メソッドは、バックグラウンドデバイス同期コードを実装するプライベートの OpenDevice メソッドと WriteToDeviceAsync メソッドも呼び出します。

UWP アプリは、DeviceUseTrigger バックグラウンドタスクを登録してトリガーします。アプリは、バックグラウンドタスクの進行状況を登録、トリガー、処理します。

Note

次のコード例は、対応するオブジェクトを使用して DeviceServicingTrigger バックグラウンドタスクに適用できます。 2 つのトリガーオブジェクトとそれに対応する API の唯一の違いは、Windows によって行われるポリシーチェックです。

DeviceUseTrigger オブジェクトと BackgroundTaskRegistration オブジェクトを作成します。
このサンプルアプリケーションで以前登録されたバックグラウンドタスクがあるかどうかを確認し、タスクの Unregister メソッドを呼び出してそれらをキャンセルします。
デバイスと同期するバックグラウンドタスクを登録します。 SetupBackgroundTask メソッドは、次の手順で SyncWithDeviceAsync メソッドから呼び出されます。
1. DeviceUseTrigger を初期化し、後で使用するために保存します。
2. BackgroundTaskBuilder オブジェクトを作成し、その Name、TaskEntryPoint、SetTrigger の各プロパティとメソッドを使用して、アプリの DeviceUseTrigger オブジェクトとバックグラウンドタスク名を登録します。 BackgroundTaskBuilder オブジェクトの TaskEntryPoint プロパティは、バックグラウンドタスクがトリガーされたときに実行されるバックグラウンドタスククラスの完全な名前に設定されます。
3. バックグラウンドタスクからの完了イベントと進行状況イベントを登録し、Microsoft Store アプリが完了と進行状況の更新をユーザーに提供できるようにします。
プライベート SyncWithDeviceAsync メソッドは、デバイスと同期するバックグラウンドタスクを登録して、バックグラウンド同期を開始します。
1. 前の手順から SetupBackgroundTask メソッドを呼び出し、デバイスと同期するバックグラウンドタスクを登録します。
2. バックグラウンドタスクを開始するプライベート StartSyncBackgroundTaskAsync メソッドを呼び出します。
3. デバイスへのアプリのハンドルを閉じて、バックグラウンドタスクが開始時にデバイスを開くことができるようにします。
  
  Note
  
  バックグラウンドタスクは更新を実行するためにデバイスを開く必要があるため、Microsoft Store アプリは RequestAsync を呼び出す前にデバイスへの接続を閉じる必要があります。
4. バックグラウンドタスクのトリガーを開始する DeviceUseTrigger オブジェクトの RequestAsync メソッドを呼び出し、バックグラウンドタスクが正常に開始されたかどうかを判断するために使用した RequestAsync から DeviceTriggerResults オブジェクトを返します。
  
  Note
  
  Windows は、必要なタスク開始ポリシー確認がすべて完了していることを確認します。すべてのポリシー確認が完了すると、更新操作が Microsoft Store アプリの外部でバックグラウンドタスクとして実行され、操作の進行中にアプリを安全に中断できるようになります。 Windows はランタイム要件も適用し、それらの要件が満たされなくなった場合はバックグラウンドタスクを取り消します。
5. StartSyncBackgroundTaskAsync から返された DeviceTriggerResults オブジェクトを使用して、バックグラウンドタスクが正常に開始されたかどうかを判断します。 switch ステートメントは、DeviceTriggerResults からの結果を検査するために使用されます。
デバイスのバックグラウンドタスクからの進行状況をアプリ UI に反映して更新するプライベート OnSyncWithDeviceProgress イベントハンドラーを実装します。
バックグラウンドタスクが完了したときに、バックグラウンドタスクからフォアグラウンドアプリへの移行を処理するプライベート OnSyncWithDeviceCompleted イベントハンドラーを実装します。
1. BackgroundTaskCompletedEventArgs オブジェクトの CheckResults メソッドを使用して、バックグラウンドタスクによって例外がスローされたかどうかを判断します。
2. アプリは、バックグラウンドタスクが完了すると、フォアグラウンドアプリで使用できるようにデバイスを再度開き、UI を更新してユーザーに通知します。
UI からプライベートボタンクリックイベントハンドラーを実装して、バックグラウンドタスクを開始および取り消します。
1. プライベート Sync_Click イベントハンドラーは、前の手順で説明した SyncWithDeviceAsync メソッドを呼び出します。
2. プライベート CancelSync_Click イベントハンドラーは、プライベート CancelSyncWithDevice メソッドを呼び出してバックグラウンドタスクを取り消します。
プライベート CancelSyncWithDevice メソッドは、BackgroundTaskRegistration オブジェクトで Unregister メソッドを使用してデバイスを再度開くことができるように、アクティブなデバイスの同期を登録解除して取り消します。

サンプルで確認する: Scenario7_Sync ファイルという名前のファイルを参照してください。バックグラウンドクラスは、IoSyncBackgroundTask で実装されます。

Windows アプリ認定キットの実行

Windows アプリ認定キットを実行します。

Windows アプリ認定キットの使用

推奨要件。 Windows アプリ認定キットを実行すると、アプリが Microsoft Store の要件を満たしていることを確認できます。アプリに主要な機能を追加するたびに実行する必要があります。

UWP アプリ UI、開始から終了まで (XAML)

UWP アプリ UI の設計についての詳細をご覧ください。

C# を使用した UWP アプリのロードマップと、C++ を使用した UWP アプリの Visual Basic とロードマップ

C++、C#、または Visual Basic を一般的に使用して UWP アプリを作成する方法について説明します。

非同期プログラミング (UWP アプリ)

アプリが長時間かかる可能性のある作業を行うとき、アプリの応答性を維持する方法について説明します。

USB デバイスとの対話、開始から終了まで (UWP アプリ)

チュートリアル—USB デバイス用の UWP アプリの作成

Microsoft WinUSB ドライバーのインストール

デバイスに関する情報の取得

USB API セットでデバイスクラス、サブクラス、プロトコルが許可されているかどうかを確認する

基本的な Visual Studio プロジェクトの作成

アプリマニフェストへの USB デバイス機能の追加

通信用にデバイスを開く

USB デバイスのレイアウトの調査

UI での USB 記述子の取得および表示

ベンダーによって定義された USB コントロール転送の送信

一括データの読み取りまたは書き込み

ハードウェア割り込みデータの取得

現在アクティブではないインターフェイス設定の選択

デバイスを閉じる

デバイスメタデータパッケージの作成

自動再生のアクティブ化の実装

バックグラウンドタスクの実装

バックグラウンドタスククラス

Windows アプリ認定キットの実行

重要な API

フィードバック

フィードバック

その他のリソース

USB デバイスとの対話、開始から終了まで (UWP アプリ)

チュートリアル—USB デバイス用の UWP アプリの作成

Microsoft WinUSB ドライバーのインストール

デバイスに関する情報の取得

USB API セットでデバイス クラス、サブクラス、プロトコルが許可されているかどうかを確認する

基本的な Visual Studio プロジェクトの作成

アプリ マニフェストへの USB デバイス機能の追加

通信用にデバイスを開く

USB デバイスのレイアウトの調査

UI での USB 記述子の取得および表示

ベンダーによって定義された USB コントロール転送の送信

一括データの読み取りまたは書き込み

ハードウェア割り込みデータの取得

現在アクティブではないインターフェイス設定の選択

デバイスを閉じる

デバイス メタデータ パッケージの作成

自動再生のアクティブ化の実装

バックグラウンド タスクの実装

バックグラウンド タスク クラス

Windows アプリ認定キットの実行

関連するサンプル

重要な API

フィードバック

フィードバック

その他のリソース

USB API セットでデバイスクラス、サブクラス、プロトコルが許可されているかどうかを確認する

アプリマニフェストへの USB デバイス機能の追加

デバイスメタデータパッケージの作成

バックグラウンドタスクの実装

バックグラウンドタスククラス