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

另請參閱

PCW_CALLBACK回呼函式