Função ExRegisterCallback (wdm.h)

Artigo
03/08/2023

A rotina ExRegisterCallback registra uma determinada rotina de retorno de chamada com um determinado objeto de retorno de chamada.

Sintaxe

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

Parâmetros

[in, out] CallbackObject

Um ponteiro para um objeto de retorno de chamada obtido da rotina ExCreateCallback .

[in] CallbackFunction

Um ponteiro para uma rotina de retorno de chamada implementada pelo driver, que deve ser inpálida. A rotina de retorno de chamada deve estar em conformidade com o seguinte protótipo:

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

Os parâmetros de rotina de retorno de chamada são os seguintes:

CallbackContext

Um ponteiro para uma área de contexto fornecida pelo driver, conforme especificado no parâmetro CallbackContext de ExRegisterCallback.

Argument1

Um ponteiro para um parâmetro definido pelo objeto de retorno de chamada.

Argumento2

Um ponteiro para um parâmetro definido pelo objeto de retorno de chamada.

[in, optional] CallbackContext

Um ponteiro para uma estrutura definida pelo chamador de itens de dados a ser passada como o parâmetro de contexto da rotina de retorno de chamada sempre que for chamada. Normalmente, o contexto faz parte da extensão de objeto do dispositivo do chamador.

Retornar valor

ExRegisterCallback retorna um ponteiro para um identificador de registro de retorno de chamada que deve ser tratado como opaco e reservado para uso do sistema. Esse ponteiro será NULL se ExRegisterCallback for concluído com um erro.

Comentários

Um driver chama ExRegisterCallback para registrar uma rotina de retorno de chamada com um objeto de retorno de chamada especificado.

Se o objeto permitir apenas uma rotina de retorno de chamada registrada e essa rotina já estiver registrada, ExRegisterCallback retornará NULL.

Os chamadores de ExRegisterCallback devem salvar o ponteiro retornado para uso posteriormente em uma chamada para ExUnregisterCallback. O ponteiro é necessário ao remover a rotina de retorno de chamada da lista de rotinas de retorno de chamada registradas para o objeto de retorno de chamada.

Os significados de Argument1 e Argument2 da rotina de retorno de chamada registrado dependem do objeto de retorno de chamada e são definidos pelo componente que o criou. Veja a seguir os parâmetros para os objetos de retorno de chamada definidos pelo sistema:

\Callback\SetSystemTime

Argument1 (SetSystemTime)

Não usado.

Argument2 (SetSystemTime)

Não usado.

\Callback\PowerState**

Argument1 (PowerState)

Um valor constante PO_CB_XXX que é convertido no tipo PVOID.
PO_CB_AC_STATUS — Indica que o sistema mudou de A/C para energia da bateria ou vice-versa.
PO_CB_LID_SWITCH_STATE — indica que a opção de tampa alterou os estados.
PO_CB_PROCESSOR_POWER_POLICY — Indica que a política de energia do processador do sistema foi alterada.
PO_CB_SYSTEM_POWER_POLICY — indica que a política de energia do sistema foi alterada.
PO_CB_SYSTEM_STATE_LOCK — Indica que uma alteração de estado de energia do sistema é iminente. Os drivers no caminho de paginação podem se registrar para que esse retorno de chamada receba um aviso antecipado de tal alteração, permitindo-lhes a oportunidade de bloquear o código na memória antes que o estado de energia seja alterado.

Argument2 (PowerState)

Um valor TRUE ou FALSE que é convertido no tipo PVOID.

Se Argument1 for PO_CB_AC_STATUS, Argument2 será TRUE se o computador estiver usando uma fonte de alimentação A/C e for FALSE se o computador estiver em execução com a energia da bateria.
Se Argument1 for PO_CB_LID_SWITCH_STATE, Argument2 será TRUE se a tampa estiver aberta no momento e for FALSE se a tampa estiver fechada.
Se Argument1 for PO_CB_PROCESSOR_POWER_POLICY, Argument2 não será usado.
Se Argument1 for PO_CB_SYSTEM_POWER_POLICY, Argument2 não será usado.
Se Argument1 for PO_CB_SYSTEM_STATE_LOCK, Argument2 será FALSE se o computador estiver prestes a sair do estado de energia do sistema S0 e for TRUE se o computador tiver apenas reentrado S0.

\Callback\ProcessorAdd

Argument1 (ProcessorAdd)

Um ponteiro para uma estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que descreve o evento de notificação de alteração do processador. Esse ponteiro é convertido para o tipo PVOID. A rotina de retorno de chamada não deve modificar o conteúdo dessa estrutura.

Argument2 (ProcessorAdd)

Um ponteiro para uma variável que contém um valor NTSTATUS. Esse ponteiro é convertido para o tipo PVOID. Em determinadas condições, uma rotina de retorno de chamada pode gravar um erro status valor nessa variável para indicar por que o novo processador não deve ser adicionado. Um driver de dispositivo não deve alterar o valor dessa variável, a menos que todas as três condições a seguir sejam verdadeiras:

Ocorre um erro durante o processamento da rotina de retorno de chamada que deve impedir que o novo processador seja adicionado.
O valor do membro State da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT para a qual Argument1 aponta é KeProcessorAddStartNotify.
A variável NSTATUS para a qual Argument2 aponta contém o valor STATUS_SUCCESS. Ou seja, a rotina de retorno de chamada não deve substituir um erro status valor que foi gravado anteriormente por outro cliente de notificação de retorno de chamada.

A partir do Windows Vista, o objeto de retorno de chamada \Callback\ProcessorAdd está disponível para acompanhar dinamicamente as alterações na população do processador. A rotina KeRegisterProcessorChangeCallback fornece informações semelhantes, mas também dá suporte a um sinalizador KE_PROCESSOR_CHANGE_ADD_EXISTING que um driver pode usar para enumerar os processadores na configuração inicial do sistema multiprocessador. Para drivers executados no Windows Server 2008 e versões posteriores do Windows, use KeRegisterProcessorChangeCallback em vez do objeto de retorno de chamada \Callback\ProcessorAdd , se possível.

Para obter mais informações sobre objetos de retorno de chamada, consulte Objetos de retorno de chamada.

O sistema operacional chama rotinas de retorno de chamada registradas no mesmo IRQL em que o driver que criou o retorno de chamada chamado rotina ExNotifyCallback .

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm)