Platform SDK: Performance Monitoring

PDH_BROWSE_DLG_CONFIG

The PDH_BROWSE_DLG_CONFIG structure is used by the PdhBrowseCounters function to configure the PDH Browse Counters dialog box.

typedef struct _BrowseDlgConfig {
  // Configuration flags
  DWORD   bIncludeInstanceIndex:1,
          bSingleCounterPerAdd:1,
          bSingleCounterPerDialog:1,
          bLocalCountersOnly:1,
          bWildCardInstances:1,
          bHideDetailBox:1,
          bInitializePath:1,
          bDisableMachineSelection:1,
          bIncludeCostlyObjects:1,
          bReserved:23;

  HWND                hWndOwner;
  LPTSTR              szDataSource;
  LPTSTR              szReturnPathBuffer;
  DWORD               cchReturnPathLength;
  CounterPathCallBack pCallBack;
  DWORD_PTR           dwCallBackArg;
  PDH_STATUS          CallBackStatus;
  DWORD               dwDefaultDetailLevel;
  LPTSTR              szDialogBoxCaption;
} PDH_BROWSE_DLG_CONFIG, *PPDH_BROWSE_DLG_CONFIG;

Members

bIncludeInstanceIndex

If this flag is TRUE, the returned counter path will include the instance index for the instance. If this flag is FALSE, the returned counter path will not contain an instance number.

bSingleCounterPerAdd

If this flag is TRUE, multiple and wildcard selections are permitted. Selected counters are returned as a MULTI_SZ string each time the Add button is clicked. If this flag is FALSE, multiple selections are not permitted. Only one counter will be returned each time the Add button is clicked.

bSingleCounterPerDialog

If this flag is TRUE, the dialog box is closed after the Add button is clicked the first time. Therefore, you can only add a single counter. If this flag is FALSE, the dialog box is not closed until the Close button is clicked. The Add button can be clicked multiple times.

bLocalCountersOnly

If this flag is TRUE, the machine name will not prefix the counter path in the returned string. If this flag is FALSE, the machine name will prefix the counter path unless the user selects the Local Counters Only radio button.

bWildCardInstances

If this flag is TRUE and a wildcard instance (for example, ALL) is selected, the returned counter path will include the wild-card syntax (for example, "*") for the instance field.

If this flag is FALSE, and All Instances has been selected, all the instances currently found for that object will be returned in a MULTI_SZ string.

bHideDetailBox

If this flag is TRUE, this removes the Detail Level combo box from the dialog box so the user cannot change the detail level of the counters displayed in the dialog box. The detail level will be fixed to the value of the dwDefaultDetailLevel member.

If this flag is FALSE, this displays the Detail Level combo box in the dialog box, allowing the user to change the detail level of the counters displayed.

Note that the counters displayed will be those whose detail level is less than or equal to the current detail level selection. Selecting a detail level of Wizard will display all counters and objects.

bInitializePath

If this flag is TRUE, the counter and object are selected based on the first counter path contained in the szReturnPathBuffer member when the dialog box is first displayed, instead of using the default counter and object specified by the machine.

If this flag is FALSE, this selects the initial counter and object using the default counter and object information returned by the machine.

bDisableMachineSelection

If this flag is TRUE, the Computer drop-down list cannot be selected.

If this flag is FALSE, the Computer drop-down list can be selected. This is the default value.

bIncludeCostlyObjects

If this flag is TRUE, performance objects returning costly data—that is, data that requires a relatively large amount of processor time or memory overhead to collect—are listed for selection.

If this flag is FALSE, performance objects returning costly data are not listed for selection. This is the default value.

hWndOwner

A handle to the calling function's window.

szDataSource

A pointer to a null-terminated string containing either the name of a log file or the null termination only. If you specify the name of a log file, performance data will be taken from that log file. If this parameter contains a null string, performance data will be collected from a real-time data source.

szReturnPathBuffer

A pointer to a null-terminated string containing the name of the buffer, allocated by the caller, that is used to initialize the first selection in the list boxes (bInitializePath == TRUE) and to return the selected counters to the calling function or the callback procedure.

cchReturnPathLength

The current maximum size, in characters, of the buffer referenced by the szReturnPathBuffer member. If the callback function reallocates a new buffer, it must also update this value.

pCallBack

The address of the callback function used to update application buffers and controls when a multiple-selection dialog box is configured. For more information, see CounterPathCallback.

dwCallBackArg

User-defined argument that is passed as the only argument to the callback function when it is called by the dialog box.

CallBackStatus

On entry to the callback function, this member contains the status of the path buffer. On exit, the callback function sets the status value resulting from processing.

If the buffer is too small to load the current selection, the browser will set this value to PDH_MORE_DATA. If the browser sets this member to ERROR_SUCCESS, then the szReturnPathBuffer member contains a valid counter path or counter path list.

If the callback function reallocates a new buffer, it should set this member to PDH_RETRY so that the browser will try to load the buffer with the selected paths and call the callback function again.

If some other error occurred, then the callback function should return the appropriate PDH error status value.

dwDefaultDetailLevel

The default detail level to show on startup in the Detail Level combo box. If the Detail Level combo box is not shown, this is the detail level to use in filtering the displayed performance counters and objects.

szDialogBoxCaption

A pointer to a null-terminated string containing the optional caption to be displayed in the caption bar of the PDH Browse Counters dialog box. If this member is NULL, the caption will be Browse Performance Counters.

Remarks

Each time the Add button is clicked, the szReturnPathBuffer buffer contains the selected counter and the pCallBack callback function is called. The callback function should call the PdhAddCounter function for each counter in the buffer.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Header: Declared in Pdh.h.
  Unicode: Declared as Unicode and ANSI structures.

PDH_BROWSE_DLG_CONFIG

Members

Remarks

Requirements

See Also