共用方式為

pcwCreateInstance 函式 (wdm.h)

  • 發行項

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

語法

NTSTATUS PcwCreateInstance(
  [out] PPCW_INSTANCE     *Instance,
  [in]  PPCW_REGISTRATION Registration,
  [in]  PCUNICODE_STRING  Name,
  [in]  ULONG             Count,
  [in]  PPCW_DATA         Data
);

參數

[out] Instance

要接收新建立實例的指標。 實例應該使用 PcwCloseInstance關閉。

[in] Registration

擁有這個實例之計數器集註冊的指標。 註冊是使用 PcwRegister建立的。

[in] Name

包含計數器集實例名稱的 Unicode 字串指標。 這不得為 NULL。

實例 Name 值必須隨著時間穩定， (相同的邏輯實例應該針對回呼的所有調用使用相同的 Name 值，) 且必須是唯一的。 如果計數器集註冊為單一實例，實例 Name 應該空白 (長度為 0) 。 如果計數器集註冊為多重實例，則實例 Name 不應該是空白的。 實例名稱比對不區分大小寫，因此 Name 值不只區分大小寫。

[in] Count

參數中 Data 提供的描述項數目。

[in] Data

提供者數據區塊的描述項陣列，其中包含這個實例的計數器值。 描述項所參考的數據區塊可以隨時存取，而且必須維持有效狀態，直到 實例由 PcwCloseInstance 或 PcwUnregister關閉為止。

傳回值

PcwCreateInstance 傳回下列其中一個值：

傳回碼 Description
STATUS_SUCCESS 已成功建立實例。
STATUS_INVALID_PARAMETER_4 由 指定的 Count結構數目對已註冊的提供者無效。
STATUS_INVALID_BUFFER_SIZE 其中一個提供者數據區塊太小。 例如，假設在呼叫 PcwRegister期間，提供者指定計數器 X 位於大小4位元組之第一個數據區塊的位移100。 如果呼叫 PcwCreateInstance 指定第一個數據區塊是 50 個字節，則會傳回這個錯誤狀態。
STATUS_INTEGER_OVERFLOW 結構的大小由 所指定 Count，會溢位數據緩衝區。

備註

計數器集提供者可以透過兩個不同的系統，將資訊提供給取用者：

  • 提供者可以提供 PCW_CALLBACK 函式，以視需要由性能計數器連結庫叫用以收集數據。 如需此系統的詳細資訊，請參閱 PCW_CALLBACK的檔。
  • 提供者可以使用 PcwCreateInstance 和 PcwCloseInstance 來維護可用實例的清單和對應的計數器數據。 此系統很容易實作，但彈性有限。

提供者使用這個函式之前，提供者必須呼叫 函 PcwRegister 式來建立註冊。

當新的實例到達 (例如，當裝置插入) 時，提供者應該配置和初始化實例的數據區塊、使用實例的名稱和數據區塊呼叫 PcwCreateInstance ，然後將數據區塊中的值保留為實例的計數器值更新。 當實例變成無效 (例如，當裝置解除叢集) 時，提供者應該呼叫 PcwCloseInstance ，然後刪除數據區塊。

提供者必須維護數據區塊 (通常位於分頁或非分頁集區中，) 包含每個實例的目前計數器值。

PcwCreateInstance 會自動指派實例的唯一標識符。 若要提供實例識別碼的特定值，請實作函 PCW_CALLBACK 式，而不是使用 PcwCreateInstance。

使用PcwCloseInstance函式關閉實例。

CTRPP 產生的 CreateXxx 函式

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

EXTERN_C __inline NTSTATUS
CreateMyCounterset(
    __deref_out PPCW_INSTANCE *Instance,
    __in PCUNICODE_STRING Name,
    __in const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

    Data[0].Data = MyCounterData;
    Data[0].Size = sizeof(MY_COUNTER_DATA);

    return PcwCreateInstance(Instance,
                             MyCounterset,
                             Name,
                             1,
                             Data);
}

CTRPP 產生的 Create 函式將會命名為 PrefixCreateCounterset。 前置 詞通常為空白，但如果在 CTRPP 命令行上使用參數，則可能存在 -prefix 。 Counterset 是計數器集的名稱，如指令清單中所指定。 函式會根據指令清單中定義的結構來擁有數據參數。 函式會將使用者提供的數據區塊 () 包裝成結構的陣列 PCW_DATA ，然後呼叫 PcwCreateInstance。 請注意，函式會在範例) 中參考 Counterset 變數 (MyCounterset ，這是保存 CTRPP 產生 RegisterXxx 函式所初始化之計數器集註冊句柄的全域變數。

規格需求

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

另請參閱

PcwCloseInstance 函式

PcwRegister 函式