次の方法で共有


WdfIoTargetFormatRequestForInternalIoctlOthers 関数 (wdfiotarget.h)

[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を返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターン コード 説明
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 キューで受信した標準以外の内部デバイス制御要求を転送するには:

  1. WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
  2. 受信した要求のコンテキスト情報を WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの OtherArg1OtherArg2OtherArg4 パラメーターに使用します。

    これらのパラメーター値を取得するには、ドライバーは WdfRequestGetParameters を呼び出し、返されるWDF_REQUEST_PARAMETERS構造体の DeviceIoControl メンバーを使用する必要があります。

I/O 要求の転送の詳細については、「I /O 要求の転送」を参照してください。

ドライバーは、多くの場合、受信した I/O 要求を、I/O ターゲットに送信する小さな要求に分割するため、ドライバーは新しい要求を作成する可能性があります。

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

  1. 新しい要求オブジェクトを作成し、 WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの Request パラメーターのハンドルを 指定 します。

    WdfRequestCreate を呼び出して、1 つ以上の要求オブジェクトを事前割り当てします。 これらの要求オブジェクトを再利用するには、 WdfRequestReuse を呼び出します。 ドライバーの EvtDriverDeviceAdd コールバック関数は、デバイスの要求オブジェクトを事前割り当てできます。

  2. 要求に必要な場合はコンテキスト バッファーを指定し、 WdfIoTargetFormatRequestForInternalIoctlOthers メソッドの OtherArg1OtherArg2OtherArg4 パラメーターのバッファー ハンドルを指定します。

    ドライバーでは、フレームワークマネージド メモリへの 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)

こちらもご覧ください

EvtDriverDeviceAdd

WDFMEMORY_OFFSET

WDF_REQUEST_PARAMETERS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetSendInternalIoctlOthersSynchronously

WdfIoTargetSendIoctlSynchronously

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCreate

WdfRequestGetParameters

WdfRequestReuse

WdfRequestSend