Share via

3.1.5.27 BaseRegSaveKeyEx (Opnum 31)

  • Article

The BaseRegSaveKeyEx method is called by the client. In response, the server saves the specified key, subkeys, and values to a new file. The BaseRegSaveKeyEx method accepts flags that determine the format for the saved key or and values.

 error_status_t BaseRegSaveKeyEx(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpFile,
   [in, unique] PRPC_SECURITY_ATTRIBUTES pSecurityAttributes,
   [in] DWORD Flags
 );

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 file in which the specified key and subkeys are saved. The format of the file name is implementation-specific.

pSecurityAttributes: A pointer to an RPC_SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new file. If the pSecurityAttributes parameter is NULL, the file receives a default security descriptor.

Flags: Specifies the format for the saved key. This MUST be one of the following values.

Value

Meaning

1

The key or subtree is saved in the original format.

2

The key or subtree is saved in the latest format.

4

The key or subtree is saved without compression.

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 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.

0x00000005

ERROR_ACCESS_DENIED

The server does not have access permissions to save the file at the specified location.

0x000000B7

ERROR_ALREADY_EXISTS

Cannot create a file when that file already exists.

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_PARAMETER:

  • HKEY_PERFORMANCE_DATA

  • HKEY_PERFORMANCE_TEXT

  • HKEY_PERFORMNACE_NLTEXT

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 server does not have access permissions to save in the location indicated by the lpFile parameter, the server MUST fail the method and return ERROR_ACCESS_DENIED.

 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 inspect the value of the Flags parameter to determine the format of the saved registry file. If the value of the Flags parameter is set to 1, the keys and values MUST be saved in the server's original file format. If the value of the Flags parameter is set to 2, the keys and values MUST be saved in the server's latest format. If the value of the Flags parameter is set to 4, the keys and values MUST be saved in an uncompressed format. Each of these file format types are implementation-dependent.

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 references a file that already exists and for which the specified key and subkeys are to be saved, the server MUST return ERROR_ALREADY_EXISTS.