ObReferenceObjectByHandleWithTag 関数 (wdm.h)

ObReferenceObjectByHandleWithTag ルーチンは、指定されたハンドルによって識別されるオブジェクトの参照カウントをインクリメントし、オブジェクト参照トレースをサポートするために 4 バイトのタグ値を オブジェクトに書き込みます。

構文

NTSTATUS ObReferenceObjectByHandleWithTag(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [in]            ULONG                      Tag,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

パラメーター

[in] Handle

オブジェクトの開いているハンドルを指定します。

[in] DesiredAccess

呼び出し元が要求するオブジェクトへのアクセスの種類を指定します。 このパラメーターは、 ACCESS_MASK型のビットマスクです。 このフィールドの解釈は、オブジェクトの種類によって異なります。 汎用アクセス権は使用しないでください。

[in, optional] ObjectType

オブジェクト型を指定する不透明な構造体へのポインター。 このパラメーターは 、OBJECT_TYPE 構造体を指します。 ObjectType を NULL に設定するか、Wdm.h ヘッダー ファイルで宣言されているポインター値 (*ExEventObjectType、*ExSemaphoreObjectType、*IoFileObjectType、*PsProcessType、*PsThreadType、*SeTokenObjectType、*TmEnlistmentObjectType、*TmResourceManagerObjectType、*TmTransactionManagerObjectType、または *TmTransactionObjectType) のいずれかに設定します。 ObjectType が NULL でない場合、ルーチンは、指定されたオブジェクト型が Handle パラメーターで指定されたオブジェクトのオブジェクト型と一致することを確認します。

[in] AccessMode

アクセス チェックに使用するアクセス モードを指定します。 UserMode または KernelMode のいずれかである必要があります。 ドライバーでは、ユーザー アドレス空間から受け取るハンドルに対して常に UserMode を指定する必要があります。

[in] Tag

4 バイトのカスタム タグ値を指定します。 詳細については、「解説」を参照してください。

[out] Object

ルーチンがオブジェクトへのポインターを書き込む変数へのポインター。 次の表に、使用可能な ObjectType パラメーター値によって指定される Object ポインター型の一覧を示します。

ポインター型が参照する構造体は不透明であり、ドライバーは構造体メンバーにアクセスできません。 構造体は不透明であるため、PEPROCESS は PKPROCESS に相当し、PETHREAD は PKTHREAD と同等です。

[out, optional] HandleInformation

ドライバーは、このパラメーターを NULL に設定 します。

戻り値

呼び出しが成功した場合、ObReferenceObjectByHandleWithTag はSTATUS_SUCCESSを返します。 エラーの戻り値として考えられるのは、次のとおりです。

注釈

このルーチンは、指定されたオブジェクト ハンドルの検証にアクセスします。 アクセスを許可できる場合、ルーチンはオブジェクト参照カウントをインクリメントし、呼び出し元へのオブジェクト ポインターを提供します。 この増分により、呼び出し元が オブジェクトを使用している間、オブジェクトが削除されなくなります。 オブジェクトが不要になったら、呼び出し元は ObDereferenceObjectWithTag ルーチンまたは ObDereferenceObjectDeferDeleteWithTag ルーチンを呼び出して、参照カウントをデクリメントする必要があります。

オブジェクト参照の詳細については、「 オブジェクトのライフ サイクル」を参照してください。

ObReferenceObjectByHandleWithTag は、 Handle パラメーターで指定されたオブジェクト ハンドルを閉じるか無効にしません。 ハンドルが不要になった場合、呼び出し元は ZwClose ルーチンを呼び出すことによってハンドルを閉じることができます。

AccessMode パラメーター値が KernelMode の場合、要求されたアクセスは常に許可されます。 AccessMode が UserMode の場合、要求されたアクセス権は、呼び出し元がオブジェクトに対して持っているアクセス権と比較されます。 AccessMode パラメーターの UserMode 値を安全に指定できるのは、最上位レベルのドライバーのみです。

Windows 7 以降、 AccessMode が KernelMode で、ユーザー アドレス空間からハンドルが受信された場合、 ドライバー検証ツール はバグチェック C4、サブコード F6 を発行します。

ObReferenceObjectByHandle ルーチンは ObReferenceObjectByHandleWithTag に似ていますが、呼び出し元がオブジェクトにカスタム タグを書き込むのを許可しない点が例外です。 Windows 7 以降のバージョンの Windows では、 ObReferenceObjectByHandle は常に既定のタグ値 ('tlfD') を オブジェクトに書き込みます。 ObReferenceObjectByHandle の呼び出しは、Tag = 'tlfD' を指定する ObReferenceObjectByHandleWithTag の呼び出しと同じ効果があります。

Windows デバッグ ツールでオブジェクト参照トレースを表示するには、!obtrace カーネル モード デバッガー拡張機能を使用します。 オブジェクト参照トレースが有効になっている場合は、 !obtrace 拡張機能が拡張され、オブジェクト参照タグが表示されます。 既定では、オブジェクト参照トレースはオフになっています。 オブジェクト参照トレースを有効にするには、 グローバル フラグ エディター (Gflags) を使用します。 詳細については、「 タグを使用したオブジェクト参照トレース」を参照してください。

要件

こちらもご覧ください

ACCESS_MASK

OBJECT_TYPE

ObDereferenceObjectDeferDeleteWithTag

ObDereferenceObjectWithTag

ObReferenceObjectByHandle

ZwClose