Função PoRegisterPowerSettingCallback (ntifs.h)
A rotina PoRegisterPowerSettingCallback registra uma rotina de retorno de chamada de configuração de energia para receber notificações de alterações na configuração de energia especificada.
Sintaxe
NTSTATUS PoRegisterPowerSettingCallback(
[in, optional] PDEVICE_OBJECT DeviceObject,
[in] LPCGUID SettingGuid,
[in] PPOWER_SETTING_CALLBACK Callback,
[in, optional] PVOID Context,
[out] PVOID *Handle
);
Parâmetros
[in, optional] DeviceObject
Um ponteiro para uma estrutura de DEVICE_OBJECT associada ao chamador dessa rotina. Esse parâmetro é opcional. Ele é usado internamente apenas para fins de depuração. Se esse parâmetro não for fornecido, ele deverá ser definido como NULL.
[in] SettingGuid
Um ponteiro para o GUID que representa a configuração de energia para esse registro. Quando a configuração de energia especificada for alterada, o power manager chamará a rotina de retorno de chamada para notificar o driver da alteração e fornecer o novo valor da configuração. Para obter mais informações, consulte Comentários.
[in] Callback
Um ponteiro para uma rotina de retorno de chamada de configuração de energia implementada pelo chamador que o power manager chama quando a configuração de energia especificada é alterada. Para obter o protótipo funcional para a rotina de retorno de chamada, consulte Retorno de chamada de configuração de energia, abaixo.
[in, optional] Context
Um ponteiro para o contexto da rotina de retorno de chamada. Esse parâmetro é opcional. Ele é fornecido para que um contexto de driver ou dispositivo possa ser passado para a rotina de retorno de chamada. Se esse parâmetro não for usado, ele deverá ser definido como NULL.
[out] Handle
Um identificador que o power manager usa para representar a rotina de retorno de chamada. Um driver deve fornecer posteriormente esse identificador em uma chamada para PoUnregisterPowerSettingCallback para cancelar o registro da rotina de retorno de chamada.
Retornar valor
PoRegisterPowerSettingCallback retorna um dos seguintes:
| Código de retorno | Descrição |
|---|---|
| STATUS_SUCCESS | A rotina registrou a rotina de retorno de chamada. |
| STATUS_ INSUFFICIENT_RESOURCES | A rotina não pôde alocar os recursos do sistema necessários para registrar a rotina de retorno de chamada. |
Comentários
Um driver chama PoRegisterPowerSettingCallback para registrar uma rotina de retorno de chamada com o power manager. Posteriormente, o power manager chama essa rotina de retorno de chamada para notificar o driver depois que houver uma alteração na configuração de energia especificada. Além disso, o power manager inicializa a configuração de energia do driver chamando imediatamente a rotina de retorno de chamada e passando o valor atual da configuração de energia. O power manager inicializa a configuração de energia do driver dessa maneira, independentemente de a configuração de energia ter sido realmente alterada.
Um driver deve chamar PoRegisterPowerSettingCallback para cada configuração de energia que o driver precisa monitorar. Os motoristas devem chamar essa rotina em sua rotina driverEntry durante a inicialização. Normalmente, a maioria dos drivers passa um ponteiro para uma extensão de dispositivo no parâmetro Context .
Para cancelar o registro de um retorno de chamada de configuração de energia, chame a rotina PoUnregisterPowerSettingCallback .
Normalmente, Kernel-Mode drivers KMDF (Driver Framework) devem chamar PoRegisterPowerSettingCallback de sua função de retorno de chamada EvtDeviceSelfManagedIoInit e devem chamar PoUnregisterPowerSettingCallback de sua função de retorno de chamada EvtDeviceSelfManagedIoCleanup . Esses drivers não devem chamar PoRegisterPowerSettingCallback de sua função de retorno de chamada EvtDriverDeviceAdd ; caso contrário, a rotina de retorno de chamada de configuração de energia pode ser chamada antes que a pilha de driver seja completamente criada.
A rotina de retorno de chamada registrada para uma configuração de energia específica é chamada quando ocorre uma transição no estado de energia que altera o valor da configuração ou quando o power manager altera o valor da configuração. Por exemplo, se SettingGuid apontar para o valor guid GUID_LIDSWITCH_STATE_CHANGE, a rotina de retorno de chamada será chamada quando a tampa de um computador laptop clicar em abrir ou fechar. O parâmetro Value passado para a rotina de retorno de chamada neste exemplo aponta para um valor ULONG que é 1 se o estado da opção de tampa foi alterado de fechado para aberto e será 0 se o estado da opção de tampa for alterado de aberto para fechado. Para obter mais informações, consulte as definições de GUID de configuração de energia e comentários extensivos no arquivo de cabeçalho Wdm.h.
A chamada inicial para uma rotina de retorno de chamada pode ocorrer imediatamente, antes que a chamada PoRegisterPowerSettingCallback que registra a rotina retorne.
PoRegisterPowerSettingCallback só pode ser chamado em IRQL = PASSIVE_LEVEL.
Retorno de chamada Power-Setting
O protótipo de função da rotina de retorno de chamada de configuração de energia e seus parâmetros são os seguintes. O power manager chama um retorno de chamada de configuração de energia em IRQL = PASSIVE_LEVEL.
NTSTATUS
POWER_SETTING_CALLBACK (
_In_ LPCGUID SettingGuid,
_In_ PVOID Value,
_In_ ULONG ValueLength,
_Inout_opt_ PVOID Context
);
| Parâmetro | Descrição |
|---|---|
| SettingGuid | Um ponteiro para um GUID que representa a configuração de energia que foi alterada. As configurações de energia e seus GUIDs correspondentes são definidos em Wdm.h. |
| Valor | Um ponteiro para o novo valor da configuração de energia que foi alterada. |
| ValueLength | Um valor do tipo ULONG que especifica o tamanho, em bytes, do novo valor de configuração de energia. |
| Contexto | O ponteiro para o contexto que um driver forneceu na chamada para PoRegisterPowerSettingCallback que registrou a rotina de retorno de chamada. |
Exemplos
Para definir uma rotina de retorno de chamada de configuração de energia, primeiro você deve fornecer uma declaração de função que identifique o tipo de função de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.
Por exemplo, para definir uma rotina de retorno de chamada de configuração de energia chamada MyPowerSettingCallback, use o tipo POWER_SETTING_CALLBACK, conforme mostrado neste exemplo de código:
POWER_SETTING_CALLBACK MyPowerSettingCallback;
Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
NTSTATUS
MyPowerSettingCallback(
LPCGUID SettingGuid,
PVOID Value,
ULONG ValueLength,
PVOID Context
)
{
// Function body
}
O tipo de função POWER_SETTING_CALLBACK é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função POWER_SETTING_CALLBACK no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista |
| Plataforma de Destino | Universal |
| Cabeçalho | ntifs.h (inclui Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (consulte a seção Comentários) |