PO_FX_POWER_CONTROL_CALLBACK função de retorno de chamada (wdm.h)
A rotina de retorno de chamada PowerControlCallback executa uma operação de controle de energia solicitada pela PoFx (estrutura de gerenciamento de energia).
Sintaxe
PO_FX_POWER_CONTROL_CALLBACK PoFxPowerControlCallback;
NTSTATUS PoFxPowerControlCallback(
PVOID DeviceContext,
[in] LPCGUID PowerControlCode,
[in, optional] PVOID InBuffer,
[in] SIZE_T InBufferSize,
[out, optional] PVOID OutBuffer,
[in] SIZE_T OutBufferSize,
[out, optional] PSIZE_T BytesReturned
)
{...}
Parâmetros
DeviceContext
[in] PowerControlCode
Um ponteiro para o código de controle de energia. Esse código é um valor GUID que especifica a operação solicitada.
[in, optional] InBuffer
Um ponteiro para o buffer que contém os dados de entrada para a operação. O formato dos dados nesse buffer depende do código de controle de energia especificado pelo parâmetro PowerControlCode . O parâmetro InBuffer é opcional e pode ser especificado como NULL se a operação especificada não exigir dados de entrada.
[in] InBufferSize
O tamanho, em bytes, do buffer de entrada apontado pelo parâmetro InBuffer . Se InBuffer for NULL, esse parâmetro será zero.
[out, optional] OutBuffer
Um ponteiro para o buffer no qual a rotina de retorno de chamada grava os dados de saída da operação. O formato dos dados nesse buffer depende do código de controle de energia especificado pelo parâmetro PowerControlCode . O parâmetro OutBuffer é opcional e pode ser especificado como NULL se a operação especificada não produzir dados de saída.
[in] OutBufferSize
O tamanho, em bytes, do buffer de saída apontado pelo parâmetro OutBuffer . Se OutBuffer for NULL, esse parâmetro será zero.
[out, optional] BytesReturned
Um ponteiro para um local no qual a rotina grava o número de bytes de dados que foram gravados no buffer apontado pelo OutBuffer. O número de bytes gravados deve ser menor ou igual a OutBufferSize. Esse parâmetro é opcional e pode ser especificado como NULL se o chamador não precisar saber quantos bytes foram gravados no buffer de saída.
Retornar valor
A rotina PowerControlCallback retornará STATUS_SUCCESS se a chamada for bem-sucedida. Caso contrário, ele retornará um código de erro apropriado.
Comentários
A PoFx chama essa rotina para enviar uma solicitação de controle de energia diretamente para o driver do dispositivo. Uma solicitação de controle de energia é semelhante a uma IOCTL (solicitação de controle de E/S). Ao contrário de um IOCTL, no entanto, uma solicitação de controle de energia é enviada diretamente ao driver e não é observada por outros drivers de dispositivo na pilha do dispositivo. Durante uma chamada de PowerControlCallback , o driver executa a operação solicitada de forma síncrona.
Essa rotina é opcional. Um driver de dispositivo que não dá suporte a operações de controle de energia não é necessário para implementar uma rotina PowerControlCallback .
O driver do dispositivo pode chamar a rotina PoFxPowerControl para enviar uma solicitação de controle de energia para PoFx.
Para obter mais informações sobre solicitações de controle de energia, consulte PoFxPowerControl.
Exemplos
Para definir uma rotina de retorno de chamada powerControlCallback , primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina 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 escrever drivers para o sistema operacional Windows.
Por exemplo, para definir uma rotina de retorno de chamada PowerControlCallback chamada MyPowerControlCallback, use o tipo PO_FX_POWER_CONTROL_CALLBACK conforme mostrado neste exemplo de código:
PO_FX_POWER_CONTROL_CALLBACK MyPowerControlCallback;
Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
NTSTATUS
MyPowerControlCallback(
PVOID Context,
LPCGUID PowerControlCode,
PVOID InBuffer,
SIZE_T InBufferSize,
PVOID OutBuffer,
SIZE_T OutBufferSize,
PSIZE_T BytesReturned
)
{
// Function body
}
O tipo de função PO_FX_POWER_CONTROL_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 _Use_decl_annotations_ anotação à sua definição de função. A _Use_decl_annotations_ anotação garante que as anotações aplicadas ao tipo de função PO_FX_POWER_CONTROL_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 | Com suporte a partir do Windows 8. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | wdm.h (include Wudfwdm.h) |
| IRQL | Chamado em IRQL <= DISPATCH_LEVEL. |