[KMDF にのみ適用]
WdfIoTargetFormatRequestForInternalIoctlOthers メソッドは、I/O ターゲットに対する標準以外の内部デバイス制御要求をビルドしますが、要求は送信しません。
構文
NTSTATUS WdfIoTargetFormatRequestForInternalIoctlOthers(
[in] WDFIOTARGET IoTarget,
[in] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] WDFMEMORY OtherArg1,
[in, optional] PWDFMEMORY_OFFSET OtherArg1Offset,
[in, optional] WDFMEMORY OtherArg2,
[in, optional] PWDFMEMORY_OFFSET OtherArg2Offset,
[in, optional] WDFMEMORY OtherArg4,
[in, optional] PWDFMEMORY_OFFSET OtherArg4Offset
);
パラメーター
[in] IoTarget
WdfDeviceGetIoTarget または WdfIoTargetCreate をする以前の呼び出しから取得されたローカルまたはリモートの I/O ターゲット オブジェクト、または特殊な I/O ターゲットが提供するメソッドからのハンドル。
[in] Request
フレームワーク要求オブジェクトへのハンドル。 詳細については、次の「解説」セクションを参照してください。
[in] IoctlCode
I/O ターゲットがサポートする I/O 制御コード (IOCTL)。
[in, optional] OtherArg1
フレームワーク メモリ オブジェクトへのハンドル。 このオブジェクトは、ドライバーが要求固有のドライバー定義コンテキスト情報に使用するバッファーを表します。 詳細については、次の「解説」セクションを参照してください。 このパラメーターは省略可能であり、NULL できます。
[in, optional] OtherArg1Offset
省略可能なバイト オフセットと長さの値を提供する呼び出し元によって割り当てられた WDFMEMORY_OFFSET 構造体へのポインター。 ドライバーは、これらの値を使用して、OtherArg1で指定されたコンテキスト領域のセグメントの開始アドレスと長さを指定できます。 このパラメーターは省略可能であり、NULL できます。
[in, optional] OtherArg2
フレームワーク メモリ オブジェクトへのハンドル。 このオブジェクトは、ドライバーが要求固有のドライバー定義コンテキスト情報に使用するバッファーを表します。 詳細については、次の「解説」セクションを参照してください。 このパラメーターは省略可能であり、NULL できます。
[in, optional] OtherArg2Offset
省略可能なバイト オフセットと長さの値を提供する呼び出し元によって割り当てられた WDFMEMORY_OFFSET 構造体へのポインター。 ドライバーは、これらの値を使用して、OtherArg2で指定されたコンテキスト領域のセグメントの開始アドレスと長さを指定できます。 このパラメーターは省略可能であり、NULL できます。
[in, optional] OtherArg4
フレームワーク メモリ オブジェクトへのハンドル。 このオブジェクトは、ドライバーが要求固有のドライバー定義コンテキスト情報に使用するバッファーを表します。 詳細については、次の「解説」セクションを参照してください。 このパラメーターは省略可能であり、NULL できます。
[in, optional] OtherArg4Offset
省略可能なバイト オフセットと長さの値を提供する呼び出し元によって割り当てられた WDFMEMORY_OFFSET 構造体へのポインター。 ドライバーは、これらの値を使用して、OtherArg4で指定されたコンテキスト領域のセグメントの開始アドレスと長さを指定できます。 このパラメーターは省略可能であり、NULL できます。
戻り値
WdfIoTargetFormatRequestForInternalIoctlOthers 、操作が成功した場合にSTATUS_SUCCESSを返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 説明 |
|---|---|
|
無効なパラメーターが検出されました。 |
|
転送の長さがバッファー長より大きかったか、I/O 要求が既に I/O ターゲットにキューに入れられました。 |
|
フレームワークは、システム リソース (通常はメモリ) を割り当てませんでした。 |
|
要求 パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが要求を転送するのに十分な IO_STACK_LOCATION 構造体を提供しません。 |
このメソッドは、他のNTSTATUS 値を返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
注釈
WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの後に、WdfRequestSend メソッドを使用して、標準以外の内部デバイス制御要求を同期的または非同期的に送信します。 または、WdfIoTargetSendInternalIoctlOthersSynchronously メソッドを使用して、非標準の内部デバイス制御要求を同期的に送信します。
ドライバーが I/O キューで受信した標準以外の内部デバイス制御要求を転送することも、新しい要求を作成して送信することもできます。 どちらの場合も、フレームワークには要求オブジェクトとバッファー領域が必要です。
ドライバーが I/O キューで受信した標準以外の内部デバイス制御要求を転送するには:
- WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
-
WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの OtherArg1、OtherArg2、OtherArg4 パラメーターに対して、受信した要求のコンテキスト情報を使用します。
これらのパラメーター値を取得するには、ドライバー WdfRequestGetParameters を呼び出し、返される WDF_REQUEST_PARAMETERS 構造体の DeviceIoControl メンバーを使用する必要があります。
ドライバーは、多くの場合、受信した I/O 要求を、I/O ターゲットに送信する小さな要求に分割するため、ドライバーは新しい要求を作成する可能性があります。
新しい I/O 要求を作成するには:
-
新しい要求オブジェクトを作成し、WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの Request パラメーターのハンドルを指定します。
WdfRequestCreate 呼び出して、1 つ以上の要求オブジェクトを事前割り当てします。 これらの要求オブジェクトは、WdfRequestReuseを呼び出すことによって再利用できます。 ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。
-
要求に必要な場合はコンテキスト バッファーを指定し、WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの OtherArg1、OtherArg2、および OtherArg4 パラメーター バッファー ハンドルを指定します。
ドライバーは、フレームワークマネージド メモリへの WDFMEMORY ハンドルとしてこのバッファー領域を指定する必要があります。 WDFMEMORY ハンドルを取得するには、ドライバーは WdfMemoryCreate 呼び出すか、WdfMemoryCreatePreallocated をします。
同じ要求を使用 WdfIoTargetFormatRequestForInternalIoctlOthers を複数回呼び出しても、追加のリソース割り当ては発生しません。 そのため、WdfRequestCreate がSTATUS_INSUFFICIENT_RESOURCESを返す可能性を減らすために、ドライバーの EvtDriverDeviceAdd コールバック関数は、WdfRequestCreate を呼び出して、デバイスの 1 つ以上の要求オブジェクトを事前割り当てできます。 ドライバーは、その後、各要求オブジェクトを再利用 (WdfRequestReuse 呼び出し)、再フォーマット (WdfIoTargetFormatRequestForInternalIoctlOthers 呼び出し)、および各要求オブジェクトの再送信 (WdfRequestSendの呼び出し) を行い、後で WdfRequestCreate 呼び出すSTATUS_INSUFFICIENT_RESOURCES戻り値を危険にさらす必要はありません。 (ドライバーが毎回同じ要求形式メソッドを呼び出さない場合は、追加のリソースが割り当てられる可能性があります)。再利用された要求オブジェクト WdfIoTargetFormatRequestForInternalIoctlOthers に対するすべての後続の呼び出しは、パラメーター値が変更されない場合、STATUS_SUCCESSを返します。
I/O 要求が完了した後の状態情報の取得については、「完了情報の取得を参照してください。
WdfIoTargetFormatRequestForInternalIoctlOthersの詳細については、「一般的な I/O ターゲットへの I/O 要求の送信」を参照してください。
I/O ターゲットの詳細については、「I/O ターゲットの使用」を参照してください。
例示
次のコード例では、フレームワーク メモリ オブジェクトを作成し、メモリ オブジェクトに含まれるバッファーを取得し、バッファーを初期化します。 次に、要求の書式を設定し、CompletionRoutine コールバック関数 設定し、要求を I/O ターゲットに送信します。
PIRB pIrb;
WDFMEMORY memory;
NTSTATUS status;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
sizeof(IRB),
&memory,
NULL
);
if (!NT_SUCCESS(status)) {
goto Done;
}
pIrb = WdfMemoryGetBuffer(
memory,
NULL
);
pIrb->FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
pIrb->Flags = 0;
pIrb->u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
pIrb->u.AllocateAddressRange.fulFlags = fulFlags;
pIrb->u.AllocateAddressRange.nLength = nLength;
pIrb->u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
pIrb->u.AllocateAddressRange.fulAccessType = fulAccessType;
pIrb->u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
pIrb->u.AllocateAddressRange.Callback = NULL;
pIrb->u.AllocateAddressRange.Context = NULL;
pIrb->u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
pIrb->u.AllocateAddressRange.FifoSListHead = NULL;
pIrb->u.AllocateAddressRange.FifoSpinLock = NULL;
pIrb->u.AllocateAddressRange.AddressesReturned = 0;
pIrb->u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
pIrb->u.AllocateAddressRange.DeviceExtension = deviceExtension;
status = WdfIoTargetFormatRequestForInternalIoctlOthers(
IoTarget,
Request,
IOCTL_1394_CLASS,
memory,
NULL,
NULL,
NULL,
NULL,
NULL
);
if (!NT_SUCCESS(status)) {
goto Done;
}
WdfRequestSetCompletionRoutine(
Request,
MyRequestCompletion,
NULL
);
if (WdfRequestSend(
Request,
IoTarget,
NULL
) == FALSE) {
status = WdfRequestGetStatus(Request);
}
else {
status = STATUS_SUCCESS;
}
必要条件
| 要件 | 価値 |
|---|---|
| ターゲット プラットフォーム の | 普遍 |
| 最小 KMDF バージョン | 1.0 |
| ヘッダー | wdfiotarget.h (Wdf.h を含む) |
| 図書館 | Wdf01000.sys (フレームワーク ライブラリのバージョン管理を参照)。 |
| IRQL | <=DISPATCH_LEVEL |
| DDI コンプライアンス規則 を する | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf) |
こちらもご覧ください
EvtDriverDeviceAdd の
WdfDeviceGetIoTarget の
WdfIoTargetCreate の
WdfIoTargetSendInternalIoctlOthersSynchronously を する
WdfIoTargetSendIoctlSynchronously を する
WdfMemoryCreatePreallocated の