[in] [in] [in] [in] [in]

bstrTypeGuid The string representation of GUID should be passed through this parameter. (GUID string without curly or square brackets around) bstrObjectName Object name. bstrObjectDesc Object description. ObjectDetailLevel Special constant, which could be taken from enumeration type which, resides in the type library for the performance component. InstanceNameOrShareFlag See remarks

Remarks:

Each performance object must have object type. This type is represented by GUID string (example: "00001234-5678-9012-3456-78901234ABCD") passed through this method call. You are as developer responsible for generation your own GUID. We also provide tility called magicguid.exe which will generate GUID for you. 
Reason for the GUID: Suppose two different developers from two different companies decided to export a single performance object in his or her application respectively. Further: each of these persons gave the same name to his or her object and each of them added only one counter to his or her object with the same name also. By using unique GUIDs these people irrespectively of each other will give a hint to the component and these objects will be able to co-exist and work on the same machine without conflicts.

In the ObjectDetailLevel variable passed to the method caller could specify one of the constants: (LevelNovice = 0, LevelAdvanced = 1, LevelExpert = 2, LevelWizard = 3), which resides in type library for the component, or the caller could pass just raw constant from the range [0..3]. Detail level doesn't affect any important object characteristics at least from the point of view of today's version of Performance Monitor application, but this could change in the future. Moreover detail level could be used by any custom performance-monitoring application which uses NT's standard performance-monitoring interface through registry API.

The last parameter of this method is very important. The thing must be mentioned first is the variable type which could be passed to this method. The only types, which will be accepted by the component, are Null, Empty, String, Bool. Any other type will be rejected with error. The type of the last parameter and parameter's data controls one important aspect of performance object - instance behavior. See the table below to decide what value to pass through this parameter to the component to get suitable performance object mode.

Example:

Call myobj.DefineObjectType("f370c8f0-2031-11d4-ae08-0050dacfb712" , "myObject", "myObjectDesc", LevelExpert, True)

This is a second method that should be done after the call of DefineObjectType in your application. This method needed to add one or more performance counters to the performance object type. It called so many times as many counters are going to be added to the object definition. Those calls could be made only before calling RegisterObjectType. After successful registration of performance object type (through RegisterObjectType) any call to this method will generate an error.

