IoGetDeviceObjectPointer 関数 (wdm.h)
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) |