Performance Information Data Structures

[Previous] [Next]

At this point, the only item we have not covered is the format of the performance information that the Collect function must place into the caller's data block. Unfortunately, the data block contains a set of different data structures, some of which are variable in length, which makes building the contents of this data buffer difficult at best. Figure 7-9 shows how the performance information is laid out for an object.

Although this particular object doesn't support instances, it does support two counters. This means that three string entries exist in the registry for this object: one string identifies the object name and was assigned a value of 2938; two other strings identify the counter names and were assigned the values 2940 and 2942. The Help strings for these three items are 2939, 2941, and 2943, respectively.

click to view at full size.

Figure 7-9. Data buffer describing a performance object that does not support instances

To report performance information for this object, the data block passed to our Collect function must first have a PERF_OBJECT_TYPE structure placed into it. Since the Platform SDK documentation provides details of this structure's members, I'll describe them just briefly in Table 7-1.

Table 7-1. Members of the PERF_OBJECT_TYPE structure

Member Description
TotalByteLength
DefinitionLength
HeaderLength
Indicate byte sizes. These values must be initialized correctly so that a tool such as the System Monitor control can walk the data block properly.
ObjectNameTitleIndex
ObjectHelpTitleIndex
Indicate the numbers that were assigned to the object text and its Help when they were added to the registry.
ObjectNameTitle
ObjectHelpTitle
Should always be set to NULL because these members are used only by the application requesting the data.
DetailLevel Indicates how "hard to understand" this object is to most users. Most objects are understandable to novice users. But you can say that your object is best understood by novice, advanced, expert, or wizard users.
NumCounters Indicates how many counters the object offers. In Figure 7-9, the object offers two counters and therefore has two PERF_COUNTER_DEFINITION structures immediately following this PERF_OBJECT_TYPE structure. (I'll discuss the PERF_COUNTER_DEFINITION structures shortly.)
DefaultCounter When an object is selected, this member indicates which counter should be selected by default in the Counters list box. The System Monitor control's Add Counter dialog box uses this member.
NumInstances Indicates how many instances the object currently has. In Figure 7-9, the object doesn't support instances, so PERF_NO_INSTANCES (-1) is returned.
CodePage If the object supports instances, each instance is returned as a string name. It's best to return the instance name as a Unicode string, so set this member to 0. However, if you prefer to return non-Unicode strings, set this member to the CodePage used for the instance string name.
PerfTime
PerfFreq
Should always be set to 0 because these members are only used by the application requesting the data.

Immediately following the PERF_OBJECT_TYPE structure is one or more PERF_COUNTER_DEFINITION structures, one structure for each counter offered by the object. Table 7-2 offers a brief description of this structure's members.

Table 7-2. Members of the PERF_COUNTER_DEFINITION structure

Member Description
ByteLength Length in bytes of this structure. Used for walking the memory block.
CounterNameTitleIndex
CounterHelpTitleIndex
Indicate the numbers that were assigned to the counter text and its Help when they were added to the registry.
CounterNameTitle
CounterHelpTitle
Should always be set to NULL because these members are used only by the application requesting the data.
DefaultScale Power of 10 by which to scale chart line, assuming vertical axis is 100 (0 specifies a scale value of 1, 1 specifies a scale value of 10, -1 specifies a scale value of 1/10, and so on).
DetailLevel Indicates how "hard to understand" this counter is to most users. Most counters are understandable to novice users. But you can say that your counter is best understood by novice, advanced, expert, or wizard users.
CounterType Type of counter. (See the WinPerf.h header file for a description.)
CounterSize Number of bytes used for counter information (usually 4 or 8).
CounterOffset Offset from the start of the PERF_COUNTER_BLOCK to the first byte of this counter.

Each PERF_COUNTER_DEFINITION structure defines characteristics of a single counter, but the actual value of the counter is not returned inside one of these structures. Following the PERF_OBJECT_TYPE structure and all the PERF_COUNTER_DEFINITION structures comes a single PERF_COUNTER_BLOCK structure. PERF_COUNTER_BLOCK is a variablelength structure. The first member, ByteLength, indicates how many bytes are in the variable-length structure. (This number must include the 4 bytes for the ByteLength member itself.) Immediately following the ByteLength member come the counter values. It is critically important that each new value is aligned on a 32-bit boundary, or data misalignment exceptions might occur.

Inside the PERF_COUNTER_DEFINITION structure, the CounterSize member indicates how many bytes are used by the counter value, and the CounterOffset member indicates the offset of where the counter value is inside the PERF_COUNTER_BLOCK structure.

Figure 7-10 shows how the performance information is laid out for an object that supports instances. This particular object offers one counter for each instance and currently has two instances defined. Because just one counter is defined, only two string entries exist in the registry for this object: one string identifies the object name and is assigned a value of 2944; the other string identifies the counter name and is assigned a value of 2946. The Help strings for the object and counter are 2945 and 2947, respectively.

click to view at full size.

Figure 7-10. Data buffer describing a performance object with two instances. All counter values for all instances are in the buffer.

The beginning of this memory block is laid out just like the previous example: it begins with a PERF_OBJECT_TYPE structure followed by one PERF_COUNTER_DEFINITION for every counter offered by the object. However, this is where the similarity ends. Since this object supports instances, the PERF_COUNTER_DEFINITION structures are followed by one PERF_INSTANCE_DEFINITION structure for each instance currently existing for the object. Table 7-3 gives a brief description of the members of the PERF_INSTANCE_DEFINITION structure.

Table 7-3. Members of the PERF_INSTANCE_DEFINITION structure

Member Description
ByteLength Length in bytes of this structure. Used for walking the memory block.
ParentObjectTitleIndex An object instance can be the child of another object or instance; for example, threads are children of a process. If the instance has a parent, this number identifies the parent object's assigned registry number (0 = no parent).
ParentObjectInstance If this instance has a parent, this number identifies the parent instance's index relative to the parent object.
UniqueID An instance can be identified by a number or by a string name. If you want to use a number, set this member to the number and set NameOffset and NameLength to 0. If you want to use a string name, set this member to -1 and set the NameOffset and NameLength members appropriately.
NameOffset Number of bytes from the beginning of the structure to this instance's Unicode string name.
NameLength Number of bytes (not characters) of this instance's Unicode string name. (Add 2 bytes for the terminating zero character.)

Immediately following the fixed-length portion of the PERF_INSTANCE_DEFINITION structure is the variable-length portion. This portion contains the Unicode string name for the instance, terminated with a zero character. If the name contains an odd number of characters (including the zero character), you must add another 2 bytes of padding so that the next PERF_INSTANCE_DEFINITION or PERF_COUNTER_BLOCK structure begins on a 32-bit boundary. If the instance name is an even number of characters, no padding is required.



Programming Server-Side Applications for Microsoft Windows 2000
Programming Server-Side Applications for Microsoft Windows 2000 (Microsoft Programming)
ISBN: 0735607532
EAN: 2147483647
Year: 2000
Pages: 126

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net