Função ExRegisterCallback (wdm.h)
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.
Argument2
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 serem passados como o parâmetro de contexto da rotina de retorno de chamada sempre que ele for chamado. Normalmente, o contexto faz parte da extensão de objeto do dispositivo do chamador.
Valor de retorno
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.
Observações
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 do 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 registrada dependem do objeto de retorno de chamada e são definidos pelo componente que o criou. A seguir estão 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 PO_CB_XXX constante que é convertido para digitar 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 seu código na memória antes que o estado de energia mude.
Argument2 (PowerState)
Um valor de TRUE ou FALSE que é convertido no tipo PVOID.
Se argument1 for PO_CB_AC_STATUS, argument2 será VERDADEIRO se o computador estiver usando uma fonte de alimentação A/C no momento e estiver FALSE se o computador estiver em execução na energia da bateria.
Se Argument1 for PO_CB_LID_SWITCH_STATE, argument2 será VERDADEIRO se a tampa estiver aberta no momento e estiver 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 estiver VERDADEIRO se o computador tiver apenas reentrado S0.
\Callback\ProcessorAdd
Argument1 (ProcessorAdd)
- Um ponteiro para uma estrutura de KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT que descreve o evento de notificação de alteração do processador. Esse ponteiro é convertido para digitar 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 digitar PVOID. Em determinadas condições, uma rotina de retorno de chamada pode gravar um valor de status de erro 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 de Estado da estrutura KE_PROCESSOR_CHANGE_NOTIFY_CONTEXT à qual Argument1 aponta é KeProcessorAddStartNotify.
A variável NSTATUS que Argument2 aponta para conter o valor STATUS_SUCCESS. Ou seja, a rotina de retorno de chamada não deve substituir um valor de status de erro que foi gravado anteriormente por outro cliente de notificação de retorno de chamada.
A partir do Windows Vista, o \Callback\ProcessorAdd objeto de retorno de chamada 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 de 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 \Callback\ProcessorAdd objeto de retorno de chamada, 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 no qual o driver que criou o retorno de chamada chamado rotina ExNotifyCallback.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm) |