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 |