Macro ObDereferenceObjectWithTag (wdm.h)
La rutina ObDereferenceObjectWithTag disminuye 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 ObDereferenceObjectWithTag(
[in] a,
[in] t
);
Parámetros
[in] a
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] t
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
ObDereferenceObjectWithTag devuelve un valor reservado para el uso del sistema. Los controladores deben tratar este valor como VOID.
Un controlador en modo kernel llama a esta rutina para disminuir el recuento de referencias de un objeto por uno. Si el objeto se creó como temporal (es decir, la marca de OBJ_PERMANENT no se especificó cuando se creó el objeto) y el recuento de referencias alcanza cero, el administrador de objetos elimina el 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.
Un objeto es permanente si se creó con la marca de atributo de objeto OBJ_PERMANENT especificada. (Para obtener más información sobre los atributos de objeto, vea InitializeObjectAttributes). Se crea un objeto permanente con un recuento de referencias inicial de uno, por lo que el objeto no se elimina cuando el controlador quita su última referencia al objeto .
Para preparar un objeto permanente que se va a eliminar, un controlador puede llamar a la rutina ZwMakeTemporaryObject para que el objeto sea temporal. Un controlador solo debe eliminar un objeto permanente que creó. Siga estos pasos para eliminar un objeto permanente:
Llame a ObDereferenceObjectWithTag.
Obtenga el identificador del objeto . Si es necesario, llame a la rutina ZwOpenXxx o ZwCreateXxx adecuada para obtener el identificador del objeto.
Llame a ZwMakeTemporaryObject con el identificador obtenido en el paso 2.
Llame a ZwClose con el identificador obtenido en el paso 2.
Si la eliminación inmediata de un objeto por el subproceso actual puede provocar un interbloqueo, no llame a ObDereferenceObjectWithTag para desreferenciar el objeto. En su lugar, llame a la rutina ObDereferenceObjectDeferDeleteWithTag para desreferenciar el objeto.
Por ejemplo, este interbloqueo puede producirse si ObDereferenceObjectWithTag se usa para desreferenciar un objeto administrador de transacciones de kernel (KTM) cuando un controlador de nivel superior de la pila de controladores mantiene un bloqueo.
Para obtener más información sobre las referencias a objetos, vea Ciclo de vida de un objeto.
La rutina ObDereferenceObject es similar a ObDereferenceObjectWithTag, salvo que no permite al autor de la llamada escribir una etiqueta personalizada en un objeto. En Windows 7 y versiones posteriores de Windows, ObDereferenceObject siempre escribe un valor de etiqueta predeterminado ('tlfD') en el objeto . Una llamada a ObDereferenceObject tiene el mismo efecto que una llamada a ObDereferenceObjectWithTag 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
ObDereferenceObjectDeferDeleteWithTag