Função PoCallDriver (wdm.h)

Artigo
08/08/2023

A rotina do PoCallDriver passa um IRP de energia para o driver mais baixo na pilha do dispositivo. (Somente Windows Server 2003, Windows XP e Windows 2000.)

Sintaxe

NTSTATUS PoCallDriver(
  [in]      PDEVICE_OBJECT        DeviceObject,
  [in, out] __drv_aliasesMem PIRP Irp
);

Parâmetros

[in] DeviceObject

Um ponteiro para o DEVICE_OBJECT criado pelo driver para o qual o IRP deve ser roteado.

[in, out] Irp

Um ponteiro para um IRP.

Retornar valor

PoCallDriver retorna STATUS_SUCCESS para indicar êxito. Ele retornará STATUS_PENDING se tiver enfileirado o IRP.

Comentários

A partir do Windows Vista, os drivers devem chamar IoCallDriver, não PoCallDriver para passar um IRP de energia para o driver mais baixo. No entanto, no Windows Server 2003, Windows XP e Windows 2000, os drivers devem chamar PoCallDriver, não IoCallDriver para passar um IRP de energia para o driver mais baixo. No Windows Server 2003, Windows XP, um Windows 2000, os drivers também devem chamar PoStartNextPowerIrp antes de chamar PoCallDriver.

Um driver que requer um novo IRP deve chamar PoRequestPowerIrp. Um driver não deve alocar seu próprio IRP de energia.

Ao passar um IRP de energia para baixo para o driver mais baixo, o chamador deve usar IoSkipCurrentIrpStackLocation ou IoCopyCurrentIrpStackLocationToNext para definir o local da pilha IRP e chamar PoCallDriver. Use IoCopyCurrentIrpStackLocationToNext se o processamento do IRP exigir a configuração de uma rotina IoCompletion ou IoSkipCurrentStackLocation se nenhuma rotina IoCompletion for necessária.

Quando um dispositivo está ativando, seus drivers devem definir rotinas IoCompletion para executar tarefas de inicialização (inicializando o dispositivo, restaurando o contexto e assim por diante) depois que o motorista do ônibus tiver definido o dispositivo no estado de trabalho. Defina rotinas de IoCompletion antes de chamar PoCallDriver.

Quando um dispositivo está desligando, seus drivers devem executar as tarefas de desligar necessárias antes de passar o IRP para o próximo driver inferior. Depois que o IRP chegar ao motorista do ônibus, o dispositivo será desligado e seus motoristas não terão mais acesso a ele. No Windows Server 2003, Windows XP e Windows 2000, uma rotina IoCompletion associada a um IRP de desligar só é necessária para chamar PoStartNextPowerIrp.

Somente um IRP inrush pode estar ativo no sistema por vez. Ao passar um IRP de ativação para um dispositivo que requer a corrente inrush (em outras palavras, o sinalizador DO_POWER_INRUSH é definido no objeto do dispositivo), PoCallDriver verifica se outro IRP inrush já está ativo. Nesse caso, PoCallDriver enfileira o IRP atual para manipulação após a conclusão do IRP anterior e, em seguida, retorna STATUS_PENDING. Para obter mais informações sobre IRPs inrush, consulte Setting Device Object Flags for Power Management(Definindo sinalizadores de objeto de dispositivo para gerenciamento de energia).

Se uma solicitação de IRP_MN_SET_POWER ou IRP_MN_QUERY_POWER já estiver ativa para DeviceObject, PoCallDriver enfileira esse IRP e retorna STATUS_PENDING.

No Windows 2000 e em sistemas posteriores, drivers pagináveis (o sinalizador DO_POWER_PAGABLE está definido no objeto do dispositivo) devem chamar PoCallDriver em IRQL = PASSIVE_LEVEL. Drivers que não podem ser paginado (DO_POWER_PAGABLE não está definido no objeto do dispositivo) ou que exigem inrush current (DO_POWER_INRUSH está definido no objeto do dispositivo) podem chamar PoCallDriver em IRQL = PASSIVE_LEVEL ou DISPATCH_LEVEL.

No Windows 98/Me, todos os drivers chamam PoCallDriver em IRQL = PASSIVE_LEVEL.

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	Consulte a seção Observações.
Regras de conformidade de DDI	CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), DeleteDevice(wdm), ForwardedAtBadIrql(wdm), ForwardedAtBadIrqlAllocate(wdm), ForwardedAtBadIrqlFsdAsync(wdm), ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDIs(storport), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildFsdForward(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), IoSetCompletionRoutineExCheck(wdm), IrpProcessingComplete(wdm), LowerDriverReturn(wdm), MarkDevicePower(wdm), MarkingQueuedIrps(wdm), MarkIrpPending(wdm), MarkIrpPending2(wdm), MarkPower(wdm) , MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequest(wdm), PendedCompletedRequest2(wdm), PendedCompletedRequest3(wdm), PendedCompletedRequestEx(wdm), PnpIrpCompletion(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RemoveLockForward(wdm), RemoveLockForward2(wdm), RemoveLockForwardDeviceControl(wdm), RemoveLockForwardDeviceControl2(wdm), RemoveLockForwardDeviceControlInternal(wdm), RemoveLockForwardDeviceControlInternal2(wdm), RemoveLockForwardRead(wdm), RemoveLockForwardRead2(wdm), RemoveLockForwardWrite(wdm), RemoveLockForwardWrite2(wdm), RemoveLockMnRemove2(wdm), RemoveLockMnSurpriseRemove(wdm), RemoveLockQueryMnRemove(wdm), TargetRelationNeedsRef(wdm), WmiForward(wdm)