poFxActivateComponent 函式 (wdm.h)

  • 發行項

PoFxActivateComponent 例程會遞增指定元件的啟用參考計數。

語法

void PoFxActivateComponent(
  [in] POHANDLE Handle,
  [in] ULONG    Component,
  [in] ULONG    Flags
);

參數

[in] Handle

句柄，表示使用電源管理架構註冊裝置， (PoFx) 。 設備驅動器先前已從 PoFxRegisterDevice 例程收到此句柄。

[in] Component

識別元件的索引。 此參數是裝置驅動程式用來向PoFx註冊裝置之PO_FX_DEVICE結構中 Components 陣列的索引。 如果 Components 陣列包含 N 個元素，元件索引的範圍從 0 到 N–1。

[in] Flags

啟用作業的旗標。 將此成員設定為零或設定為下列其中一個旗標 ，PO_FX_FLAG_XXX 位：

這兩個旗標位互斥。 如需詳細資訊，請參閱＜備註＞。

值 意義
PO_FX_FLAG_BLOCKING
0x1
 讓條件變更同步。 如果設定此旗標，要求條件變更的例程不會將控制權傳回呼叫驅動程式，直到元件硬體完成轉換至新條件為止。 只有當呼叫端在 IRQL < DISPATCH_LEVEL 執行時，才能使用此旗標。
PO_FX_FLAG_ASYNC_ONLY
0x2
 讓條件變更完全異步。 如果設定此旗標，呼叫驅動程式的回呼例程會從呼叫條件變更的線程以外的線程呼叫。 因此，要求條件變更的例程一律會以異步方式傳回，而不需要等待回呼完成。

傳回值

無

備註

在設備驅動器可以存取裝置中的元件之前，驅動程式必須先呼叫 PoFxActivateComponent 以取得元件的啟用參考。 如果元件尚未處於作用中條件，則此呼叫會起始從閑置條件轉換至使用中條件。 此轉換完成時，PoFx 會呼叫驅動程式的 ComponentActiveConditionCallback 例程來通知驅動程式。 只有在元件處於使用中條件時，驅動程式才能存取元件中的硬體緩存器。

如果呼叫 PoFxActivateComponent 時元件已在作用中條件中，則不需要轉換，而且不會呼叫 ComponentActiveConditionCallback 例程。

元件進入使用中條件之後，只要驅動程式在元件上保留一或多個啟用參考，它就會保留在作用中條件中。 若要釋放啟用參考，驅動程式會呼叫 PoFxIdleComponent 例程。 當驅動程式在元件上釋放上次啟用參考時， PoFxIdleComponent 會起始從作用中條件轉換到閑置條件。 處於閑置條件的元件可能會進入低電源 Fx 狀態。

如果 Flags = PO_FX_FLAG_BLOCKING， 則 PoFxActivateComponent 呼叫是同步的。 如果元件已在作用中條件中，呼叫會遞增啟用參考計數，並在不等候的情況下傳回。 否則， PoFxActivateComponent 會等候返回，直到元件完成轉換至使用中條件為止。 在此情況下，如果元件在呼叫發生時尚未處於 F0 狀態， PoFxActivateComponent 會呼叫驅動程式的 ComponentIdleStateCallback 例程來起始轉換至 F0。 元件進入 F0 狀態之後， PoFxActivateComponent 會呼叫驅動程式的 ComponentActiveConditionCallback 例程，通知驅動程式該元件處於使用中狀況。 這些回呼發生在與 呼叫 PoFxActivateComponent 相同的線程中，而 PoFxActivateComponent 只有在 ComponentActiveConditionCallback 回呼傳回之後才會傳回。

如果 Flags = PO_FX_FLAG_ASYNC_ONLY， 則 PoFxActivateComponent 呼叫是異步的。 如果元件已經在使用中條件中，呼叫會遞增啟用參考計數並傳回。 否則， PoFxActivateComponent 會視需要) 排程 ComponentIdleStateCallback (，並在另一個線程中發生 ComponentActiveConditionCallback 回 呼，然後傳回而不等待任一回呼發生。 回呼可以在 PoFxActivateComponent 傳回之前或之後發生。 驅動程式依賴 ComponentActiveConditionCallback 回 呼來判斷元件何時完成轉換至使用中條件。

驅動程式可以設定 Flags = 0，表示它不小心 PoFxActivateComponent 呼叫是同步還是異步的。 在此情況下，PoFx 會決定是否要進行同步或異步呼叫。

相同驅動程式中的兩個或多個程式代碼路徑可能需要同時存取特定元件。 PoFxActivateComponent 和 PoFxIdleComponent 例程會使用啟用參考計數，讓驅動程式的各個部分獨立維護元件的存取權，而不需要驅動程式集中管理元件的存取權。

PoFx 會維護裝置中每個元件的啟用參考計數。 PoFxActivateComponent 呼叫會將此計數遞增一，而 PoFxIdleComponent 呼叫會將計數遞減一。 當計數為非零時，元件會處於使用中條件，或是在切換至使用中條件的過程中。 具有零計數的元件是在閑置狀況中，或是在切換至閑置條件的過程中。

當 PoFxActivateComponent 呼叫導致啟用參考計數從 0 遞增到 1 時， PoFxActivateComponent 會起始從閑置條件到使用中條件的轉換。 當 PoFxIdleComponent 呼叫導致計數從 1 遞減到 0 時， PoFxIdleComponent 會起始從使用中條件轉換到閑置條件。

PoFx 會在作用中條件與閑置條件之間發生轉換時通知驅動程式。 ComponentActiveConditionCallback 回呼會通知驅動程式轉換至使用中條件，而 ComponentIdleConditionCallback 回呼會通知驅動程式轉換至閑置條件。 當 PoFxActivateComponent 或 PoFxIdleComponent 呼叫只會遞增或遞減啟用參考計數而不會造成這類轉換時，驅動程式不會收到任何通知。

規格需求

需求 值
最低支援的用戶端 從 Windows 8 開始提供。
目標平台 Universal
標頭 wdm.h
程式庫 Ntoskrnl.lib
Dll Ntoskrnl.exe
IRQL <= DISPATCH_LEVEL

另請參閱

ComponentActiveConditionCallback

ComponentIdleStateCallback

PO_FX_DEVICE

PoFxIdleComponent

PoFxRegisterDevice