pcwRegister 函式 (wdm.h)

函式 PcwRegister 會建立新的計數器集註冊。 大部分開發人員都會使用 CTRPP 產生的 RegisterXxx 函式，而不是直接呼叫此函式。

語法

NTSTATUS PcwRegister(
  [out] PPCW_REGISTRATION             *Registration,
  [in]  PPCW_REGISTRATION_INFORMATION Info
);

參數

[out] Registration

PPCW_REGISTRATION的指標。 接收新註冊的句柄。 應該使用 PcwUnregister 關閉註冊。

[in] Info

PCW_REGISTRATION_INFORMATION 結構的指標，其中包含所註冊計數器集的詳細數據。

傳回值

PcwRegister 傳回下列其中一個值：

傳回碼	Description
STATUS_SUCCESS	計數器集已成功註冊。
STATUS_INTEGER_OVERFLOW	此註冊所公開的計數器數目超過支援的最大值。
STATUS_NO_MEMORY	沒有足夠的空間可供配置計數器的記憶體。
STATUS_INVALID_PARAMETER_2	在參數中 Info 發現問題。 如需一些可能的原因，請參閱下方。

PcwRegister 可能會在下列情況下傳回 STATUS_INVALID_PARAMETER_2 ：

• 欄位 Info->Name->Length 為 0，或不是 的 sizeof(WCHAR)倍數。

• 此 Info->Version 欄位與這個版本的 Windows 不支援的值不符。 在 10.0.19645 () NTDDI_VERSION < NTDDI_VERSION_MN 之前在 Windows 上執行時， Version 字段必須設定為 PCW_VERSION_1 (0x100) 。 在 Windows 10.0.19645 和更新版本上執行時，) NTDDI_VERSION >= NTDDI_VERSION_MN (，可能會將此設定為 PCW_VERSION_1 (0x100) 或 PCW_VERSION_2 (0x200) 。

• 欄位 Info->Flags 包含執行中 Windows 版本無法辨識的值。

備註

提供者會呼叫此函式來建立新的計數器集註冊。 會擷取所有輸入自變數，讓呼叫端不需要保留它們的複本。

根據預設，新的計數器集只會顯示在註冊時作用中的伺服器接收器 (，也就是 PcwRegister 將新建立的註冊與呼叫) 時 PcwRegister 附加至線程的伺服器接收器產生關聯。 如果在 Windows 10.0.19645 和更新版本上執行， () NTDDI_VERSION >= NTDDI_VERSION_MN 您可以藉由將 設定為 PCW_REGISTRATION_INFORMATION::VersionPCW_VERSION_2 ，PCW_REGISTRATION_INFORMATION::FlagsPcwRegistrationSiloNeutral建立所有伺服器尋址接收器可見的計數器集註冊。

CTRPP 產生的 RegisterXxx 函式

大部分開發人員不需要直接呼叫 PcwRegister 。 相反地，他們會使用 CTRPP 工具編譯指令清單，並從 CTRPP 產生的標頭使用 RegisterXxx 函式。 產生的函式看起來會像這樣：

EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext
    )
{
    PCW_REGISTRATION_INFORMATION RegInfo;

    PAGED_CODE();

    InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

    return PcwRegister(&MyCounterset, &RegInfo);
}

CTRPP 產生的 Register 函式會命名為 PrefixRegisterCounterset。 前置 詞通常為空白，但如果在 CTRPP 命令行上使用參數，則可能存在 -prefix 。 Counterset 是計數器集的名稱，如指令清單中所指定。 產生的 Register 函式會叫用 PrefixInitRegistrationInformationCounterset 函式來初始化PCW_REGISTRATION_INFORMATION結構，然後叫PcwRegister用 以建立新的註冊，MyCounterset並將句柄儲存在 CTRPP 產生的標頭中宣告的全域 Counterset (變數中，) 。

在某些情況下，CTRPP 產生的 Add 函式可能不適合。

• 如果您必須使用 編譯 NTDDI_VERSION >= NTDDI_VERSION_FE ，但必須在舊版 Windows 上執行，則 CTRPP 產生的 Register 函式將無法運作，因為它會設定 RegInfo.Version = PCW_CURRENT_VERSION。 當 設定為 時NTDDI_VERSION >= NTDDI_VERSION_FE，PCW_CURRENT_VERSION會導致傳PcwRegister回錯誤。PCW_VERSION_2

• 如果您需要支援多個計數器集註冊 (例如，若要支援每個伺服器尋址接收器) 個別註冊，則 CTRPP 產生的 Register 函式將無法運作，因為它會將傳回的句柄儲存在全域變數中。

• 如果您想要建立尋址接收器中性計數器集註冊，則 CTRPP 產生的 Register 函式將無法運作，因為呼叫 之前PcwRegister無法變更的值RegInfo.Flags。

在這些情況下，請使用類似下列的程序代碼，而不是呼叫 CTRPP 產生的 Register 函式：

PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.

// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);

CTRPP 產生的 InitRegistrationInformationXxx 函式會根據指令清單的宣告，初始化 RegInfo 結構。 如需所產生 InitRegistrationInformation 函式的詳細資訊，請參閱 PCW_REGISTRATION_INFORMATION的檔。

如果您使用自己的句柄變數而非 Counterset 來儲存句柄，您可能也需要呼叫 並直接呼叫 PcwUnregister ， PcwCreateInstance 而不是使用 CTRPP 產生的 UnregisterXxx 和 CreateXxx 函式。

規格需求

需求	值
最低支援的用戶端	可在 Windows 7 和更新版本的 Windows 中使用。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

另請參閱

PcwUnregister

_PCW_REGISTRATION_INFORMATION