WdfUsbTargetDeviceSendControlTransferSynchronously 関数 (wdfusb.h)

[アーティクル]
08/08/2023

[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 ターゲットの完了状態値を返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INSUFFICIENT_RESOURCES	メモリが不足していました。
STATUS_INVALID_DEVICE_REQUEST	無効なメモリ記述子が指定されたか、指定された I/O 要求が既に I/O ターゲットにキューに登録されています。
STATUS_IO_TIMEOUT	ドライバーがタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。

このメソッドは、他の 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 を取得できます。

フレームワークは、内部 URB に USBD_SHORT_TRANSFER_OK フラグを設定します。このフラグを設定すると、データ転送の最後のパケットが最大パケットサイズより小さくなります。

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)