WdfUsbTargetDeviceSendControlTransferSynchronously 関数 (wdfusb.h)
[KMDF と UMDF に適用]
WdfUsbTargetDeviceSendControlTransferSynchronously メソッドは、USB コントロール転送要求をビルドし、I/O ターゲットに同期的に送信します。
構文
NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
[in] WDFUSBDEVICE UsbDevice,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in] PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
[in, optional] PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional] PULONG BytesTransferred
);
パラメーター
[in] UsbDevice
WdfUsbTargetDeviceCreateWithParameters の以前の呼び出しから取得された USB デバイス オブジェクトへのハンドル。
[in, optional] Request
フレームワーク要求オブジェクトへのハンドル。 このパラメーターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。
[in, optional] RequestOptions
要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。
[in] SetupPacket
制御転送を記述する呼び出し元によって割り当てられた WDF_USB_CONTROL_SETUP_PACKET 構造体へのポインター。
[in, optional] MemoryDescriptor
デバイス固有のコマンドに応じて、入力バッファーまたは出力バッファーを記述する呼び出し元によって割り当てられた WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。
[out, optional] BytesTransferred
転送されるバイト数を受け取る場所へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。
戻り値
操作が成功した場合、WdfUsbTargetDeviceSendControlTransferSynchronously は I/O ターゲットの完了状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。
リターン コード | 説明 |
---|---|
|
無効なパラメーターが検出されました。 |
|
メモリが不足していました。 |
|
無効なメモリ記述子が指定されたか、指定された I/O 要求が既に I/O ターゲットにキューに登録されています。 |
|
ドライバーがタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。 |
このメソッドは、他の NTSTATUS 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
注釈
USB コントロール転送要求を同期的に送信するには、 WdfUsbTargetDeviceSendControlTransferSynchronously メソッドを使用します。 このような要求を非同期に送信するには、 WdfUsbTargetDeviceFormatRequestForControlTransfer を使用し、その後に WdfRequestSend を使用します。
WdfUsbTargetDeviceSendControlTransferSynchronously メソッドは、RequestOptions パラメーターが指すWDF_REQUEST_SEND_OPTIONS構造体にタイムアウト値をドライバーが提供しない限り、またはエラーが検出されない限り、要求が完了するまで戻りません。
ドライバーが I/O キューで受信した I/O 要求を転送することも、新しい要求を作成して送信することもできます。 どちらの場合も、フレームワークには要求オブジェクトが必要であり、制御転送の種類によっては、バッファー領域が必要になる場合があります。
ドライバーが I/O キューで受信した I/O 要求を転送するには:
- Request パラメーターに対して、受信した 要求 のハンドルを指定します。
-
MemoryDescriptor パラメーターには、受信した要求の入力バッファーまたは出力バッファーを使用します。
ドライバーは、WdfRequestRetrieveInputMemory または WdfRequestRetrieveOutputMemory を呼び出して、要求の入力バッファーまたは出力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得し、そのハンドルを、ドライバーが MemoryDescriptor パラメーターに提供するWDF_MEMORY_DESCRIPTOR構造体に配置できます。
-
Request パラメーターに NULL 要求ハンドルを 指定 するか、新しい要求オブジェクトを作成してそのハンドルを指定します。
- NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。 この手法は簡単に使用できますが、ドライバーは要求を取り消すことができません。
- WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse を呼び出してこれらの要求オブジェクトを再利用できます。 この手法を使用すると、ドライバーの EvtDriverDeviceAdd コールバック関数を使用して、デバイスの要求オブジェクトを事前に割り当てることができます。 さらに、別のドライバー スレッドは WdfRequestCancelSentRequest を呼び出して、必要に応じて要求を取り消すことができます。
ドライバーは、NULL 以外の RequestOptions パラメーターを指定できます。ドライバーが NULL 以外の要求パラメーターと NULL要求パラメーターのどちらを提供しているか。 たとえば、 RequestOptions パラメーターを使用してタイムアウト値を指定できます。
-
WdfUsbTargetDeviceSendControlTransferSynchronously メソッドの MemoryDescriptor パラメーターのバッファー領域を指定します。
ドライバーは、ローカルに割り当てられたバッファー、WDFMEMORY ハンドル、または MDL として、このバッファー領域を指定できます。 最も便利な方法を使用できます。
必要に応じて、フレームワークはバッファーの説明を、データ バッファーにアクセスするための I/O ターゲットの メソッドに適した記述に変換します。
次の手法を使用できます。
-
ローカル バッファーを指定する
WdfUsbTargetDeviceSendControlTransferSynchronously は I/O 要求を同期的に処理するため、ドライバーは、次のコード例に示すように、呼び出し元のルーチンに対してローカルな要求バッファーを作成できます。
WDF_MEMORY_DESCRIPTOR memoryDescriptor; MY_BUFFER_TYPE myBuffer; WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor, (PVOID) &myBuffer, sizeof(myBuffer));
-
WDFMEMORY ハンドルを指定する
次のコード例に示すように、 WdfMemoryCreate または WdfMemoryCreatePreallocated を呼び出して、フレームワークマネージド メモリへのハンドルを取得します。
WDF_MEMORY_DESCRIPTOR memoryDescriptor; WDFMEMORY memoryHandle = NULL; status = WdfMemoryCreate(NULL, NonPagedPool, POOL_TAG, MY_BUFFER_SIZE, &memoryHandle, NULL); WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor, memoryHandle, NULL);
または、ドライバーは WdfRequestRetrieveInputMemory または WdfRequestRetrieveOutputMemory を呼び出して、受信した I/O 要求のバッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得することもできます (ドライバーがそのバッファーの内容を I/O ターゲットに渡す場合)。 ドライバーは、 WdfUsbTargetDeviceSendControlTransferSynchronously が I/O ターゲットに送信する新しい要求が削除、再利用、または再フォーマットされるまで、受信した I/O 要求を完了することはできません。 (WdfUsbTargetDeviceSendControlTransferSynchronously は、メモリ オブジェクトの参照カウントをインクリメントします。要求オブジェクトを削除、再利用、または再フォーマットすると、メモリ オブジェクトの参照カウントがデクリメントされます)。
-
MDL を指定する
ドライバーは、WdfRequestRetrieveInputWdmMdl または WdfRequestRetrieveOutputWdmMdl を呼び出すことによって、受信した I/O 要求に関連付けられている MDL を取得できます。
-
ローカル バッファーを指定する
I/O 要求の完了後に状態情報を取得する方法については、「 完了情報の取得」を参照してください。
WdfUsbTargetDeviceSendControlTransferSynchronously メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。
例
次のコード例では、 WDF_USB_CONTROL_SETUP_PACKET 構造体を初期化し、 WdfUsbTargetDeviceSendControlTransferSynchronously を呼び出してベンダー固有の制御転送を送信します。
WDF_USB_CONTROL_SETUP_PACKET controlSetupPacket;
WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
&controlSetupPacket,
BmRequestHostToDevice,
BmRequestToDevice,
USBFX2LK_REENUMERATE,
0,
0
);
status = WdfUsbTargetDeviceSendControlTransferSynchronously(
UsbDevice,
WDF_NO_HANDLE,
NULL,
&controlSetupPacket,
NULL,
NULL
);
return status;
要件
要件 | 値 |
---|---|
対象プラットフォーム | ユニバーサル |
最小 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)、 RequestForUrbXrb(kmdf)、 SyncReqSend(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf) |
こちらもご覧ください
WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示