3.1.5.22 BaseRegSetValue (Opnum 22)

The BaseRegSetValue method is called by the client. In response, the server sets the data for the specified value of a registry key.

 error_status_t BaseRegSetValue(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpValueName,
   [in] DWORD dwType,
   [in, size_is(cbData)] LPBYTE lpData,
   [in] DWORD cbData
 );

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.

lpValueName: MUST be a pointer to an RRP_UNICODE_STRING structure that contains the name of the value (as specified in section 3.1.1.5) to set.

dwType: The type of data to be stored. This MUST be one of the REG_VALUE_TYPE values specified in section 3.1.1.5.

lpData: A pointer to a buffer that contains the data to set for the value entry.

cbData: The length in bytes of the information to be stored.

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
0x00000005 ERROR_ACCESS_DENIED	The caller does not have KEY_SET_VALUE access rights, or the value being set to a symbolic key is not the literal string "SymbolicLinkValue".
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 set the data that is associated with the specified value and registry key.

If the lpValueName parameter in the client request is NULL or an empty string, the server MUST set the data that is associated with the default value of the specified key, as specified in section 3.1.1.5.

If lpValueName is not NULL, the server MUST remove any terminating null characters from the value name before storing the value name on the server.

If the key specified by hKey has a KEYTYPE of symbolic link and lpValueName is specified to any string other than "SymbolicLinkValue", the server MUST fail the method and return ERROR_ACCESS_DENIED.

The server MUST set the type of the information that is stored based on the value that is specified in the dwType parameter. The value of dwType MUST be one of the values that are specified in REG_VALUE_TYPE, or NULL.

The server MUST set the data for the value by using the data in the buffer that is pointed to by the lpData parameter.

The client MUST specify the length, in bytes, to copy from the buffer in the cbData parameter. This MUST be set to 0 if no data needs to be copied from the lpData parameter.

The server MUST determine if the key path indicated by hKey refers to a path that is within the list of paths for which updates to either the 32-bit or 64-bit namespaces are copied into the 64-bit or 32-bit namespace, respectively, as specified in section 3.1.1.4. If the key indicated by hKey is within one of the paths, the server MUST set the UPDATECOPY column of the HANDLETABLE for the row indicated by hKey to TRUE. This indicates that the value is copied between the 32-bit and 64-bit key namespaces when the handle is closed.

The server MUST set the KEYISMODIFIED property of the key indicated by hKey to TRUE.

The caller MUST have KEY_SET_VALUE access rights to invoke this method. Otherwise, the server MUST fail the method and return ERROR_ACCESS_DENIED. For more information, see section 2.2.4.

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

If the parameter lpValueName is NULL, the server MUST return ERROR_INVALID_PARAMETER.

If the parameter lpValueName is greater than zero and the buffer is NULL, the server MUST return ERROR_INVALID_PARAMETER.