WdfIoTargetSendInternalIoctlOthersSynchronously 関数 (wdfiotarget.h)

[KMDF にのみ適用]

WdfIoTargetSendInternalIoctlOthersSynchronously メソッドは、標準以外の内部デバイス制御要求をビルドし、I/O ターゲットに同期的に送信します。

構文

NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg1,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg2,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg4,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesReturned
);

パラメーター

[in] IoTarget

WdfDeviceGetIoTarget または WdfIoTargetCreate の以前の呼び出し、または特殊化された I/O ターゲットが提供するメソッドから取得されたローカルまたはリモートの I/O ターゲット オブジェクトへのハンドル。

[in, optional] Request

フレームワーク要求オブジェクトへのハンドル。 このパラメーターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[in] IoctlCode

I/O ターゲットがサポートする I/O 制御コード (IOCTL)。

[in, optional] OtherArg1

コンテキスト情報を含むメモリ バッファーを記述する WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。

[in, optional] OtherArg2

コンテキスト情報を含むメモリ バッファーを記述するWDF_MEMORY_DESCRIPTOR構造体へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。

[in, optional] OtherArg4

コンテキスト情報を含むメモリ バッファーを記述するWDF_MEMORY_DESCRIPTOR構造体へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。

[in, optional] RequestOptions

要求のオプションを指定する呼び出し元によって割り当てられた WDF_REQUEST_SEND_OPTIONS 構造体へのポインター。 このポインターは省略可能であり、 NULL にすることができます。 詳細については、「解説」を参照してください。

[out, optional] BytesReturned

別のドライバーが WdfRequestCompleteWithInformation を呼び出して要求を完了したときに提供する情報 (転送されたバイト数など) を受け取る場所へのポインター。 このポインターは省略可能であり、 NULL にすることができます。

戻り値

操作が成功した場合、 WdfIoTargetSendInternalIoctlOthersSynchronously は内部デバイス制御要求の完了後にを返し、戻り値は要求の完了状態値です。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターン コード 説明
STATUS_INVALID_PARAMETER
無効なパラメーターが検出されました。
STATUS_INFO_LENGTH_MISMATCH
RequestOptions パラメーターが指すWDF_REQUEST_SEND_OPTIONS構造体のサイズが正しくありません。
STATUS_INVALID_DEVICE_REQUEST
要求は既に I/O ターゲットにキューに入れられました。
STATUS_INSUFFICIENT_RESOURCES
フレームワークはシステム リソース (通常はメモリ) を割り当てませんでした。
STATUS_IO_TIMEOUT
ドライバーはタイムアウト値を指定し、割り当てられた時間内に要求が完了しませんでした。
STATUS_REQUEST_NOT_ACCEPTED
要求パラメーターが表す I/O 要求パケット (IRP) は、ドライバーが 要求 を転送できるようにするため の十 分なIO_STACK_LOCATION構造を提供しません。
 

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

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

注釈

非標準の内部デバイス制御要求では、IOCTL コードを使用して実行する操作を識別しますが、要求では、他の内部デバイス制御要求で使用される標準の入力バッファーと出力バッファーは使用されません。 一連の対話ドライバーを作成する場合は、この一連のドライバーで要求の引数 (OtherArg1、OtherArg2OtherArg4) を使用する方法を定義できます。

OtherArg3 というパラメーターはありません。これは、フレームワークがドライバーの IO_STACK_LOCATION 構造体の Other.Parameters 共用体の Argument1Argument2および Argument4 メンバーにこれらのパラメーターを関連付けるからです。 その共用体の Argument3 メンバーは IoctlCode パラメーターから値を受け取ります。そのため、他のドライバーが指定した値では使用できません。

標準以外の内部デバイス制御要求を同期的に送信するには、 WdfIoTargetSendInternalIoctlOthersSynchronously メソッドを使用します。 内部デバイス制御要求を非同期で送信するには、 WdfIoTargetFormatRequestForInternalIoctlOthers を使用し、その後に WdfRequestSend を続けます。

内部デバイス制御要求の詳細については、「 I/O 制御コードの使用」を参照してください。

WdfIoTargetSendInternalIoctlOthersSynchronously メソッドは、要求が完了するまで、ドライバーが RequestOptions パラメーターのWDF_REQUEST_SEND_OPTIONS構造体にタイムアウト値を提供しない限り、またはエラーが検出されない限り、戻りません。

ドライバーが I/O キューで受信した標準以外の内部デバイス制御要求を転送することも、新しい要求を作成して送信することもできます。 どちらの場合も、フレームワークには要求オブジェクトと、場合によってはコンテキスト空間が必要です。

