WdfUsbTargetDeviceFormatRequestForCyclePort 関数 (wdfusb.h)

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

[KMDF にのみ適用]

WdfUsbTargetDeviceFormatRequestForCyclePort メソッドは、指定したデバイスが接続されているポートの電源サイクル要求を作成しますが、要求は送信しません。

構文

NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
  [in] WDFUSBDEVICE UsbDevice,
  [in] WDFREQUEST   Request
);

パラメーター

[in] UsbDevice

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

[in] Request

フレームワーク要求オブジェクトへのハンドル。詳細については、「解説」を参照してください。

戻り値

操作が成功した場合、WdfUsbTargetDeviceFormatRequestForCyclePort はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返すことができます。

リターンコード	説明
STATUS_INVALID_DEVICE_STATE	デバイスの USB デバイスが使用できませんでした。
STATUS_INSUFFICIENT_RESOURCES	メモリが不足していました。

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

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

注釈

WdfUsbTargetDeviceFormatRequestForCyclePort の後に WdfRequestSend を使用して、電源サイクル要求を同期的または非同期的に送信します。または、 WdfUsbTargetDeviceCyclePortSynchronously メソッドを使用して、要求を同期的に送信します。

ドライバーが WdfRequestSend を呼び出す前に、 WdfIoTargetStop を呼び出す必要があり、I/O ターゲットに送信したすべての I/O 要求を完了または取り消す必要があります。ドライバーは、サイクル要求が完了するまで、追加の I/O 要求を I/O ターゲットに送信することはできません。

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

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

新しい I/O 要求を作成するには、 WdfRequestCreate を呼び出して要求オブジェクトを事前割り当てします。 WdfUsbTargetDeviceFormatRequestForCyclePort メソッドの Request パラメーターの要求ハンドルを指定します。要求オブジェクトは、WdfRequestReuse を呼び出すことで再利用できます。ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。

WdfUsbTargetDeviceFormatRequestForCyclePort を呼び出して I/O 要求を書式設定した後、ドライバーは WdfRequestSend を呼び出して要求を (同期的または非同期的に) I/O ターゲットに送信する必要があります。 WdfRequestSend へのこの呼び出しは、IRQL = PASSIVE_LEVELで行う必要があります。

同じ要求を使用する WdfUsbTargetDeviceFormatRequestForCyclePort を複数回呼び出しても、追加のリソース割り当ては発生しません。そのため、 WdfRequestCreate がSTATUS_INSUFFICIENT_RESOURCESを返す可能性を減らすために、ドライバーの EvtDriverDeviceAdd コールバック関数は WdfRequestCreate を呼び出して、デバイスの 1 つ以上の要求オブジェクトを事前割り当てできます。ドライバーは、その後、 WdfRequestReuse の呼び出し、再フォーマット ( WdfUsbTargetDeviceFormatRequestForCyclePort の呼び出し)、および WdfRequestCreate への後の呼び出しからSTATUS_INSUFFICIENT_RESOURCES戻り値を危険にさらすことなく、各要求オブジェクトを再送信 (呼び出し WdfRequestSend) できます。再利用された要求オブジェクトに対する WdfUsbTargetDeviceFormatRequestForCyclePort に対する後続のすべての呼び出しは、パラメーター値が変更されない場合、STATUS_SUCCESSを返します。 (ドライバーが毎回同じ要求形式メソッドを呼び出さない場合は、追加のリソースが割り当てられる可能性があります)。

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

例

次のコード例では、電源サイクル要求の書式を設定し、 CompletionRoutine コールバック関数を登録して、要求を I/O ターゲットに送信します。

status = WdfUsbTargetDeviceFormatRequestForCyclePort(
                                            UsbDevice,
                                            request
                                            );
if (!NT_SUCCESS(status)){
    return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyCompletionRoutine,
                               NULL
                               );

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfusb.h (Wdfusb.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf), KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 RequestFormattedValid(kmdf)、 RequestSendAndForgetNoFormatting(kmdf)、 RequestSendAndForgetNoFormatting2(kmdf)、 UsbKmdfIrql(kmdf)、 UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf)