Функция PoFxActivateComponent (wdm.h)
Подпрограмма PoFxActivateComponent увеличивает число ссылок активации для указанного компонента.
Синтаксис
void PoFxActivateComponent(
[in] POHANDLE Handle,
[in] ULONG Component,
[in] ULONG Flags
);
Параметры
[in] Handle
Дескриптор, представляющий регистрацию устройства с помощью платформы управления питанием (PoFx). Драйвер устройства ранее получил этот дескриптор из подпрограммы PoFxRegisterDevice .
[in] Component
Индекс, идентифицирующий компонент. Этот параметр является индексом массива Components в структуре PO_FX_DEVICE , используемой драйвером устройства для регистрации устройства с помощью PoFx. Если массив Components содержит N элементов, индексы компонентов варьируются от 0 до N–1.
[in] Flags
Флаги для операции активации. Присвойте этому элементу значение ноль или один из следующих флагов PO_FX_FLAG_XXX bits :
Эти два бита флагов являются взаимоисключающими. Дополнительные сведения см. в подразделе "Примечания".
Возвращаемое значение
None
Remarks
Прежде чем драйвер устройства сможет получить доступ к компоненту на устройстве, драйвер должен сначала вызвать PoFxActivateComponent , чтобы получить ссылку активации на компонент. Если компонент еще не находится в активном состоянии, этот вызов инициирует переход от условия простоя к активному условию. После завершения этого перехода PoFx вызывает подпрограмму ComponentActiveConditionCallback драйвера, чтобы уведомить драйвер. Драйвер может получить доступ к аппаратным регистрациям в компоненте, только если компонент находится в активном состоянии.
Если компонент уже находится в активном состоянии при вызове PoFxActivateComponent , переход не требуется и подпрограмма ComponentActiveConditionCallback не вызывается.
После того как компонент входит в активное условие, он остается в активном состоянии до тех пор, пока драйвер содержит одну или несколько ссылок активации в компоненте. Чтобы освободить ссылку на активацию, драйвер вызывает подпрограмму PoFxIdleComponent . Когда драйвер освобождает последнюю ссылку активации для компонента, PoFxIdleComponent инициирует переход от активного условия к условию простоя. Компонент, который находится в состоянии простоя, потенциально может перейти в маломощное состояние Fx.
Если флаги = PO_FX_FLAG_BLOCKING, вызов PoFxActivateComponent является синхронным. Если компонент уже находится в активном состоянии, вызов увеличивает число ссылок активации и возвращается без ожидания. В противном случае PoFxActivateComponent ожидает возврата, пока компонент не завершит переход к активному условию. В этом случае, если компонент еще не находится в состоянии F0 при вызове, PoFxActivateComponent вызывает подпрограмму ComponentIdleStateCallback драйвера, чтобы инициировать переход на F0. После того как компонент перейдет в состояние F0, PoFxActivateComponent вызывает подпрограмму ComponentActiveConditionCallback драйвера, чтобы сообщить драйверу о том, что компонент находится в активном состоянии. Эти обратные вызовы выполняются в том же потоке, что и вызов PoFxActivateComponent, а PoFxActivateComponent возвращается только после возврата обратного вызова ComponentActiveConditionCallback .
Если флаги = PO_FX_FLAG_ASYNC_ONLY, то вызов PoFxActivateComponent является асинхронным. Если компонент уже находится в активном состоянии, вызов увеличивает число ссылок активации и возвращает значение . В противном случае PoFxActivateComponent запланирует обратные вызовы ComponentIdleStateCallback (при необходимости) и ComponentActiveConditionCallback в другом потоке, а затем возвращается, не дожидаясь выполнения одного из этих обратных вызовов. Обратные вызовы могут выполняться до или после возврата PoFxActivateComponent . Драйвер использует обратный вызов ComponentActiveConditionCallback , чтобы определить, когда компонент завершит переход к активному условию.
Драйвер может установить флаги = 0, чтобы указать, что ему не важно, является ли вызов PoFxActivateComponent синхронным или асинхронным. В этом случае PoFx решает, следует ли сделать вызов синхронным или асинхронным.
Двум или более путям кода в одном драйвере может потребоваться одновременный доступ к определенному компоненту. Подпрограммы PoFxActivateComponent и PoFxIdleComponent используют счетчики ссылок на активацию, чтобы различные части драйвера могли независимо поддерживать доступ к компоненту без необходимости централизованного управления доступом к компоненту.
PoFx поддерживает количество ссылок активации для каждого компонента на устройстве. Вызов PoFxActivateComponent увеличивает это число на единицу, а вызов PoFxIdleComponent уменьшает число на единицу. Если счетчик не равен нулю, компонент либо находится в активном состоянии, либо находится в процессе переключения на активное условие. Компонент с нулем либо находится в состоянии простоя, либо находится в процессе переключения на условие простоя.
Когда вызов PoFxActivateComponent приводит к тому, что число ссылок на активацию увеличивается с 0 до 1, PoFxActivateComponent инициирует переход от условия простоя к активному условию. Когда вызов PoFxIdleComponent приводит к уменьшению числа с 1 до 0, PoFxIdleComponent инициирует переход от активного условия к условию простоя.
PoFx уведомляет драйвер при переходе между активным условием и условием простоя. Обратный вызов ComponentActiveConditionCallback уведомляет драйвер о переходе к активному условию, а обратный вызов ComponentIdleConditionCallback уведомляет драйвер о переходе на условие простоя. Когда вызов PoFxActivateComponent или PoFxIdleComponent просто увеличивает или уменьшает число ссылок активации, не вызывая такой переход, драйвер не получает уведомления.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Доступно начиная с Windows 8. |
| Целевая платформа | Универсальное |
| Верхняя часть | wdm.h |
| Библиотека | Ntoskrnl.lib |
| DLL | Ntoskrnl.exe |
| IRQL | <= DISPATCH_LEVEL |