pcwAddInstance 函式 (wdm.h)
函 PcwAddInstance 式會將計數器集的指定實例新增至取用者緩衝區。 大部分開發人員都會使用 CTRPP 產生的 AddXxx 函式，而不是直接呼叫此函式。 如需詳細資訊，請參閱下面的。
語法
NTSTATUS PcwAddInstance(
[in] PPCW_BUFFER Buffer,
[in] PCUNICODE_STRING Name,
[in] ULONG Id,
[in] ULONG Count,
[in] PPCW_DATA Data
);
參數
[in] Buffer
將加入計數器集實例的系統管理緩衝區句柄。 當緩衝區來自 PcwCallbackEnumerateInstances 通知時， PcwAddInstance 只會記錄實例的名稱和標識符。 當緩衝區來自 PcwCallbackCollectData 通知時， PcwAddInstance 會記錄實例) 名稱、標識碼和數據 (計數器值。
[in] Name
Unicode 字串的指標，其中包含計數器集實例的名稱。 這不得為 NULL。
實例 Name 值必須隨著時間穩定， (相同的邏輯實例應該針對回呼的所有調用使用相同的 Name 值) ，而且必須是唯一的。 如果計數器集註冊為單一實例，則實例 Name 應為空白 (長度為 0) 。 如果計數器集註冊為多重實例，則實例 Name 不應該空白。 實例名稱比對不區分大小寫，因此 Name 值不應只因大小寫而有所不同。
[in] Id
數值，指定 Id 與計數器集實例相關聯的 (標識碼) 。
實例 Id 值必須隨著時間穩定， (相同實例應該針對回呼) 的所有調用使用相同的 Id 值，應該是唯一的 (例如，請勿針對所有實例) 使用 0，而且應該小於0xFFFFFFFE (不会用于 PCW_ANY_INSTANCE_ID 任何實例) 。 可能的話，實例 Id 應該有意義的 (例如進程計數器集可能會使用 PID 作為 Id) ，而不是任意 (例如序號) 。
[in] Count
參數中 Data 提供的描述項數目。
[in] Data
提供者數據區塊的描述項陣列，其中包含這個實例的計數器值。
傳回值
PcwAddInstance 會傳回下列其中一個值：
| 傳回碼 | Description |
|---|---|
STATUS_SUCCESS |
實例已成功新增至緩衝區。 |
STATUS_INVALID_BUFFER_SIZE |
其中一個提供者數據區塊太小。 例如，假設在 呼叫PcwRegister期間，提供者指定計數器 X 位於大小4位元組之第一個數據區塊的位移100。 如果呼叫 PcwAddInstance 指定第一個數據區塊為 50 個字節，則會傳回此錯誤狀態。 |
備註
當PcwAddInstance通知類型為 PcwCallbackEnumerateInstances 或 PcwCallbackCollectData時，提供者定義的PCW_CALLBACK例程應該呼叫函式。 Buffer要使用的 來自Info例程的參數PCW_CALLBACK，例如 Info->EnumerateInstances.Buffer 或 Info->CollectData.Buffer。
針對 PcwCallbackEnumerateInstances 通知呼叫 時， PcwAddInstance 將 Name 和 Id 值新增至緩衝區。 針對通知呼叫 PcwCallbackCollectData 時， PcwAddInstance 將 Name、 Id和 計數器數據值新增至緩衝區。
CTRPP 產生的 Add** 函式
大部分的開發人員不需要直接呼叫 PcwAddInstance 。 相反地，他們會使用 CTRPP 工具編譯指令清單，並使用 CTRPP 產生的標頭中的 Add** 函式。 產生的函式看起來會像這樣：
EXTERN_C __inline NTSTATUS
AddMyCounterset(
__in PPCW_BUFFER Buffer,
__in PCUNICODE_STRING Name,
__in ULONG Id,
__in_opt const MY_COUNTER_DATA *MyCounterData
)
{
PCW_DATA Data[1];
PAGED_CODE();
Data[0].Data = MyCounterData;
Data[0].Size = sizeof(MY_COUNTER_DATA);
return PcwAddInstance(Buffer,
Name,
Id,
1,
Data);
}
CTRPP 產生的 Add 函式會命名為 PrefixAddCounterset。 前置詞 通常是空白的，但如果在 CTRPP 命令行上使用參數，則可能會出現 -prefix 。 Counterset 是計數器集的名稱，如指令清單中所指定。 函式會根據指令清單中定義的結構來擁有Data參數。 函式會將使用者提供的數據區塊包裝 () 成 結構的陣列 PCW_DATA ，然後呼叫 PcwAddInstance。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 適用於 Windows 7 和更新版本的 Windows。 |
| 目標平台 | Universal |
| 標頭 | wdm.h (包括 Wdm.h、Ntddk.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |