WdfIoTargetFormatRequestForInternalIoctlOthers 関数 (wdfiotarget.h)

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

[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

[in, optional] OtherArg2Offset

省略可能なバイトオフセットと長さの値を提供する呼び出し元によって割り当てられた WDFMEMORY_OFFSET 構造体へのポインター。ドライバーは、これらの値を使用して、 OtherArg2 で指定されたコンテキスト領域のセグメントの開始アドレスと長さを指定できます。このパラメーターは省略可能であり、 NULL にすることができます。

[in, optional] OtherArg4

[in, optional] OtherArg4Offset

省略可能なバイトオフセットと長さの値を提供する呼び出し元によって割り当てられた WDFMEMORY_OFFSET 構造体へのポインター。ドライバーは、これらの値を使用して、 OtherArg4 で指定されたコンテキスト領域のセグメントの開始アドレスと長さを指定できます。このパラメーターは省略可能であり、 NULL にすることができます。

戻り値

操作が成功した場合、WdfIoTargetFormatRequestForInternalIoctlOthers はSTATUS_SUCCESSを返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	無効なパラメーターが検出されました。
STATUS_INVALID_DEVICE_REQUEST	転送長がバッファー長を超えているか、I/O 要求が既に I/O ターゲットにキューに入れられます。
STATUS_INSUFFICIENT_RESOURCES	フレームワークは、システムリソース (通常はメモリ) を割り当てませんでした。
STATUS_REQUEST_NOT_ACCEPTED	要求パラメーターが表す 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 要求を、I/O ターゲットに送信する小さな要求に分割するため、ドライバーは新しい要求を作成する可能性があります。

新しい I/O 要求を作成するには:

新しい要求オブジェクトを作成し、 WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの Request パラメーターのハンドルを指定します。
WdfRequestCreate を呼び出して、1 つ以上の要求オブジェクトを事前割り当てします。これらの要求オブジェクトを再利用するには、 WdfRequestReuse を呼び出します。ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。
要求に必要な場合はコンテキストバッファーを指定し、 WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの OtherArg1、 OtherArg2、 OtherArg4 パラメーターのバッファーハンドルを指定します。
ドライバーでは、フレームワークマネージドメモリへの WDFMEMORY ハンドルとして、このバッファー領域を指定する必要があります。 WDFMEMORY ハンドルを取得するために、ドライバーは WdfMemoryCreate または WdfMemoryCreatePreallocated を呼び出します。

ドライバーが WdfIoTargetFormatRequestForInternalIoctlOthers を呼び出してデバイスコントロール要求を書式設定した後、ドライバーは WdfRequestSend を呼び出して要求を (同期的または非同期的に) I/O ターゲットに送信する必要があります。

同じ要求を使用する WdfIoTargetFormatRequestForInternalIoctlOthers を複数回呼び出しても、追加のリソース割り当ては発生しません。そのため、 WdfRequestCreate がSTATUS_INSUFFICIENT_RESOURCESを返す可能性を減らすために、ドライバーの EvtDriverDeviceAdd コールバック関数は WdfRequestCreate を呼び出して、デバイスの 1 つ以上の要求オブジェクトを事前割り当てできます。ドライバーは、その後、WdfRequestReuse の呼び出し、再フォーマット (WdfIoTargetFormatRequestForInternalIoctlOthers の呼び出し)、および WdfRequestCreate の後の呼び出しからSTATUS_INSUFFICIENT_RESOURCES戻り値を危険にさらすことなく、各要求オブジェクトを再送 (呼び出し WdfRequestSend) できます。 (ドライバーが毎回同じ要求形式メソッドを呼び出さない場合は、追加のリソースが割り当てられる可能性があります)。再利用された要求オブジェクトに対する 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
Header	wdfiotarget.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 RequestFormattedValid(kmdf)、 RequestSendAndForgetNoFormatting(kmdf)、 RequestSendAndForgetNoFormatting2(kmdf)