Função PoRequestPowerIrp (wdm.h)
A rotina PoRequestPowerIrp aloca um IRP de energia e o envia para o driver superior na pilha de dispositivos para o dispositivo especificado.
Sintaxe
NTSTATUS PoRequestPowerIrp(
[in] PDEVICE_OBJECT DeviceObject,
[in] UCHAR MinorFunction,
[in] POWER_STATE PowerState,
[in, optional] PREQUEST_POWER_COMPLETE CompletionFunction,
[in, optional] __drv_aliasesMem PVOID Context,
[out] PIRP *Irp
);
Parâmetros
[in] DeviceObject
Um ponteiro para o DEVICE_OBJECT de destino para o IRP. No Windows 2000 e versões posteriores do Windows, esse parâmetro pode apontar para um PDO (objeto de dispositivo físico) ou um FDO (objeto de dispositivo funcional). No Windows 98/Me, esse parâmetro deve apontar para o PDO do dispositivo subjacente.
[in] MinorFunction
Especifica um dos seguintes códigos IRP de energia secundária: IRP_MN_QUERY_POWER, IRP_MN_SET_POWER ou IRP_MN_WAIT_WAKE.
[in] PowerState
Especifica um valor de POWER_STATE a ser passado no IRP. Para IRP_MN_SET_POWER e IRP_MN_QUERY_POWER, especifique o novo estado de energia do dispositivo solicitado. Os valores possíveis são DEVICE_POWER_STATE valores.
Para IRP_MN_WAIT_WAKE, especifique o estado de energia do sistema mais baixo (menos alimentado) do qual o dispositivo deve ter permissão para ativar o sistema. Os valores possíveis são SYSTEM_POWER_STATE valores.
[in, optional] CompletionFunction
Um ponteiro para a rotina de retorno de chamada do PowerCompletion do chamador. O gerente de E/S chama essa rotina quando o IRP é concluído. Esse parâmetro é opcional e pode ser definido como NULL se nenhuma rotina de retorno de chamada do PowerCompletion for necessária.
[in, optional] Context
Um ponteiro para um contexto fornecido pelo chamador a ser passado para o retorno de chamada do PowerCompletion . Quando o chamador solicita um IRP de set-power do dispositivo em resposta a um IRP de set-power do sistema, o Contexto deve conter o IRP de set-power do sistema que disparou a solicitação.
[out] Irp
Um ponteiro para uma variável fornecida pelo chamador na qual PoRequestPowerIrp retorna um ponteiro para o IRP que ele aloca. Especifique um valor para Irp somente se o parâmetro MinorFunction estiver definido como IRP_MN_WAIT_WAKE. Caso contrário, esse parâmetro sempre deverá ser NULL porque o IRP pode ser concluído antes do retorno de PoRequestPowerIrp , fazendo com que esse parâmetro aponte para a memória que já foi descartada.
Retornar valor
PoRequestPowerIrp retorna um dos seguintes:
| Código de retorno | Descrição |
|---|---|
|
O IRP foi enviado. |
|
A rotina não pôde alocar o IRP. |
|
MinorFunction não significa um código IRP de energia secundária válido. |
Comentários
Um proprietário da política de energia do dispositivo chama essa rotina para enviar um IRP de espera/ativação ou de configuração.
Um driver chama PoRequestPowerIrp, não IoAllocateIrp, para alocar e enviar um IRP de energia que tenha um código IRP secundário IRP_MN_SET_POWER, IRP_MN_QUERY_POWER ou IRP_MN_WAIT_WAKE. (Um driver deve chamar IoAllocateIrp para enviar um IRP de energia com código IRP secundário IRP_MN_POWER_SEQUENCE.)
Se PoRequestPowerIrp retornar um valor status de STATUS_PENDING, a rotina alocou com êxito um IRP de energia do dispositivo e o enviou para a parte superior da pilha do dispositivo para o dispositivo. Depois que o motorista do ônibus e todos os outros drivers tiverem concluído o IRP e o gerente de E/S chamar todas as rotinas de IoCompletion definidas pelos drivers conforme eles passavam o IRP para baixo na pilha do dispositivo, o gerente de E/S chama a rotina PowerCompletion e passa para essa rotina o valor de Contexto especificado. Se PoRequestPowerIrp retornar um status diferente de STATUS_PENDING, a rotina não enviou um IRP de energia do dispositivo e a rotina do PowerCompletion não será chamada.
A rotina PowerCompletion executa quaisquer tarefas adicionais que o remetente do IRP requer depois que todos os outros drivers tiverem concluído o IRP. Ele não precisa liberar o IRP; o power manager faz isso. No Windows 2000 e versões posteriores do Windows, a rotina PowerCompletion pode ser chamada em IRQL = PASSIVE_LEVEL ou IRQL = DISPATCH_LEVEL. No Windows 98/Me, a rotina PowerCompletion é sempre chamada em IRQL = PASSIVE_LEVEL e os drivers devem concluir IRPs em IRQL = PASSIVE_LEVEL.
Um proprietário da política de energia do dispositivo chama PoRequestPowerIrp para enviar um IRP de consulta de dispositivo ou de set-power quando recebe um IRP de consulta do sistema ou de set-power. O driver deve definir uma rotina IoCompletion no IRP do sistema e passar o IRP do sistema para o próximo driver inferior. A rotina IoCompletion chama PoRequestPowerIrp para enviar o IRP do dispositivo, passando o IRP do sistema no parâmetro Context . O parâmetro Context é posteriormente passado para a rotina PowerCompletion para o IRP do dispositivo. Na rotina do PowerCompletion , o driver pode concluir o IRP do sistema. Para obter mais informações, consulte Enviando IRP_MN_QUERY_POWER ou IRP_MN_SET_POWER para estados de energia do dispositivo e Rotinas de retorno de chamada de espera/ativação.
Os drivers podem usar o Irp retornado para cancelar um IRP IRP_MN_WAIT_WAKE . Os drivers que estão solicitando outros tipos de IRPs de energia devem passar NULL para esse parâmetro.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows 2000. |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |
| Regras de conformidade da DDI | HwStorPortProhibitedDIs(storport), MarkDevicePower(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RequestedPowerIrp(wdm) |