WdfUsbTargetPipeFormatRequestForWrite 関数 (wdfusb.h)
[KMDF と UMDF に適用]
WdfUsbTargetPipeFormatRequestForWrite メソッドは、USB 出力パイプの書き込み要求を作成しますが、要求は送信しません。
構文
NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY WriteMemory,
[in, optional] PWDFMEMORY_OFFSET WriteOffset
);
パラメーター
[in] Pipe
WdfUsbInterfaceGetConfiguredPipe を呼び出して取得されたフレームワーク パイプ オブジェクトへのハンドル。
[in] Request
フレームワーク要求オブジェクトへのハンドル。 詳細については、「解説」を参照してください。
[in, optional] WriteMemory
フレームワーク メモリ オブジェクトへのハンドル。 このオブジェクトは、パイプに送信されるデータを含むバッファーを表します。 このバッファーの詳細については、次の「備考」セクションを参照してください。
[in, optional] WriteOffset
省略可能なバイト オフセットと長さの値を提供する呼び出し元によって割り当てられた WDFMEMORY_OFFSET 構造体へのポインター。 フレームワークでは、これらの値を使用して、書き込みバッファー内のデータ転送の開始アドレスと長さを決定します。 このポインターが NULL の場合、データ転送はバッファーの先頭から開始され、転送サイズはバッファー サイズになります。
戻り値
操作が成功した場合、WdfUsbTargetPipeFormatRequestForWrite はSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 説明 |
|---|---|
|
無効なパラメーターが検出されました。 |
|
メモリが不足していました。 |
|
無効なメモリ記述子が指定されたか、パイプの種類が無効か、転送方向が無効か、指定された I/O 要求が既に I/O ターゲットにキューに入れられました。 |
|
Offset パラメーターが指定した オフセット が無効です。 |
|
要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが 要求 を転送できるようにするため の十 分なIO_STACK_LOCATION構造を提供しません。 |
このメソッドは、他の NTSTATUS 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
注釈
WdfUsbTargetPipeFormatRequestForWrite の後に WdfRequestSend を使用して、書き込み要求を同期的または非同期的に送信します。 または、 WdfUsbTargetPipeWriteSynchronously メソッドを使用して、書き込み要求を同期的に送信します。
指定したパイプは出力パイプである必要があり、パイプの 種類 は WdfUsbPipeTypeBulk または WdfUsbPipeTypeInterrupt である必要があります。
ドライバーが I/O キューで受信した I/O 要求を転送することも、新しい要求を作成して送信することもできます。 どちらの場合も、フレームワークには要求オブジェクトとバッファー領域が必要です。
ドライバーが I/O キューで受信した I/O 要求を転送するには:
- WdfUsbTargetPipeFormatRequestForWrite メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
-
WdfUsbTargetPipeFormatRequestForWrite メソッドの WriteMemory パラメーターには、受信した要求の入力バッファーを使用します。
ドライバーは WdfRequestRetrieveInputMemory を呼び出して、要求の入力バッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得し、そのハンドルを WriteMemory の値として使用する必要があります。
ドライバーは、多くの場合、受信した I/O 要求を、I/O ターゲットに送信する小さな要求に分割するため、ドライバーが新しい要求を作成する可能性があります。
新しい I/O 要求を作成するには:
-
新しい要求オブジェクトを作成し、 WdfUsbTargetPipeFormatRequestForWrite メソッドの Request パラメーターのハンドルを 指定 します。
WdfRequestCreate を呼び出して、1 つ以上の要求オブジェクトを事前割り当てします。 これらの要求オブジェクトを再利用するには、 WdfRequestReuse を呼び出します。 ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。
-
バッファー領域を指定し、 WdfUsbTargetPipeFormatRequestForWrite メソッドの WriteMemory パラメーターのバッファーのハンドルを指定します。
ドライバーでは、フレームワークマネージド メモリへの WDFMEMORY ハンドルとしてこのバッファー領域を指定する必要があります。 ドライバーは、次のいずれかを実行できます。
- ドライバーが新しいバッファーを I/O ターゲットに渡す場合は、 WdfMemoryCreate または WdfMemoryCreatePreallocated を呼び出して新しいメモリ バッファーを作成します。
- WdfRequestRetrieveInputMemory を呼び出して、受信した I/O 要求のバッファーを表すメモリ オブジェクトへのハンドルを取得します (ドライバーがそのバッファーの内容を I/O ターゲットに渡す場合)。
同じ要求を使用する WdfUsbTargetPipeFormatRequestForWrite を 複数回呼び出しても、追加のリソース割り当ては発生しません。 そのため、 WdfRequestCreate がSTATUS_INSUFFICIENT_RESOURCESを返す可能性を減らすために、ドライバーの EvtDriverDeviceAdd コールバック関数は WdfRequestCreate を呼び出して、デバイスの 1 つ以上の要求オブジェクトを事前割り当てできます。 ドライバーは、後で WdfRequestCreate を呼び出して戻り値をSTATUS_INSUFFICIENT_RESOURCESすることなく、(WdfRequestReuse の呼び出し)、再フォーマット (WdfUsbTargetPipeFormatRequestForWrite の呼び出し)、および各要求オブジェクトの再送信 (呼び出し WdfRequestSend) を再利用できます。 パラメーター値が変更されない場合、再利用された要求オブジェクトに対する WdfUsbTargetPipeFormatRequestForWrite に対する後続のすべての呼び出しは、STATUS_SUCCESSを返します。 (ドライバーが毎回同じ要求書式設定メソッドを呼び出さない場合は、追加のリソースが割り当てられる可能性があります)。
I/O 要求の完了後に状態情報を取得する方法については、「 完了情報の取得」を参照してください。
WdfUsbTargetPipeFormatRequestForWrite メソッドと USB I/O ターゲットの詳細については、「USB I/O ターゲット」を参照してください。
例
次のコード例は、 kmdf_fx2 サンプル ドライバーのコード例です。 この例は、書き込み要求を USB パイプに転送する EvtIoWrite コールバック関数です。 この例では 、WdfRequestRetrieveInputMemory を呼び出して要求の入力バッファーを取得し、USB パイプに要求を送信できるように書き込み要求を書式設定します。 次に、 CompletionRoutine コールバック関数を登録します。 最後に、USB パイプに要求を送信します。
VOID
OsrFxEvtIoWrite(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t Length
)
{
NTSTATUS status;
WDFUSBPIPE pipe;
WDFMEMORY reqMemory;
PDEVICE_CONTEXT pDeviceContext;
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
status = STATUS_INVALID_PARAMETER;
goto Exit;
}
pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
pipe = pDeviceContext->BulkWritePipe;
status = WdfRequestRetrieveInputMemory(
Request,
&reqMemory
);
if (!NT_SUCCESS(status)){
goto Exit;
}
status = WdfUsbTargetPipeFormatRequestForWrite(
pipe,
Request,
reqMemory,
NULL
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
EvtRequestWriteCompletionRoutine,
pipe
);
if (WdfRequestSend(
Request,
WdfUsbTargetPipeGetIoTarget(pipe),
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
WdfRequestCompleteWithInformation(
Request,
status,
0
);
}
return;
}
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| 最小 KMDF バージョン | 1.0 |
| 最小 UMDF バージョン | 2.0 |
| Header | wdfusb.h (Wdfusb.h を含む) |
| Library | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI コンプライアンス規則 | DriverCreate(kmdf), KmdfIrql(kmdf)、KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、RequestFormattedValid(kmdf)、RequestSendAndForgetNoFormatting(kmdf)、RequestSendAndForgetNoFormatting2(kmdf)、UsbKmdfIrql(kmdf)、UsbKmdfIrql2(kmdf)、UsbKmdfIrqlExplicit(kmdf) |