PO_FX_POWER_CONTROL_CALLBACK回呼函式 (wdm.h)

  • 發行項

PowerControlCallback 回呼例程會執行電源管理架構所要求的電源控制作業， (PoFx) 。

語法

PO_FX_POWER_CONTROL_CALLBACK PoFxPowerControlCallback;

NTSTATUS PoFxPowerControlCallback(
                  PVOID DeviceContext,
  [in]            LPCGUID PowerControlCode,
  [in, optional]  PVOID InBuffer,
  [in]            SIZE_T InBufferSize,
  [out, optional] PVOID OutBuffer,
  [in]            SIZE_T OutBufferSize,
  [out, optional] PSIZE_T BytesReturned
)
{...}

參數

DeviceContext

[in] PowerControlCode

電源控制件程式代碼的指標。 此程式代碼是指定所要求作業的 GUID 值。

[in, optional] InBuffer

緩衝區的指標，其中包含作業的輸入數據。 此緩衝區中的數據格式取決於 PowerControlCode 參數所指定的電源控制程式代碼。 InBuffer 參數是選擇性的，如果指定的作業不需要輸入數據，則可以指定為 NULL。

[in] InBufferSize

InBuffer 參數所指向之輸入緩衝區的大小，以位元組為單位。 如果 InBuffer 為 NULL，則此參數為零。

[out, optional] OutBuffer

回呼例程從作業寫入輸出數據的緩衝區指標。 此緩衝區中的數據格式取決於 PowerControlCode 參數所指定的電源控制程式代碼。 OutBuffer 參數是選擇性參數，如果指定的作業不會產生任何輸出數據，則可以指定為 NULL。

[in] OutBufferSize

OutBuffer 參數所指向之輸出緩衝區的大小，以位元組為單位。 如果 OutBuffer 為 NULL，則此參數為零。

[out, optional] BytesReturned

例程寫入寫入 OutBuffer 所指向緩衝區之數據位元組數目的位置指標。 寫入的位元組數目必須小於或等於 OutBufferSize。 此參數是選擇性的，如果呼叫端不需要知道有多少位元組寫入輸出緩衝區，則可以指定為NULL。

傳回值

如果呼叫成功， PowerControlCallback 例程會傳回STATUS_SUCCESS。 否則，它會傳回適當的錯誤碼。

備註

PoFx 會呼叫此例程，直接將電源控制要求傳送至設備驅動器。 電源控制要求類似於IOCTL) IOCTL (I/O 控制要求。 不過，不同於IOCTL，電源控制要求會直接傳送至驅動程式，而且不會由裝置堆疊中的其他設備驅動器觀察到。 在 PowerControlCallback 呼叫期間，驅動程式會同步執行要求的作業。

此例程是選擇性的。 實作 PowerControlCallback 例程不需要不支援電源控制作業的裝置驅動程式。

設備驅動器可以呼叫 PoFxPowerControl 例程，將電源控制要求傳送至PoFx。

如需電源控制要求的詳細資訊，請參閱 PoFxPowerControl。

範例

若要定義 PowerControlCallback 回 呼例程，您必須先提供函式宣告來識別您要定義的回呼例程類型。 Windows 提供一組驅動程式的回呼函式類型。 使用回呼函式類型宣告函式有助於 驅動程式的程式代碼分析、 靜態驅動程式驗證器 (SDV) ，以及其他驗證工具尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為MyPowerControlCallback的 PowerControlCallback 回呼例程，請使用 PO_FX_POWER_CONTROL_CALLBACK 類型，如下列程式代碼範例所示：

PO_FX_POWER_CONTROL_CALLBACK MyPowerControlCallback;

然後，實作回呼例程，如下所示：

_Use_decl_annotations_
NTSTATUS
  MyPowerControlCallback(
    PVOID Context,
    LPCGUID PowerControlCode,
    PVOID InBuffer,
    SIZE_T InBufferSize,
    PVOID OutBuffer,
    SIZE_T OutBufferSize,
    PSIZE_T BytesReturned
    )
  {
      // Function body
  }

PO_FX_POWER_CONTROL_CALLBACK函式類型定義於 Wdm.h 頭檔中。 若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 _Use_decl_annotations_ 批註新增至函式定義。 註釋 _Use_decl_annotations_ 可確保使用頭檔中套用至PO_FX_POWER_CONTROL_CALLBACK函式類型的批註。 如需函數宣告需求的詳細資訊，請參閱 使用WDM驅動程式的函式角色類型來宣告函式。 如需 的相關信息 _Use_decl_annotations_，請參閱 標註函式行為。

規格需求

需求 值
最低支援的用戶端 從 Windows 8 開始支援。
目標平台 桌面
標頭 wdm.h (包含 Wudfwdm.h)
IRQL 在 IRQL <= DISPATCH_LEVEL呼叫。

另請參閱

PO_FX_DEVICE

PoFxPowerControl