Функция PoFxActivateComponent (wdm.h)

Статья
08/08/2023

Подпрограмма 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 :

Эти два бита флагов являются взаимоисключающими. Дополнительные сведения см. в подразделе "Примечания".

Значение	Значение
PO_FX_FLAG_BLOCKING 0x1	Сделайте изменение условия синхронным. Если этот флаг установлен, подпрограмма, запрашивающая изменение условия, не возвращает управление вызывающим драйвером до тех пор, пока оборудование компонента не завершит переход на новое условие. Этот флаг можно использовать только в том случае, если вызывающий объект работает на < DISPATCH_LEVEL IRQL.
PO_FX_FLAG_ASYNC_ONLY 0x2	Сделайте изменение условия полностью асинхронным. Если этот флаг установлен, подпрограмма обратного вызова драйвера вызывается из потока, отличного от потока, в котором вызывается подпрограмма, запрашивающая изменение условия. Таким образом, подпрограмма, запрашивающая изменение условия, всегда возвращается асинхронно, не дожидаясь завершения обратного вызова.

Значение

PO_FX_FLAG_BLOCKING
0x1

Сделайте изменение условия синхронным. Если этот флаг установлен, подпрограмма, запрашивающая изменение условия, не возвращает управление вызывающим драйвером до тех пор, пока оборудование компонента не завершит переход на новое условие. Этот флаг можно использовать только в том случае, если вызывающий объект работает на < DISPATCH_LEVEL IRQL.

PO_FX_FLAG_ASYNC_ONLY
0x2

Сделайте изменение условия полностью асинхронным. Если этот флаг установлен, подпрограмма обратного вызова драйвера вызывается из потока, отличного от потока, в котором вызывается подпрограмма, запрашивающая изменение условия. Таким образом, подпрограмма, запрашивающая изменение условия, всегда возвращается асинхронно, не дожидаясь завершения обратного вызова.

Возвращаемое значение

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