IoGetDeviceObjectPointer 関数 (wdm.h)

[アーティクル]
03/05/2024

IoGetDeviceObjectPointer ルーチンは、オブジェクトへの要求されたアクセスを許可できる場合、名前付きデバイスオブジェクトのスタック内の最上位オブジェクトへのポインターと、対応するファイルオブジェクトへのポインターを返します。

構文

NTSTATUS IoGetDeviceObjectPointer(
  [in]  PUNICODE_STRING ObjectName,
  [in]  ACCESS_MASK     DesiredAccess,
  [out] PFILE_OBJECT    *FileObject,
  [out] PDEVICE_OBJECT  *DeviceObject
);

パラメーター

[in] ObjectName

デバイスオブジェクトの名前である Unicode 文字列を含むバッファーへのポインター。

[in] DesiredAccess

目的のアクセスを表す ACCESS_MASK 値を指定します。通常 、DesiredAccess はFILE_READ_DATA。まれに、FILE_WRITE_DATAまたはFILE_ALL_ACCESSアクセス権が指定されます。

[out] FileObject

呼び出しが成功した場合は、ユーザーモードコードへの対応するデバイスオブジェクトを表すファイルオブジェクトへのポインター。

[out] DeviceObject

呼び出しが成功した場合は、名前付きの論理、仮想、または物理デバイスを表すデバイスオブジェクトへのポインター。

戻り値

IoGetDeviceObjectPointer は、成功した場合STATUS_SUCCESSを返します。エラーの戻り値として考えられるのは、次の状態コードです。

STATUS_OBJECT_TYPE_MISMATCH

STATUS_INVALID_PARAMETER

STATUS_PRIVILEGE_NOT_HELD

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_INVALID

注釈

IoGetDeviceObjectPointer は 、呼び出し元と次の下位レベルのドライバーの間に "接続" を確立します。正常な呼び出し元は、返されたデバイスオブジェクトポインターを使用して、独自のデバイスオブジェクトを初期化できます。また、 IoAttachDeviceToDeviceStack、 IoCallDriver、および下位ドライバー用の IRP を作成する任意のルーチンの引数として使用することもできます。返されるポインターは、 IoCallDriver に必要な引数です。

このルーチンは、対応するファイルオブジェクトへのポインターも返します。アンロード時に、ドライバーは、デバイスオブジェクトを間接的に逆参照する手段としてファイルオブジェクトを逆参照できます。これを行うために、ドライバーは Unload ルーチンから ObDereferenceObject を呼び出し、 IoGetDeviceObjectPointer によって返されるファイルオブジェクトポインターを渡します。ドライバーの Unload ルーチンでデバイスオブジェクトを逆参照できないと、次の下位ドライバーがアンロードされなくなります。ただし、アンロードプロセスの前にファイルオブジェクトを閉じるドライバーは、ファイルオブジェクトを逆参照する前に、デバイスオブジェクトに対して追加の参照を取り出す必要があります。そうしないと、ファイルオブジェクトを逆参照すると、デバイスオブジェクトが早期に削除される可能性があります。

ファイルシステムドライバースタックの最上位レベルのドライバーへのポインターを取得するには、ドライバーがファイルシステムがマウントされていることを確認する必要があります。そうでない場合、このルーチンはストレージデバイススタックを走査します。ファイルシステムがストレージデバイスに確実にマウントされるようにするには、ドライバーで DesiredAccess パラメーターに適切なアクセスマスク (FILE_READ_DATAやFILE_WRITE_ATTRIBUTESなど) を指定する必要があります。 FILE_READ_ATTRIBUTESを指定しても、ファイルシステムはマウントされません。

このルーチンを正常に呼び出すことによって、上位レベルのドライバーが別のドライバーにチェーンされた後、上位レベルのドライバーは、そのデバイスオブジェクトの StackSize フィールドを、次の下位レベルのドライバーのデバイスオブジェクトに 1 を加えたものに設定する必要があります。

IoGetDeviceObjectPointer の呼び出し元は、IRQL = PASSIVE_LEVELで実行されている必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm)