WdfUsbTargetDeviceSendUrbSynchronously 関数 (wdfusb.h)

[KMDF にのみ適用]

WdfUsbTargetDeviceSendUrbSynchronously メソッドは、URB で記述されている要求パラメーターを使用して、指定された USB デバイスに USB 要求を同期的に送信します。

構文

NTSTATUS WdfUsbTargetDeviceSendUrbSynchronously(
  [in]           WDFUSBDEVICE              UsbDevice,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           PURB                      Urb
);

パラメーター

[in] UsbDevice

WdfUsbTargetDeviceCreateWithParameters の以前の呼び出しから取得された USB デバイス オブジェクトへのハンドル。

[in, optional] Request

フレームワーク要求オブジェクトへのハンドル。 このパラメーターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[in, optional] RequestOptions

要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[in] Urb

呼び出し元で初期化された URB 構造体へのポインター。

ドライバーが以前 に WdfUsbTargetDeviceCreateWithParameters を呼び出して UsbDevice を作成した場合、ドライバーは WdfUsbTargetDeviceCreateUrb または WdfUsbTargetDeviceCreateIsochUrb を使用してこの URB を作成する必要があります。

戻り値

操作が成功した場合、WdfUsbTargetDeviceSendUrbSynchronously は I/O ターゲットの完了状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターン コード 説明
STATUS_INVALID_PARAMETER
無効なパラメーターが検出されました。
STATUS_INVALID_DEVICE_REQUEST
呼び出し元の IRQL が無効です。
STATUS_INSUFFICIENT_RESOURCES
メモリ不足が使用可能でした。
STATUS_IO_TIMEOUT
ドライバーはタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。
 

このメソッドは、他の NTSTATUS 値を返す場合もあります。

ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。

注釈

USB コントロール転送要求を同期的に送信するには、 WdfUsbTargetDeviceSendUrbSynchronously メソッドを使用します。 このような要求を非同期に送信するには、 WdfUsbTargetDeviceFormatRequestForUrb を使用し、その後に WdfRequestSend を使用します。

WdfUsbTargetDeviceSendUrbSynchronously メソッドは、要求が完了するまで、ドライバーが RequestOptions パラメーターのWDF_REQUEST_SEND_OPTIONS構造体でタイムアウト値を提供しない限り、またはエラーが検出されない限り、戻りません。

ドライバーが I/O キューで受信した I/O 要求を転送することも、新しい要求を作成して送信することもできます。

ドライバーが I/O キューで受信した I/O 要求を転送するには、受信した要求のハンドルを WdfUsbTargetDeviceSendUrbSynchronously メソッドの Request パラメーターに指定します。

新しい要求を作成して送信するには、Request パラメーターに NULL 要求ハンドルを指定するか、新しい要求オブジェクトを作成してそのハンドルを指定します。

  • NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。 この手法は簡単に使用できますが、ドライバーは要求を取り消すことができません。
  • WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse を呼び出すことによって、これらの要求オブジェクトを再利用できます。 この手法により、ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前に割り当てることができます。 さらに、別のドライバー スレッドは、必要に応じて、要求を取り消すために WdfRequestCancelSentRequest を呼び出すことができます。
ドライバーは NULL 以外のRequestOptions パラメーターを指定できます。これは、ドライバーが NULL 以外の要求パラメーターまたは NULL要求パラメーターを提供するかどうかです。 たとえば、 RequestOptions パラメーターを使用してタイムアウト値を指定できます。

I/O 要求が完了した後の状態情報の取得については、「 完了情報の取得」を参照してください。

WdfUsbTargetDeviceSendUrbSynchronously メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。

次のコード例では、URB 構造体を初期化し、 WdfUsbTargetDeviceSendUrbSynchronously を呼び出します。

URB Urb;
NTSTATUS status;

Urb.UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
Urb.UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
Urb.UrbControlGetConfigurationRequest.TransferBufferLength = 1 ; // Must be 1
Urb.UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
Urb.UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
Urb.UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceSendUrbSynchronously(
                                                UsbDevice,
                                                NULL,
                                                NULL,
                                                &Urb
                                                );

要件

   
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
Header wdfusb.h (Wdfusb.h を含む)
Library Wdf01000.sys (フレームワーク ライブラリのバージョン管理を参照)。
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 DriverCreate(kmdf)KmdfIrql(kmdf)KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 SyncReqSend(kmdf)UsbKmdfIrql(kmdf)UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)

こちらもご覧ください

EvtDriverDeviceAdd

WDF_REQUEST_SEND_OPTIONS

WdfRequestCancelSentRequest

WdfRequestCreate

WdfRequestReuse

WdfRequestSend

WdfUsbTargetDeviceFormatRequestForUrb