3.1.5.20 BaseRegSaveKey (Opnum 20)

  • Article

The BaseRegSaveKey method is called by the client. In response, the server saves the specified key, subkeys, and values to a new file.

 error_status_t BaseRegSaveKey(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpFile,
   [in, unique] PRPC_SECURITY_ATTRIBUTES pSecurityAttributes
 );

hKey: A handle to a key that MUST have been opened previously by using one of the open methods that are specified in section 3.1.5: OpenClassesRoot, OpenCurrentUser, OpenLocalMachine, OpenPerformanceData, OpenUsers, BaseRegCreateKey, BaseRegOpenKey, OpenCurrentConfig, OpenPerformanceText, OpenPerformanceNlsText.

lpFile: A pointer to an RRP_UNICODE_STRING structure that contains the name of the registry file in which the specified key and subkeys are to be saved. The format of the file name SHOULD<26> be implementation-specific.

pSecurityAttributes: A pointer to an RPC_SECURITY_ATTRIBUTES structure.

Return Values: The method returns 0 (ERROR_SUCCESS) to indicate success; otherwise, it returns a nonzero error code, as specified in either [MS-ERREF] section 2.2 or [MS-ERREF] section 2.3.1. The most common error codes are listed in the following table.

Return value/code

Description

0x00000057

ERROR_INVALID_PARAMETER

A parameter is incorrect.

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.

In response to this request from the client, for a successful operation, the server MUST save the key, subkeys, and values of the keys that are specified in the hKey parameter to the file that is specified in the lpFile parameter of the request.

If the key indicated by hKey refers to, or is a subkey of, one of the following predefined keys, the server MUST fail the method and return ERROR_INVALID_HANDLE:

  • HKEY_PERFORMANCE_DATA

  • HKEY_PERFORMANCE_TEXT

  • HKEY_PERFORMANCE_NLSTEXT

If the key indicated by hKey refers to one of the following predefined keys, the server MUST fail the method and return ERROR_ACCESS_DENIED:

  • HKEY_USERS

  • HKEY_LOCAL_MACHINE

If the file indicated by lpFile already exists, the server MUST fail the method and return ERROR_ALREADY_EXISTS.

The server MUST set the SECURITY_DESCRIPTOR on this file based on the RPC_SECURITY_ATTRIBUTES that are specified in the pSecurityAttributes parameter. If this parameter is NULL, the server MUST use the default SECURITY_DESCRIPTOR.

The server MUST return 0 to indicate success or an appropriate error code (as specified in [MS-ERREF]) to indicate an error.

If the parameter lpFile is NULL or references a buffer that is NULL, the server MUST return ERROR_INVALID_PARAMETER.

If the parameter pSecurityAttributes is not a security descriptor as specified in [MS-DTYP] section 2.4.6, the function MUST return ERROR_INVALID_PARAMETER.