ドライバーが I/O キューで受信した標準以外の内部デバイス制御要求を転送するには:

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

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

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

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

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

  1. WdfIoTargetSendInternalIoctlOthersSynchronously メソッドの Request パラメーターに NULL 要求ハンドルを指定するか、新しい要求オブジェクトを作成してそのハンドルを指定します。
    • NULL 要求ハンドルを指定すると、フレームワークは内部要求オブジェクトを使用します。 この手法は簡単に使用できますが、ドライバーは要求をキャンセルできません。
    • WdfRequestCreate を呼び出して 1 つ以上の要求オブジェクトを作成する場合は、WdfRequestReuse を呼び出すことで、これらの要求オブジェクトを再利用できます。 この手法を使用すると、ドライバーの EvtDriverDeviceAdd コールバック関数を使用して、デバイスの要求オブジェクトを事前に割り当てできます。 さらに、別のドライバー スレッドは WdfRequestCancelSentRequest を呼び出して、必要に応じて要求を取り消すことができます。

    ドライバーは、NULL 以外の RequestOptions パラメーターを指定できます。これは、ドライバーが NULL 以外の要求パラメーターまたは NULL要求パラメーターを提供するかどうかです。 たとえば、 RequestOptions パラメーターを使用してタイムアウト値を指定できます。

  2. 要求に必要な場合は、WdfIoTargetSendInternalIoctlOthersSynchronously メソッドの OtherArg1OtherArg2、OtherArg4 パラメーターのコンテキスト領域を指定します。

    ドライバーでは、このコンテキスト領域をローカルに割り当てられたバッファーとして、WDFMEMORY ハンドルとして、またはメモリ記述子リスト (MDLs) として指定できます。 最も便利な方法を使用できます。

    バッファー領域を指定するには、次の手法を使用できます。

    • ローカル バッファーを指定します。

      WdfIoTargetSendInternalIoctlOthersSynchronously は I/O 要求を同期的に処理するため、次のコード例に示すように、ドライバーは呼び出し元ルーチンに対してローカルな要求バッファーを作成できます。

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
      MY_BUFFER_TYPE  MyBuffer;
      WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                        (PVOID) &MyBuffer,
                                        sizeof(MyBuffer));
      
    • WDFMEMORY ハンドルを指定します。

      次のコード例に示すように、 WdfMemoryCreate または WdfMemoryCreatePreallocated を呼び出して、フレームワークマネージド メモリへのハンドルを取得します。

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
      WDFMEMORY  MemoryHandle = NULL;
      status = WdfMemoryCreate(NULL,
                               NonPagedPool,
                               POOL_TAG,
                               MY_BUFFER_SIZE,
                               &MemoryHandle,
                               NULL);
      WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor,
                                        MemoryHandle,
                                        NULL);
      
    • MDL を指定します。

      ドライバーは、WdfRequestRetrieveInputWdmMdl と WdfRequestRetrieveOutputWdmdl を呼び出すことによって、受信した I/O 要求に関連付けられている MDL を取得できます。

I/O 要求の完了後に状態情報を取得する方法については、「 完了情報の取得」を参照してください。

WdfIoTargetSendInternalIoctlOthersSynchronously の詳細については、「一般的な I/O ターゲットへの I/O 要求の送信」を参照してください。

I/O ターゲットの詳細については、「I /O ターゲットの使用」を参照してください。

次のコード例では、IEEE 1394 IRB 構造体を初期化し、構造体のアドレスを使用して WDF_MEMORY_DESCRIPTOR 構造体を初期化し、 WdfIoTargetSendInternalIoctlOthersSynchronously を呼び出します。

WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;

Irb.FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
Irb.Flags = 0;
Irb.u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
Irb.u.AllocateAddressRange.fulFlags = fulFlags;
Irb.u.AllocateAddressRange.nLength = nLength;
Irb.u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
Irb.u.AllocateAddressRange.fulAccessType = fulAccessType;
Irb.u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
Irb.u.AllocateAddressRange.Callback = NULL;
Irb.u.AllocateAddressRange.Context = NULL;
Irb.u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
Irb.u.AllocateAddressRange.FifoSListHead = NULL;
Irb.u.AllocateAddressRange.FifoSpinLock = NULL;
Irb.u.AllocateAddressRange.AddressesReturned = 0;
Irb.u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
Irb.u.AllocateAddressRange.DeviceExtension = deviceExtension;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &descriptor,
                                  &Irb,
                                  sizeof (IRB)
                                  );

ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
                                                           IoTarget, 
                                                           NULL,
                                                           IOCTL_1394_CLASS,
                                                           &descriptor,
                                                           NULL,
                                                           NULL,
                                                           NULL,
                                                           NULL
                                                           );

要件

要件
対象プラットフォーム ユニバーサル
最小 KMDF バージョン 1.0
Header wdfiotarget.h (Wdf.h を含む)
Library Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 DeferredRequestCompleted(kmdf)DriverCreate(kmdf)IoctlReqs(kmdf)KmdfIrql(kmdf)KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)、 ReadReqs(kmdf)RequestCompleted(kmdf)RequestCompletedLocal(kmdf)WriteReqs(kmdf)

こちらもご覧ください

EvtDriverDeviceAdd

IO_STACK_LOCATION

WDF_MEMORY_DESCRIPTOR

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER

WDF_REQUEST_PARAMETERS

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForInternalIoctlOthers

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCancelSentRequest

WdfRequestCompleteWithInformation

WdfRequestCreate

WdfRequestGetParameters

WdfRequestRetrieveInputWdmMdl

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse

WdfRequestSend