3.1.5.4 OpenPerformanceData (Opnum 3)

  • Article

The OpenPerformanceData method is called by the client. In response, the server opens a handle to the HKEY_PERFORMANCE_DATA predefined key. The HKEY_PERFORMANCE_DATA  predefined key is used to retrieve performance information from a registry server using only the BaseRegQueryInfoKey, BaseRegQueryValue, BaseRegEnumValue, and BaseRegCloseKey methods.

 error_status_t OpenPerformanceData(
   [in, unique] PREGISTRY_SERVER_NAME ServerName,
   [in] REGSAM samDesired,
   [out] PRPC_HKEY phKey
 );

ServerName: SHOULD be sent as NULL and MUST be ignored on receipt because the binding to the server is already complete at this stage.

samDesired: SHOULD be sent as 0 and MUST be ignored on receipt.

phKey: A pointer to an RPC context handle for the root key, HKEY_PERFORMANCE_DATA, as specified in section 3.1.1.7. The handle is found in the handle table (HANDLETABLE).

Return Values: The method returns 0 (ERROR_SUCCESS) to indicate success; otherwise, it returns a nonzero error code, as specified in [MS-ERREF] section 2.2. The server SHOULD return without modification any other error code encountered in servicing the client request.

The most common error codes are listed in the following table.

Return value/code

Description

0x00000005

ERROR_ACCESS_DENIED

Access is denied.

0x00000013

ERROR_WRITE_PROTECT

A read or write operation was attempted to a volume after it was dismounted. The server can no longer service registry requests because server shutdown has been initiated.

Server Operations

If the registry server can no longer service registry requests because server shutdown has been initiated (SHUTDOWNINPROGRESS is set to TRUE), the server MUST return ERROR_WRITE_PROTECT.

The server attempts to open the root key, HKEY_PERFORMANCE_DATA, and return a handle to that key in the phKey parameter. The server SHOULD<15> ignore the samDesired parameter and instead use a requested access of MAXIMUM_ALLOWED (see [MS-DTYP] section 2.4.3).

If the caller is permitted to open the key, the server MUST return 0 to indicate success, and create a new valid context handle. The server MUST store the context handle value in the handle table (HANDLETABLE) along with a mapping to the HKEY_PERFORMANCE_DATA  key. The server MUST place the handle value (see 3.1.1.9) in the phKey parameter. If the caller does not have access, the server MUST return ERROR_ACCESS_DENIED.