Macro WdfDeviceStopIdle (wdfdevice.h)

[Aplica-se a KMDF e UMDF]

O método WdfDeviceStopIdle informa à estrutura que o dispositivo especificado deve ser colocado em seu estado de energia de trabalho (D0).

Sintaxe

NTSTATUS WdfDeviceStopIdle(
   _In_ WDFDEVICE Device,
   _In_ BOOLEAN WaitForD0
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] WaitForD0

Um valor booliano que indica quando WdfDeviceStopIdle retornará. Se TRUE, ele retornará somente depois que o dispositivo especificado tiver inserido o estado de energia do dispositivo D0. Se FALSE, o método retornará imediatamente.

Retornar valor

Nenhum

Comentários

Essa macro pode retornar os seguintes valores:

Valor retornado Significado
STATUS_PENDING O dispositivo está sendo ligado de forma assíncrona.
STATUS_INVALID_DEVICE_STATE O driver não é o proprietário da política de energia do dispositivo.
STATUS_POWER_STATE_INVALID Ocorreu uma falha no dispositivo e o dispositivo não pode inserir seu estado de energia D0.

O método pode retornar outros valores NTSTATUS.

Observação

Para dispositivos que especificam SystemManagedIdleTimeout ou SystemManagedIdleTimeoutWithHint na enumeração WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE , ao chamar WdfDeviceStopIdle com WaitForD0 definido como FALSE, se o dispositivo ainda estiver em D0 e o período de tempo limite ocioso ainda não tiver decorrido, começando nas versões do WDF 1.33/2.33, WdfDeviceStopIdle retornará STATUS_SUCCESS (em versões anteriores isso resultou em um valor de retorno de STATUS_PENDING).

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Se o dispositivo puder entrar em um estado de baixa potência quando ele ficar ocioso, o driver poderá precisar chamar ocasionalmente WdfDeviceStopIdle para trazer o dispositivo de volta ao estado de trabalho (D0) ou impedir que ele entre em um estado de baixa potência.

WdfDeviceStopIdle não impede que a estrutura faça a transição do dispositivo para um estado de suspensão quando o sistema muda para um estado de suspensão Sx. Seu único efeito é evitar transições para estados de suspensão Dx enquanto o sistema está no estado de trabalho S0. Da mesma forma, se o dispositivo der suporte ao gerenciamento de energia direcionado, WdfDeviceStopIdle não impedirá que o dispositivo insira a energia direcionada.

Aviso

Não chame WdfDeviceStopIdle com WaitForD0 = TRUE durante a desligar, direta ou indiretamente. Por exemplo, se o retorno de chamada EvtDeviceArmWakeFromS0 aguardar em outro thread que chama WdfDeviceStopIdle(TRUE), a transição de energia será bloqueada e o sistema falhará.

Seu driver não precisa chamar WdfDeviceStopIdle quando um dispositivo está ocioso e a estrutura coloca uma solicitação de E/S na fila de E/S gerenciada por energia do dispositivo. Além disso, o driver não precisa chamar WdfDeviceStopIdle quando um dispositivo está ocioso e detecta um sinal de ativação. Em ambos os casos, a estrutura solicita que o motorista do barramento restaure o estado de energia do dispositivo para D0.

Embora os drivers normalmente não precisem chamar WdfDeviceStopIdle ao lidar com solicitações de E/S obtidas de uma fila de E/S gerenciada por energia, a chamada é permitida. No entanto, os drivers não devem definir o parâmetro WaitForD0 como TRUE ao lidar com solicitações de E/S de uma fila de E/S gerenciada por energia.

O driver precisa chamar WdfDeviceStopIdle se precisar acessar o dispositivo devido a uma solicitação que o driver recebeu fora de uma fila de E/S gerenciada por energia. Por exemplo, seu driver pode dar suporte a uma interface definida pelo driver ou a uma solicitação WMI que requer acesso ao dispositivo. Nesse caso, você deve garantir que o dispositivo esteja em seu estado de trabalho antes que o driver acesse o dispositivo e que o dispositivo permaneça em seu estado de trabalho até que o driver termine de acessar o dispositivo.

Chamar WdfDeviceStopIdle força o dispositivo para seu estado de trabalho (D0), se o sistema estiver em seu estado de trabalho (S0). O dispositivo permanece em seu estado de trabalho até que o driver chame WdfDeviceResumeIdle, momento em que a estrutura poderá colocar o dispositivo em um estado de baixa potência se ele permanecer ocioso.

Não chame WdfDeviceStopIdle antes que a estrutura tenha chamado a função de retorno de chamada EvtDeviceD0Entry do driver pela primeira vez.

Uma chamada para WdfDeviceStopIdle poderá restaurar um dispositivo ocioso para seu estado de trabalho somente se o sistema estiver em seu estado de trabalho (S0). Se o sistema estiver fazendo a transição para um estado de baixa potência ou o dispositivo já tiver sido desligado em resposta ao Sx (em que x > 0) quando um driver chamar WdfDeviceStopIdle com o parâmetro WaitForD0 definido como TRUE, a função não retornará até que o sistema retorne ao estado S0.

Todas as chamadas bem-sucedidas para WdfDeviceStopIdle devem eventualmente ser seguidas por uma chamada para WdfDeviceResumeIdle ou então o dispositivo nunca retornará a um estado de baixa potência se ele ficar ocioso novamente. As chamadas para WdfDeviceStopIdle podem ser aninhadas, portanto, o número de chamadas para WdfDeviceResumeIdle deve ser igual ao número de chamadas para WdfDeviceStopIdle. Não chame WdfDeviceResumeIdle se uma chamada para WdfDeviceStopIdle falhar.

Se o sistema entrar em um estado de baixa potência após wdfDeviceStopIdle retornar, o dispositivo também entrará em um estado de baixa potência. Quando o sistema retorna ao estado de trabalho (S0), o dispositivo também retorna ao estado de trabalho (D0). A referência de energia da chamada para WdfDeviceStopIdle permanece ativa e impede que o dispositivo insira um estado de baixa potência até que haja uma chamada correspondente para WdfDeviceResumeIdle.

Para obter mais informações, consulte Suporte à ociosidade de energia para baixo.

Se WaitForD0 for TRUE, WdfDeviceStopIdle deverá ser chamado em IRQL = PASSIVE_LEVEL. Se WaitForD0 for FALSE, esse método deverá ser chamado em IRQL <= DISPATCH_LEVEL.

Chamar WdfDeviceStopIdleWithTag em vez de WdfDeviceStopIdle fornece informações adicionais (valor da marca, número de linha e nome do arquivo) que você pode exibir nos depuradores da Microsoft.

Exemplos

No exemplo de código a seguir, WdfDeviceStopIdle retorna depois que o dispositivo especificado inseriu o estado de energia do dispositivo D0.

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Requisitos

Requisito Valor
Plataforma de Destino Universal
Versão mínima do KMDF 1.0
Versão mínima do UMDF 2,0
Cabeçalho wdfdevice.h (inclua Wdf.h)
Biblioteca Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL Consulte a seção Observações.
Regras de conformidade de DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Confira também