[in] [in [in] [in] [in]		bstrCounterName Counter name bstrCounterDesc Counter description. PredefinedCounterType Counter type. (See Constant Table) CounterDetailLevel Special constant, which could be taken from enumeration type which, resides in the type library for the performance component. CounterScale Some constant value to specify default counter scale as hint for data visualization in Performance Monitor application. This constant value defines scale factor as a power of 10.
		Example: 1 - means scale factor 0.1 2 - means scale factor 0.02 3 - means scale factor 1000
[in] [out]		Valid value for this parameter belongs to the range [-7..7]. bfDefaultCounterFlag If "true" value is passed in this parameter then corresponding counter will be treated as default. It means that if somebody adds performance counter for monitoring without selecting one, then default counter will be chosen automatically by Performance Monitor application. Each successive call with a "true" value overwrites previously defined default counter. pCounterIndex Counter access index. Must be saved on successful return from the method (See remarks)

Remarks:

When specifying counter name and counter description make sure not to provide empty strings. If any of these parameters are Null or contain empty strings then component will return error code. Strings with blanks are allowed.
In the CounterDetailLevel variable passed to the method caller it is possible to specify one of the constants: (LevelNovice = 0, LevelAdvanced = 1, LevelExpert = 2, LevelWizard = 3), which resides in type library for the component, or the caller could pass just raw constant from the range [0..3]. Detail level doesn't affect any of counter's characteristics at least from the point of view of today's version of Performance Monitor application, but this could change in the future.
On successful return from this method caller must save a value referenced by pCounterIndex pointer. Caller must not make any assumptions about the value being referenced by this pointer. Later this value should be used when updating specific counter's data.

Example:

c1 = myobj.AddPredefinedCounterDefinition("DeltaCounter", "DeltaCounter",
DeltaCounter, 1, 0, Null)

c2 = myobj.AddPredefinedCounterDefinition("NumberCounter", "NumberCounter",
NumberCounter, 1, 0, Null)

c3 = myobj.AddPredefinedCounterDefinition("AvgTimeCounter", "AvgTimeCounter",
AvgTimeCounter, 1, 0, Null)

c4 = myobj.AddPredefinedCounterDefinition("AvgBulkCounter", "AvgBulkCounter",
AvgBulkCounter, 1, 0, Null)

c5 = myobj.AddPredefinedCounterDefinition("RateCounter", "RateCounter",
RateCounter, 1, 0, Null)

Remarks:

While call is being performed attempt is made to register performance object's name and description and it counters names with descriptions in system's performance database, internal memory-based structure of the object is created also.

Example:
Call myobj.RegisterObjectType

Remarks:

If performance object is registered (via a call to RegisterObjectType), then this method won't work. Moreover this method is not intended to be called often and will succeed only under some circumstances. First thing that should be taken in mind is the fact that performance object's definition data (counters' names and theirs explanations) resides in registry and could be accessed at any particular moment not only by the component itself, but by operating system and performance monitoring applications. That implies some restrictions, since component's code is unaware about such activity. The component checks whether any similar component instances are running at specific instance of un-registration, and whether any standard Performance Monitoring applications are running and use counters' definitions from the system's performance database which is about of being reorganized by the call to this method. If object counters are not locked by any of the above resources, object will be deleted. If counters are in use, this method will fail.

Example:

Call myobj.UnregisterObjectType

[in] a. b.

typeOfTimeMark As Long Specifies type of time measure. Could be TuFrequency TuInterval100ns

Remarks:

Both values could be used to obtain current system time. This function is required to be called before calling CalcOperationTime function. The returned value should not be changed and need to be passed into CalcOperationTimefunction as reference.

Example:

dblmark = myobj.ObtainTimeMark(tuInterval100ns)

[in] [in] a. b. c. d.

typeOfTimeMark Needs to be the same type as used in ObtainTimeMark function unitOfMeasure Specifies unit of time measure. Could be TmuFrequency TmuInterval100ns TmuMilliseconds TmuSeconds

Example:

OpTime = myobj.CalcOperationTime (tuInterval100ns, tmuMilliseconds, dblmark)

[in]

CounterIndex

Counter index should be returned and stored by previous call to AddPredefinedCounterDefinition function.

Remarks:

Calling ClearCounter function will set specified counter to 0.

Example:

myobj.ClearCounter(c1)

[in] [in] a. b. c. [in]

CounterIndex Counter index should be returned and stored by previous call to AddPredefinedCounterDefinition function. updCmd Command specifies operation to perform on the counter. Choices are: CmdIncrement - increments counter by value pValue CmdDecrement - decrements counter by value pValue CmdSet - sets counter to value pValue pValue Value to be passed to the counter.

Remarks:

This is one of the main functions that perform all the work. After this function is called the System's performance database is updated and changes became viewable through performance monitor.

Example:

Call myobj.UpdateOneValueCounter(c2, cmdSet, MyValue)

[in] [in] [in]

CounterIndex Counter index should be returned and stored by previous call to AddPredefinedCounterDefinition function. pValue1 pValue2

Remarks:

UpdateTwoValueCounter function used to update counters that require two values. Usualy those are an "average" counters. Example of the counters where UpdateTwoValueCounter function needs to be used are: AvgBulkCounter, AvgTimeCounter. Counters themselves are responseible for caulculation proer value and updating System's performance database.

Example:

myobj.UpdateTwoValueCounter(c3, val1,val2)

Examples of the Code:

ASP Examples:

1. Using this snap of code you should be able to monitor real-time number of users visiting your page.

<%

Set myPefObj=Server.CreateObject("MagicPerf")
If Not myPefObj.DefineObjectType("f370c8f0-2031-11d4-ae08-0050dacfb789", myASPApp1","Test MagicPerf application", LevelExpert, True) Then
  Response.Write ("Error in DefineObjectType")
End If
cntNumber = myPefObj.AddPredefinedCounterDefinition("TotalHits", "Displays", NumberCounter, 1, 0, Null)
Call myPefObj.RegisterObjectType
Call myPefObj.UpdateOneValueCounter(cntNumber, cmdIncrement, 1)

%>

2. Using this code should show total number of simultaneous users accessing specific page at the same time.

3. Examples shows how long does it take for your page to get processed.

<%

Set myPefObj=Server.CreateObject("MagicPerf")
If Not myPefObj.DefineObjectType("f270c8f0-3031-12d4-ae08-0050dacfb773", "myASPApp4","Test MagicPerf application", LevelExpert, True) Then
    Response.Write("Error in DefineObjectType")
End If
cntNumber = myPefObj.AddPredefinedCounterDefinition("PageLoadTime2", "Displays Time ASP code takes to execute", NumberCounter, 1, 0, Null)

Call myPefObj.RegisterObjectType
timeMark = myPefObj.ObtainTimeMark(tuInterval100ns)
'your ASP and HTML code here --------------------------
for i=0 to 10000    'for loop is just our example
     j=1
next
'-----------------------------------------------
optime = myPefObj.CalcOperationTime(tuInterval100ns, tmuMilliseconds, timeMark)
Call myPefObj.UpdateOneValueCounter(cntNumber, cmdSet, optime)

%>

More examples for ASP, Visual Basic and Visual C++ are included in the download package.