3.1.4.2.33 ApiSetValue (Opnum 32)

(Protocol Version 3) In response to the ApiSetValue request from the client, the server MUST set the data that is associated with the specified value and cluster registry key.

The server MUST accept an ApiSetValue request only if its protocol server state is read/write, as specified in section 3.1.1.

The server MUST require that the client have a security access level of "All" (section 3.1.4).

 error_status_t ApiSetValue(
   [in] HKEY_RPC hKey,
   [in, string] LPCWSTR lpValueName,
   [in] DWORD dwType,
   [in, size_is(cbData)] const UCHAR *lpData,
   [in] DWORD cbData,
   [out] error_status_t *rpc_status
 );

hKey: The RPC context handle for a key that was previously obtained by a call to ApiGetRootKey, ApiCreateKey, or ApiOpenKey.

lpValueName: A null-terminated string that is the name of the value to set, as specified in [MS-RRP]. If this parameter is set to NULL or an empty string, the server MUST set the value to the default value of the specified key, as specified in [MS-RRP]. If the specified value name is not present, the server MUST create it.

dwType: The type of data to be stored as one of the following values. A server SHOULD support all of the following values.

Value	Meaning
REG_NONE 0x00000000	No defined value type.
REG_SZ 0x00000001	A null-terminated Unicode string.
REG_EXPAND_SZ 0x00000002	A null-terminated Unicode string that contains unexpanded references to environment variables.
REG_BINARY 0x00000003	Binary data in any form.
REG_DWORD 0x00000004	A 32-bit unsigned integer, as defined in[MS-DTYP] section 2.2.9.
REG_MULTI_SZ 0x00000007	An array of null-terminated Unicode strings that are terminated by two NULL characters, as defined in [MS-RRP] section 2.2.5.
REG_QWORD 0x0000000B	A 64-bit unsigned integer, as defined in [MS-DTYP] section 2.2.40.

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

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

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether the runtime succeeded in executing this method on the server. A value of 0x00000000 indicates that the method call was successfully transported to the server, executed with no faults, and returned control to the client without encountering any communication faults. This value is separate from the value returned by the method and does not represent the success of the method. The client MUST treat all nonzero values the same, except as specified in section 3.2.4.6.

Return Values: On success, the method returns 0x00000000 (ERROR_SUCCESS).

For any other condition, the server MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table, except as specified in section 3.2.4.6.