OpenPerformanceData callback function
Performs the initialization required by your performance DLL. Implement and export this function if you are writing a performance DLL to provide performance data. The system calls this function whenever a consumer first connects to the registry to collect performance data.
The OpenPerformanceData function is a placeholder for the application-defined function name.
Syntax
DWORD APIENTRY OpenPerformanceData(
LPWSTR pContext
);
Parameters
- pContext
The pContext parameter contains one or more strings stored in the Export registry value. The strings are separated by a UNICODE_NULL and terminated by two UNICODE_NULL characters. If this entry does not exist, pContext is NULL. For details on setting the Export registry value, see Creating Other Registry Entries.
Return value
If successful, return ERROR_SUCCESS. Otherwise, return the appropriate error code.
If you do not return ERROR_SUCCESS, the system will no longer call your OpenPerformanceData function. The system also posts an error event in Application Event Log for later reference (the data section contains the return value).
If the error is recoverable, you should consider returning ERROR_SUCCESS and trying the initialization process again from your CollectPerformanceData function.
Remarks
This function should perform the initialization tasks necessary for the CollectPerformanceData function to collect performance data efficiently.
Typically, this function initializes the data structures that it returns to the consumer. In particular, it retrieves index values for its performance objects and counters from the registry and stores these indexes in the appropriate members of the PERF_OBJECT_TYPE and PERF_COUNTER_DEFINITION structures.
To get the counter and help index values for your objects and counters, query the First Counter and First Help registry values under your application's Performance key located at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\application-name.
The first counter index value maps directly to the first symbolic constant value in your symbolic constant header file. (The symbolic constant header file is the header file that you used to load your counters on the computer. For details, see Adding Counter Names and Descriptions to the Registry.) The order of the constants should match the order of the objects and counters that you return in the performance data.
If you are managing devices, the pContext parameter should contain the names of the devices that you manage. The OpenPerformanceData function should call the CreateFile function to open a handle to each device. If CreateFile fails, the OpenPerformanceData function should return the error code returned by the GetLastError function; otherwise, it should return ERROR_SUCCESS.
If the consumer is running on another computer (remotely), then the extensible counter functions are called in the context of the Winlogon process, which handles the server side of the remote connection. This distinction is important when troubleshooting problems that occur only remotely.
Examples
For an example, see Implementing OpenPerformanceData.
Requirements
Minimum supported client |
Windows XP [desktop apps only] |
Minimum supported server |
Windows Server 2003 [desktop apps only] |
Header |
Winperf.h |