Macro ObReferenceObjectWithTag (wdm.h)

La rutina ObReferenceObjectWithTag 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

void ObReferenceObjectWithTag(
  [in]  Object,
  [in]  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] 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

None

Observaciones

ObReferenceObjectWithTag devuelve un valor reservado para el uso del sistema. Los controladores deben tratar este valor como VOID.

ObReferenceObjectWithTag simplemente incrementa el recuento de referencias de puntero para un objeto, sin realizar comprobaciones de acceso en el objeto especificado. Por el contrario, las rutinas ObReferenceObjectByHandleWithTag y ObReferenceObjectByPointerWithTag comprueban que el autor de la llamada tiene los derechos de acceso necesarios para el objeto y producen un error si el autor de la llamada no tiene estos derechos.

Una llamada ObReferenceObjectWithTag impide la eliminación del objeto especificado al menos hasta que el controlador llame a la rutina ObDereferenceObjectWithTag o cierre el objeto. Una vez que el objeto ya no sea necesario, el controlador debe llamar a ObDereferenceObjectWithTag para quitar su referencia al objeto .

Cuando el recuento de referencias de un objeto alcanza cero, un componente en modo kernel puede eliminar el objeto. Sin embargo, un controlador solo puede eliminar los objetos que creó y un controlador nunca debe intentar eliminar ningún objeto que no haya creado.

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

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

Para ver un seguimiento de referencia de objeto en las herramientas de depuración de Windows, use la extensión !obtrace kernel-mode debugger. 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 global de marcas (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	Escritorio
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	HwStorPortProhibitedDIs(storport)

Consulte también

ObDereferenceObjectWithTag

ObReferenceObject

ObReferenceObjectByHandleWithTag

ObReferenceObjectByPointerWithTag