CPerfMon::CreateInstance

Call this method to create an instance of a performance object.

HRESULT CreateInstance(
   DWORD dwObjectId,
   DWORD dwInstance,
   LPCWSTR szInstanceName,
   CPerfObject** ppInstance
) throw( );
template <class T>
HRESULT CreateInstance(
   DWORD dwInstance,
   LPCWSTR szInstanceName,
   T** ppInstance
) throw( );

Parameters

dwObjectId

The ID used in defining the desired performance object. If the desired performance object was created using nonattributed code, then this will be the object ID used with the DECLARE_PERF_OBJECT or DECLARE_PERF_OBJECT_EX macros. For performance objects defined with attributed code, use the templatized version of CreateInstance.

dwInstance

This parameter can be used to specify a specific instance ID of an object instance if this ID is known ahead of time. If an instance with the given ID already exists, a reference to the existing object will be returned. If this parameter is 0, a new instance will be created with a unique ID and the new object will be returned. This parameter must be 0 for instanceless objects.

szInstanceName

A Unicode string indicating the name of the instance to be created.

ppInstance

The address of a pointer that points to the new object. When CPerfMon creates instances of classes derived from CPerfObject, the constructors of the derived classes are not called.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

Before performance counter values can be manipulated, an instance of the performance object containing the counters must be retrieved. If successful, the CreateInstance function creates an instance of the desired performance object and grants access using the supplied pointer.

Use this function to create instances if the object is instanceless or if objects are to be created with a well-defined scheme that lends itself to generating instances by ID. An example is creating instances to track how many of each window message an application receives; in this case, the window message itself will be the dwInstance.

Example

See the PerfPersist Sample.

See Also

Performance Monitoring | CPerfMon Overview | Class Members | Performance Monitoring Reference