WdfUsbTargetDeviceRetrieveConfigDescriptor 関数 (wdfusb.h)
[KMDF と UMDF に適用]
WdfUsbTargetDeviceRetrieveConfigDescriptor メソッドは、指定されたフレームワーク USB デバイス オブジェクトに関連付けられている USB デバイスの USB 構成記述子を取得します。
構文
NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
[in] WDFUSBDEVICE UsbDevice,
[out] PVOID ConfigDescriptor,
[in, out] PUSHORT ConfigDescriptorLength
);
パラメーター
[in] UsbDevice
WdfUsbTargetDeviceCreateWithParametersへの以前の呼び出しから取得された USB デバイス オブジェクトへのハンドル。
[out] ConfigDescriptor
USB_CONFIGURATION_DESCRIPTOR 構造体を受け取り、その後に 1 つ以上の USB_INTERFACE_DESCRIPTOR および USB_ENDPOINT_DESCRIPTOR 構造体を受け取る呼び出し元によって割り当てられたバッファーへのポインター。 このパラメーターは省略可能であり、NULL できます。この場合、WdfUsbTargetDeviceRetrieveConfigDescriptor は必要なバッファー長 返します。 詳細については、次の「解説」セクションを参照してください。
[in, out] ConfigDescriptorLength
ConfigDescriptor が指すバッファーの長さを提供 する場所へのポインター。 ConfigDescriptor に指定されたポインターが NULL 場合、WdfUsbTargetDeviceRetrieveConfigDescriptor は、ConfigDescriptorLengthが指す位置にある必要なバッファー長を返します。
戻り値
WdfUsbTargetDeviceRetrieveConfigDescriptor 、操作が成功した場合にSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。
| リターン コード | 形容 |
|---|---|
|
指定されたターゲットに対して構成記述子を使用できませんでした。 |
|
無効なパラメーターが検出されました。 |
|
指定されたバッファー サイズがデータに対して小さすぎたか、ConfigDescriptor パラメーターに NULL 呼び出し元が指定しました。 |
このメソッドは、他のNTSTATUS 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
備考
WdfUsbTargetDeviceRetrieveConfigDescriptor メソッドは、指定されたすべての USB デバイスの構成情報 (つまり、構成記述子に加えて、存在する可能性がある任意のインターフェイスまたはエンドポイント記述子) を取得します。 この情報の形式については、USB 仕様を参照してください。
WdfUsbTargetDeviceSelectConfig を使用して、記述子リストにリストされている最初の USB 構成のみを選択できますが、この単一の構成内で複数のインターフェイスを選択できます。
ドライバーは、次のように WdfUsbTargetDeviceRetrieveConfigDescriptor 2 回呼び出す必要があります。
- ConfigDescriptor ポインターを NULLに設定して、WdfUsbTargetDeviceRetrieveConfigDescriptor が ConfigDescriptorLength が指すアドレスに必要なバッファー サイズ 返すようにします。
- 構成情報を保持するバッファー領域を割り当てます。 たとえば、ドライバーは ExAllocatePoolWithTag 呼び出してバッファーを割り当てたり、WdfMemoryCreate 呼び出してフレームワーク メモリ オブジェクトを作成したりする場合があります。
- WdfUsbTargetDeviceRetrieveConfigDescriptor 再度 呼び出し、新しいバッファーへのポインターとバッファーのサイズを渡します。
WdfUsbTargetDeviceRetrieveConfigDescriptor メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲットを参照してください。
例
次のコード例では、WdfUsbTargetDeviceRetrieveConfigDescriptor を呼び出して必要なバッファー サイズを取得し、WdfMemoryCreate 呼び出してメモリ オブジェクトとバッファーを作成した後、WdfUsbTargetDeviceRetrieveConfigDescriptor を呼び出してデバイスの構成情報を取得します。
USHORT size;
NTSTATUS ntStatus;
PMY_DEVICE_CONTEXT myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES objectAttribs;
WDFMEMORY memoryHandle;
myDeviceContext = GetDeviceContext(Device);
ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
myDeviceContext->WdfUsbTargetDevice,
NULL,
&size
);
if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
return ntStatus;
}
WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;
ntStatus = WdfMemoryCreate(
&objectAttribs,
NonPagedPool,
POOL_TAG,
size,
&memoryHandle,
(PVOID)&configurationDescriptor
);
if (!NT_SUCCESS(ntStatus)) {
return ntStatus;
}
ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
myDeviceContext->WdfUsbTargetDevice,
configurationDescriptor,
&size
);
if (!NT_SUCCESS(ntStatus)) {
return ntStatus;
}
必要条件
| 要件 | 価値 |
|---|---|
| ターゲット プラットフォーム の | 万国 |
| 最小 KMDF バージョン | 1.0 |
| UMDF の最小バージョン を する | 2.0 |
| ヘッダー | wdfusb.h (Wdfusb.h を含む) |
| ライブラリ | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
| IRQL | PASSIVE_LEVEL |
| DDI コンプライアンス規則 を する | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExp usbKmdfIrql(kmdf) , usbKmdfIrql2(kmdf) , UsbKmdfIrqlExplicit(kmdf) |
関連項目
ExAllocatePoolWithTag の
WdfUsbTargetDeviceCreateWithParameters
WdfUsbTargetDeviceGetDeviceDescriptor の