Función ObReferenceObjectByPointerWithTag (wdm.h)

Artículo
02/27/2024

La rutina ObReferenceObjectByPointerWithTag incrementa el recuento de referencias del objeto especificado y escribe un valor de etiqueta de cuatro bytes en el objeto para admitir el seguimiento de referencia de objetos.

Sintaxis

NTSTATUS ObReferenceObjectByPointerWithTag(
  [in]           PVOID           Object,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [in]           ULONG           Tag
);

Parámetros

[in] Object

Puntero al objeto . El autor de la llamada obtiene este puntero cuando crea el objeto o desde una llamada anterior a la rutina ObReferenceObjectByHandleWithTag después de abrir el objeto.

[in] DesiredAccess

Especifica los tipos de acceso al objeto que solicita el autor de la llamada. Este parámetro es una máscara de bits de tipo ACCESS_MASK. La interpretación de este campo depende del tipo de objeto. No use ningún derecho de acceso genérico.

[in, optional] ObjectType

Puntero a una estructura opaca que especifica el tipo de objeto. Este parámetro apunta a una estructura de OBJECT_TYPE . Establezca ObjectType en NULL o en uno de los siguientes valores de puntero, que se declaran en el archivo de encabezado Wdm.h: *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType o *TmTransactionObjectType. Este parámetro puede ser NULL si AccessMode es KernelMode. Si ObjectType no es NULL, la rutina comprueba que el tipo de objeto proporcionado coincide con el tipo de objeto del objeto que especifica el parámetro Handle .

[in] AccessMode

Indica el modo de acceso que se va a usar para la comprobación de acceso. Establezca este parámetro en uno de los siguientes valores de enumeración MODE :

UserMode
KernelMode

Los controladores de nivel inferior deben especificar KernelMode.

[in] Tag

Especifica un valor de etiqueta personalizada de cuatro bytes. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Valor devuelto

ObReferenceObjectByPointerWithTag devuelve STATUS_SUCCESS si la llamada es correcta. Entre los valores devueltos de error posibles se incluyen los siguientes:

Código devuelto	Descripción
STATUS_OBJECT_TYPE_MISMATCH	El parámetro ObjectType especifica el tipo de objeto incorrecto para el objeto al que apunta el parámetro Object o ObjectType es NULL , pero AccessMode es UserMode.

Comentarios

Esta rutina tiene acceso a la validación del objeto especificado. Si se puede conceder acceso, la rutina incrementa el recuento de referencias de objetos. Este incremento impide que el objeto se elimine mientras el autor de la llamada usa el objeto . Cuando el objeto ya no es necesario, el autor de la llamada debe disminuir el recuento de referencias llamando a la rutina ObDereferenceObjectWithTag o ObDereferenceObjectDeferDeleteWithTag .

Para obtener más información sobre las referencias a objetos, vea Ciclo de vida de un objeto.

La rutina ObReferenceObjectByPointer es similar a ObReferenceObjectByPointerWithTag, salvo que no permite al autor de la llamada escribir una etiqueta personalizada en un objeto. En Windows 7 y versiones posteriores de Windows, ObReferenceObjectByPointer siempre escribe un valor de etiqueta predeterminado ('tlfD') en el objeto. Una llamada a ObReferenceObjectByPointer tiene el mismo efecto que una llamada a ObReferenceObjectByPointerWithTag que especifica Tag = 'tlfD'.

Para ver un seguimiento de referencia de objetos en las herramientas de depuración de Windows, use la extensión del depurador de modo kernel-obtrace. En Windows 7, la extensión !obtrace se mejora para mostrar etiquetas de referencia de objetos, si está habilitado el seguimiento de referencia de objetos. De forma predeterminada, el seguimiento de referencia de objetos está desactivado. Use el Editor de marcas globales (Gflags) para habilitar el seguimiento de referencia de objetos. Para obtener más información, vea Seguimiento de referencia de objetos con etiquetas.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows 7 y versiones posteriores del sistema operativo Windows.
Plataforma de destino	Universal
Encabezado	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDDIs(storport)