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 構成のみを選択できますが、この 1 つの構成内で複数のインターフェイスを選択できます。
ドライバーは、次のように 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 |
Header | wdfusb.h (Wdfusb.h を含む) |
Library | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
IRQL | PASSIVE_LEVEL |
DDI コンプライアンス規則 | DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf) |