Função PoFxActivateComponent (wdm.h)
A rotina PoFxActivateComponent incrementa a contagem de referência de ativação no componente especificado.
Sintaxe
void PoFxActivateComponent(
[in] POHANDLE Handle,
[in] ULONG Component,
[in] ULONG Flags
);
Parâmetros
[in] Handle
Um identificador que representa o registro do dispositivo com a PoFx (estrutura de gerenciamento de energia). O driver de dispositivo recebeu anteriormente esse identificador da rotina PoFxRegisterDevice .
[in] Component
O índice que identifica o componente. Esse parâmetro é um índice na matriz Components na estrutura PO_FX_DEVICE que o driver de dispositivo usou para registrar o dispositivo com PoFx. Se a matriz Components contiver N elementos, os índices de componentes variam de 0 a N–1.
[in] Flags
Os sinalizadores para a operação de ativação. Defina esse membro como zero ou como um dos seguintes sinalizadores PO_FX_FLAG_ bitsXXX :
Esses dois bits de sinalizador são mutuamente exclusivos. Para obter mais informações, consulte Comentários.
Retornar valor
Nenhum
Comentários
Antes que um driver de dispositivo possa acessar um componente em um dispositivo, o driver deve primeiro chamar PoFxActivateComponent para obter uma referência de ativação para o componente. Se o componente ainda não estiver na condição ativa, essa chamada iniciará uma transição da condição ociosa para a condição ativa. Quando essa transição for concluída, o PoFx chamará a rotina ComponentActiveConditionCallback do driver para notificar o driver. O driver pode acessar os registros de hardware em um componente somente quando o componente está na condição ativa.
Se o componente já estiver na condição ativa quando PoFxActivateComponent for chamado, nenhuma transição será necessária e a rotina ComponentActiveConditionCallback não será chamada.
Depois que um componente entra na condição ativa, ele permanece na condição ativa enquanto o driver mantém uma ou mais referências de ativação no componente. Para liberar uma referência de ativação, o driver chama a rotina PoFxIdleComponent . Quando o driver libera a última referência de ativação em um componente, PoFxIdleComponent inicia uma transição da condição ativa para a condição ociosa. Um componente que está na condição ociosa pode potencialmente entrar em um estado fx de baixa potência.
Se Flags = PO_FX_FLAG_BLOCKING, a chamada PoFxActivateComponent será síncrona. Se o componente já estiver na condição ativa, a chamada incrementará a contagem de referência de ativação e retornará sem esperar. Caso contrário, PoFxActivateComponent aguarda o retorno até que o componente conclua a transição para a condição ativa. Nesse caso, se o componente ainda não estiver no estado F0 quando a chamada ocorrer, PoFxActivateComponent chamará a rotina ComponentIdleStateCallback do driver para iniciar a transição para F0. Depois que o componente entra no estado F0, PoFxActivateComponent chama a rotina ComponentActiveConditionCallback do driver para informar ao driver que o componente está na condição ativa. Esses retornos de chamada ocorrem no mesmo thread que a chamada para PoFxActivateComponent e PoFxActivateComponent retorna somente após o retorno de chamada ComponentActiveConditionCallback .
Se Flags = PO_FX_FLAG_ASYNC_ONLY, a chamada PoFxActivateComponent será assíncrona. Se o componente já estiver na condição ativa, a chamada incrementará a contagem de referência de ativação e retornará. Caso contrário, PoFxActivateComponent agenda os retornos de chamada ComponentIdleStateCallback (se necessário) e ComponentActiveConditionCallback para ocorrer em outro thread e retorna sem esperar que nenhum retorno de chamada ocorra. Os retornos de chamada podem ocorrer antes ou depois que PoFxActivateComponent retorna. O driver depende do retorno de chamada ComponentActiveConditionCallback para determinar quando o componente conclui a transição para a condição ativa.
O driver pode definir Flags = 0 para indicar que não se importa se a chamada PoFxActivateComponent é síncrona ou assíncrona. Nesse caso, a PoFx decide se deseja tornar a chamada síncrona ou assíncrona.
Dois ou mais caminhos de código no mesmo driver podem precisar acessar simultaneamente um componente específico. As rotinas PoFxActivateComponent e PoFxIdleComponent usam contagens de referência de ativação para permitir que as várias partes do driver mantenham independentemente o acesso ao componente sem exigir que o driver gerencie centralmente o acesso ao componente.
O PoFx mantém uma contagem de referência de ativação para cada componente em um dispositivo. Uma chamada PoFxActivateComponent incrementa essa contagem em um e uma chamada PoFxIdleComponent diminui a contagem em um. Quando a contagem é diferente de zero, o componente está na condição ativa ou está em processo de alternância para a condição ativa. Um componente que tem uma contagem de zero está na condição ociosa ou está em processo de alternância para a condição ociosa.
Quando uma chamada PoFxActivateComponent faz com que a contagem de referência de ativação seja incrementada de 0 para 1, PoFxActivateComponent inicia uma transição da condição ociosa para a condição ativa. Quando uma chamada PoFxIdleComponent faz com que a contagem decremento de 1 para 0, PoFxIdleComponent inicia uma transição da condição ativa para a condição ociosa.
PoFx notifica o driver quando ocorre uma transição entre a condição ativa e a condição ociosa. Um retorno de chamada ComponentActiveConditionCallback notifica o driver de uma transição para a condição ativa e um retorno de chamada ComponentIdleConditionCallback notifica o driver de uma transição para a condição ociosa. Quando uma chamada PoFxActivateComponent ou PoFxIdleComponent simplesmente incrementa ou diminui a contagem de referência de ativação sem causar essa transição, o driver não recebe nenhuma notificação.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível a partir do Windows 8. |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h |
| Biblioteca | Ntoskrnl.lib |
| DLL | Ntoskrnl.exe |
| IRQL | <= DISPATCH_LEVEL |