The Open Function

The system calls the Open function whenever an application first connects to the registry to collect performance data. This function performs the initialization required for the application to provide performance data.

Use the following function prototype for your Open function.

DWORD CALLBACK OpenPerformanceData(LPWSTR lpDeviceNames);
 

The name OpenPerformanceData is a place-holder for an application-defined name. The lpDeviceNames argument points to a buffer containing the Unicode strings stored in the Export value in the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
Application_Name\Linkage

The strings are REG_MULTI_SZ strings, separated by a UNICODE_NULL, and terminated by two UNICODE_NULL characters. If this entry does not exist, lpDeviceNames should be NULL. The strings are the names of the devices managed by this application. The Open function should call the CreateFile function to open a handle to each device named. If CreateFile fails, the Open function should return the error code returned by the GetLastError function; otherwise, it should return ERROR_SUCCESS.

The Open function initializes the data structures it returns to the performance monitor application. In particular, it examines the registry to get the Counter and Help indices of the objects and counters supported by the application. It then stores these indices in the appropriate members of the PERF_OBJECT_TYPE and PERF_COUNTER_DEFINITION structures.

Other initialization tasks that might be performed by the Open function include the following:

• Open and map a file mapping object used by the program to store performance data. Create a mutex to prevent the application from changing a value while the performance DLL is reading it. This is one way to communicate performance data from the application to the performance DLL. If you are using another form of interprocess communication, substitute the appropriate steps to initialize that mechanism.
• Initialize event logging, if the DLL uses event logging to report errors. This is the only way for the performance DLL to report error conditions to the user, other than through a debugger. For more information, see Event Logging.
• Initialize the object and counter indexes. This must be done each time the performance DLL is loaded, because the indices vary from machine to machine.
• Perform other initialization tasks necessary for the Collect function to collect performance data efficiently.

The Open function should write any error that prevents the function from completing successfully in the system event log.