Função PoRequestPowerIrp (wdm.h)

Artigo
08/08/2023

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
STATUS_PENDING	O IRP foi enviado.
STATUS_INSUFFICIENT_RESOURCES	A rotina não pôde alocar o IRP.
STATUS_INVALID_PARAMETER_2	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)