Creates an instance of the specified counter set. Providers use this function.

Syntax

PPERF_COUNTERSET_INSTANCE PerfCreateInstance(
  __in  HANDLE hProvider,
  __in  LPCGUID CounterSetGuid,
  __in  LPCWSTR szInstanceName,
  __in  ULONG dwInstance
);

Parameters

hProvider [in]

Handle of the provider. The handle is returned by the PerfStartProvider function.

CounterSetGuid [in]

GUID that uniquely identifies the counter set that you want to create an instance of. This is the same GUID specified in the guid attribute of the <counterSet> element.

szInstanceName [in]

Null-terminated Unicode string that contains a unique name for this instance.

dwInstance [in]

Unique identifier for this instance of the counter set. The identifier can be a serial number that you increment for each new instance.

Return Value

A PERF_COUNTERSET_INSTANCE structure that contains the instance of the counter set or NULL if PERFLIB could not create the instance. Cache this pointer to use in later calls instead of calling PerfQueryInstance to retrieve the pointer to the instance.

This function returns NULL if an error occurred. To determine the error that occurred, call GetLastError.

Remarks

The provider determines when it creates an instance. If the counter data is more static, the provider can create an instance at initialization time. For example, the number of processors on a computer would be considered static, so a provider that provides counter data for processors could create an instance for each processor on the computer at initialization time. For counters that are more dynamic, such as disk or process counters, the providers would create the new instances in response to a new USB device being added or a new process being created.

When the provider calls this function, PERFLIB allocates local memory for the new instance and builds the instance block. PERFLIB deletes the memory when the provider calls the PerfDeleteInstance function.

The instance contains the raw counter data. Providers use the following three functions to update the raw counter data:

• PerfSetUlongCounterValue
• PerfSetUlongLongCounterValue
• PerfSetCounterRefValue

Typically, the provider keeps the counter data up-to-date at all times. As an alternative, the provider can implement the ControlCallback function and use the PERF_COLLECT_START request code to trigger the updates.

Requirements

See Also

PerfDeleteInstance
PerfQueryInstance

Send comments about this topic to Microsoft

Build date: 7/17/2008