Función ExRegisterCallback (wdm.h)

Artículo
02/27/2024

La rutina ExRegisterCallback registra una rutina de devolución de llamada determinada con un objeto de devolución de llamada determinado.

Sintaxis

PVOID ExRegisterCallback(
  [in, out]      PCALLBACK_OBJECT   CallbackObject,
  [in]           PCALLBACK_FUNCTION CallbackFunction,
  [in, optional] PVOID              CallbackContext
);

Parámetros

[in, out] CallbackObject

Puntero a un objeto de devolución de llamada obtenido de la rutina ExCreateCallback .

[in] CallbackFunction

Puntero a una rutina de devolución de llamada implementada por el controlador, que debe ser no paginable. La rutina de devolución de llamada debe ajustarse al prototipo siguiente:

VOID
(*PCALLBACK_FUNCTION ) (
    IN PVOID CallbackContext,
    IN PVOID Argument1,
    IN PVOID Argument2
    );

Los parámetros de rutina de devolución de llamada son los siguientes:

CallbackContext

Puntero a un área de contexto proporcionada por el controlador como se especifica en el parámetro CallbackContext de ExRegisterCallback.

Argument1

Puntero a un parámetro definido por el objeto de devolución de llamada.

Argument2

Puntero a un parámetro definido por el objeto de devolución de llamada.

[in, optional] CallbackContext

Puntero a una estructura definida por el autor de la llamada de los elementos de datos que se van a pasar como parámetro de contexto de la rutina de devolución de llamada cada vez que se llama. Normalmente, el contexto forma parte de la extensión de objeto de dispositivo del autor de la llamada.

Valor devuelto

ExRegisterCallback devuelve un puntero a un identificador de registro de devolución de llamada que se debe tratar como opaco y reservado para el uso del sistema. Este puntero es NULL si ExRegisterCallback se completa con un error.

Comentarios

Un controlador llama a ExRegisterCallback para registrar una rutina de devolución de llamada con un objeto de devolución de llamada especificado.

Si el objeto solo permite una rutina de devolución de llamada registrada y dicha rutina ya está registrada, ExRegisterCallback devuelve NULL.

Los autores de llamadas de ExRegisterCallback deben guardar el puntero devuelto para usarlo más adelante en una llamada a ExUnregisterCallback. El puntero es necesario al quitar la rutina de devolución de llamada de la lista de rutinas de devolución de llamada registradas para el objeto de devolución de llamada.

Los significados de Argument1 y Argument2 de la rutina de devolución de llamada registrada dependen del objeto de devolución de llamada y se definen mediante el componente que lo creó. Estos son los parámetros de los objetos de devolución de llamada definidos por el sistema:

\Callback\SetSystemTime

Argument1 (SetSystemTime)

No se usa.

Argument2 (SetSystemTime)

No se usa.

\Callback\PowerState**

Argument1 (PowerState)

Valor constante PO_CB_XXX que se convierte al tipo PVOID.
PO_CB_AC_STATUS: indica que el sistema ha cambiado de A/C a energía de batería, o viceversa.
PO_CB_LID_SWITCH_STATE: indica que el conmutador de tapa ha cambiado de estado.
PO_CB_PROCESSOR_POWER_POLICY: indica que la directiva de potencia del procesador del sistema ha cambiado.
PO_CB_SYSTEM_POWER_POLICY: indica que la directiva de energía del sistema ha cambiado.
PO_CB_SYSTEM_STATE_LOCK: indica que un cambio de estado de energía del sistema es inminente. Los controladores de la ruta de acceso de paginación pueden registrarse para que esta devolución de llamada reciba una advertencia temprana de este cambio, lo que les permite bloquear su código en la memoria antes de que cambie el estado de energía.

Argument2 (PowerState)

Valor de TRUE o FALSE que se convierte al tipo PVOID.

Si Argument1 es PO_CB_AC_STATUS, Argument2 es TRUE si el equipo usa actualmente una fuente de alimentación A/C y es FALSE si el equipo se está ejecutando con batería.
Si Argument1 es PO_CB_LID_SWITCH_STATE, Argument2 es TRUE si la tapa está abierta actualmente y es FALSE si la tapa está cerrada.
Si Argument1 es PO_CB_PROCESSOR_POWER_POLICY, no se usa Argument2 .
Si Argument1 es PO_CB_SYSTEM_POWER_POLICY, no se usa Argument2 .
Si Argument1 es PO_CB_SYSTEM_STATE_LOCK, Argument2 es FALSE si el equipo está a punto de salir del estado de alimentación del sistema S0 y es TRUE si el equipo acaba de volver a escribir S0.

\Callback\ProcessorAdd

Argument1 (ProcessorAdd)

Puntero a una estructura de KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que describe el evento de notificación de cambio del procesador. Este puntero se convierte en el tipo PVOID. La rutina de devolución de llamada no debe modificar el contenido de esta estructura.

Argument2 (ProcessorAdd)

Puntero a una variable que contiene un valor NTSTATUS. Este puntero se convierte en el tipo PVOID. En determinadas condiciones, una rutina de devolución de llamada puede escribir un valor de estado de error en esta variable para indicar por qué no se debe agregar el nuevo procesador. Un controlador de dispositivo no debe cambiar el valor de esta variable a menos que se cumplan las tres condiciones siguientes:

Se produce un error durante el procesamiento de la rutina de devolución de llamada que debe impedir que se agregue el nuevo procesador.
El valor del miembro State de la estructura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT a la que Apunta Argument1 es KeProcessorAddStartNotify.
La variable NSTATUS a la que Argument2 apunta contiene el valor STATUS_SUCCESS. Es decir, la rutina de devolución de llamada no debe sobrescribir un valor de estado de error escrito previamente por otro cliente de notificación de devolución de llamada.

A partir de Windows Vista, el objeto \Callback\ProcessorAdd callback está disponible para realizar un seguimiento dinámico de los cambios en el rellenado del procesador. La rutina KeRegisterProcessorChangeCallback proporciona información similar, pero además admite una marca de KE_PROCESSOR_CHANGE_ADD_EXISTING que un controlador puede usar para enumerar los procesadores en la configuración inicial del sistema multiprocesador. Para los controladores que se ejecutan en Windows Server 2008 y versiones posteriores de Windows, use KeRegisterProcessorChangeCallback en lugar del objeto de devolución de llamada \Callback\ProcessorAdd , si es posible.

Para obtener más información sobre los objetos de devolución de llamada, vea Objetos de devolución de llamada.

El sistema operativo llama a las rutinas de devolución de llamada registradas en el mismo IRQL en el que el controlador que creó la devolución de llamada denominada rutina ExNotifyCallback .

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm)