WdfIoTargetSendInternalIoctlSynchronously 関数 (wdfiotarget.h)

[KMDF にのみ適用]

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

構文

NTSTATUS WdfIoTargetSendInternalIoctlSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    InputBuffer,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OutputBuffer,
  [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] InputBuffer

I/O ターゲットに書き込まれるバッファーを記述する呼び出し元によって割り当てられた WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 詳細については、次の「解説」セクションを参照してください。 このパラメーターは省略可能であり、要求がデータを送信しない場合は NULL できます。

[in, optional] OutputBuffer

I/O ターゲットからデータを受信するバッファーを記述する呼び出し元によって割り当てられた WDF_MEMORY_DESCRIPTOR 構造体へのポインター。 詳細については、次の「解説」セクションを参照してください。 このパラメーターは省略可能であり、要求がデータを受信しない場合は NULL を できます。

[in, optional] RequestOptions

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

[out, optional] BytesReturned

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

戻り値

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

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

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

備考

WdfIoTargetSendInternalIoctlSynchronously メソッドを使用して、内部デバイス制御要求を同期的に送信します。 内部デバイス制御要求を非同期的に送信するには、WdfIoTargetFormatRequestForInternalIoctl メソッドを使用し、その後に WdfRequestSend メソッドを使用します。

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

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

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

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

1. WdfIoTargetSendInternalIoctlSynchronously メソッドの Request パラメーターに対して、受信した要求のハンドルを指定します。
2. WdfIoTargetSendInternalIoctlSynchronously InputBuffer パラメーターを するために、受信した要求の入力バッファーを使用します。

   ドライバーは、要求の入力バッファー ハンドルを取得する WdfRequestRetrieveInputMemory を呼び出す必要があります。 その後、ドライバーは、InputBuffer パラメーターに対してドライバーが提供する WDF_MEMORY_DESCRIPTOR 構造体にそのハンドルを配置する必要があります。

3. WdfIoTargetSendInternalIoctlSynchronously OutputBuffer パラメーターに対して、受信した要求の出力バッファー 使用します。

   ドライバーは、要求の出力バッファーへのハンドルを取得するために WdfRequestRetrieveOutputMemory 呼び出す必要があります。その後、OutputBuffer パラメーターにドライバーが提供する WDF_MEMORY_DESCRIPTOR 構造体にそのハンドルを配置する必要があります。

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

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

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

   ドライバーは、以外の NULL または NULLRequest パラメーターを提供するかどうかに関係なく、NULLRequestOptions パラメーターを指定できます。 たとえば、RequestOptions パラメーターを使用してタイムアウト値を指定できます。

2. WdfIoTargetSendInternalIoctlSynchronously メソッドの InputBuffer のバッファー領域を指定し、要求に必要な場合は OutputBuffer パラメーターを します。

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

   必要に応じて、フレームワークは、IOCTL の転送の種類に対して正しいバッファーの説明を変換します。 IOCTL 転送タイプの詳細については、「I/O 制御コードの定義」を参照してください。

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

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

     WdfIoTargetSendInternalIoctlSynchronously は 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);
     

     または、ドライバーは WdfRequestRetrieveInputMemory 呼び出 すか、WdfRequestRetrieveOutputMemory を呼び出して、受信した I/O 要求のバッファーを表すフレームワーク メモリ オブジェクトへのハンドルを取得できます (ドライバーがそのバッファーの内容を I/O ターゲットに渡す場合)。 WdfIoTargetSendInternalIoctlSynchronously が I/O ターゲットに送信 する新しい要求が削除、再利用、または再フォーマットされるまで、ドライバーは受信した I/O 要求を完了してはなりません。 (WdfIoTargetSendInternalIoctlSynchronously メモリ オブジェクトの参照カウントをインクリメントします。要求オブジェクトを削除、再利用、または再フォーマットすると、メモリ オブジェクトの参照カウントがデクリメントされます)。

   • MDL を指定します。

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

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

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

例

次のコード例では、ローカル バッファーを定義し、WDF_MEMORY_DESCRIPTOR 構造体を初期化し、WdfIoTargetSendInternalIoctlSynchronously呼び出します。 この例では、要求オブジェクト ハンドル NULL を指定するため、フレームワークは I/O ターゲットの新しい要求オブジェクトを作成します。

WDF_MEMORY_DESCRIPTOR  outputDescriptor;
NTSTATUS  status;
MY_DRIVER_INFORMATION  driverInformation;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &outputDescriptor,
                                  (PVOID) &driverInformation,
                                  sizeof(MY_DRIVER_INFORMATION)
                                  );

status = WdfIoTargetSendInternalIoctlSynchronously(
                                                   hidTarget,
                                                   NULL,
                                                   IOCTL_INTERNAL_GET_MY_DRIVER_INFORMATION,
                                                   NULL,
                                                   &outputDescriptor,
                                                   NULL,
                                                   NULL
                                                   );

必要条件

関連項目

EvtDriverDeviceAdd の

WDF_MEMORY_DESCRIPTOR

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget の

WdfIoTargetCreate の

WdfIoTargetFormatRequestForInternalIoctl

WdfIoTargetSendIoctlSynchronously を する

WdfMemoryCreate

WdfMemoryCreatePreallocated の

WdfRequestCancelSentRequest

WdfRequestCompleteWithInformation の

WdfRequestCreate

WdfRequestRetrieveInputMemory

WdfRequestRetrieveInputWdmMdl

WdfRequestRetrieveOutputMemory

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse

WdfRequestSend