def set_value(hive,
key,
vname=None,
vdata=None,
vtype='REG_SZ',
use_32bit_registry=False,
volatile=False):
'''
Sets a registry value entry or the default value for a key.
:param str hive: The name of the hive. Can be one of the following
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
:param str key: The key (looks like a path) to the value name.
:param str vname: The value name. These are the individual name/data pairs
under the key. If not passed, the key (Default) value will be set.
:param object vdata: The value data to be set.
What the type of this parameter
should be is determined by the value of the vtype
parameter. The correspondence
is as follows:
.. glossary::
REG_BINARY
binary data (i.e. str in python version < 3 and bytes in version >=3)
REG_DWORD
int
REG_EXPAND_SZ
str
REG_MULTI_SZ
list of objects of type str
REG_SZ
str
:param str vtype: The value type.
The possible values of the vtype parameter are indicated
above in the description of the vdata parameter.
:param bool use_32bit_registry: Sets the 32bit portion of the registry on
64bit installations. On 32bit machines this is ignored.
:param bool volatile: When this parameter has a value of True, the registry key will be
made volatile (i.e. it will not persist beyond a system reset or shutdown).
This parameter only has an effect when a key is being created and at no
other time.
:return: Returns True if successful, False if not
:rtype: bool
CLI Example:
.. code-block:: bash
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2'
This function is strict about the type of vdata. For instance the
the next example will fail because vtype has a value of REG_SZ and vdata
has a type of int (as opposed to str as expected).
CLI Example:
.. code-block:: bash
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_SZ vdata=0
However, this next example where vdata is properly quoted should succeed.
CLI Example:
.. code-block:: bash
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_SZ vdata="'0'"
An example of using vtype REG_BINARY is as follows:
CLI Example:
.. code-block:: bash
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_BINARY vdata='!!binary d2hhdCdzIHRoZSBwb2ludA=='
An example of using vtype REG_LIST is as follows:
CLI Example:
.. code-block:: bash
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_LIST vdata='[a,b,c]'
'''
local_hive = _to_unicode(hive)
local_key = _to_unicode(key)
local_vname = _to_unicode(vname)
local_vtype = _to_unicode(vtype)
registry = Registry()
hkey = registry.hkeys[local_hive]
vtype_value = registry.vtype[local_vtype]
access_mask = registry.registry_32[use_32bit_registry] | win32con.KEY_ALL_ACCESS
# Check data type and cast to expected type
# int will automatically become long on 64bit numbers
# https://www.python.org/dev/peps/pep-0237/
# String Types to Unicode
if vtype_value in [1, 2]:
local_vdata = _to_unicode(vdata)
# Don't touch binary...
elif vtype_value == 3:
local_vdata = vdata
# Make sure REG_MULTI_SZ is a list of strings
elif vtype_value == 7:
local_vdata = [_to_unicode(i) for i in vdata]
# Everything else is int
else:
local_vdata = int(vdata)
if volatile:
create_options = registry.opttype['REG_OPTION_VOLATILE']
else:
create_options = registry.opttype['REG_OPTION_NON_VOLATILE']
try:
handle, _ = win32api.RegCreateKeyEx(hkey, local_key, access_mask,
Options=create_options)
win32api.RegSetValueEx(handle, local_vname, 0, vtype_value, local_vdata)
win32api.RegFlushKey(handle)
win32api.RegCloseKey(handle)
broadcast_change()
return True
except (win32api.error, SystemError, ValueError, TypeError) as exc: # pylint: disable=E0602
log.error(exc, exc_info=True)
return False
def set_value(
hive,
key,
vname=None,
vdata=None,
vtype="REG_SZ",
use_32bit_registry=False,
volatile=False,
):
"""
Sets a value in the registry. If ``vname`` is passed, it will be the value
for that value name, otherwise it will be the default value for the
specified key
Args:
hive (str):
The name of the hive. Can be one of the following
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
key (str):
The key (looks like a path) to the value name.
vname (str):
The value name. These are the individual name/data pairs under the
key. If not passed, the key (Default) value will be set.
vdata (str, int, list, bytes):
The value you'd like to set. If a value name (vname) is passed, this
will be the data for that value name. If not, this will be the
(Default) value for the key.
The type of data this parameter expects is determined by the value
type specified in ``vtype``. The correspondence is as follows:
- REG_BINARY: Binary data (str in Py2, bytes in Py3)
- REG_DWORD: int
- REG_EXPAND_SZ: str
- REG_MULTI_SZ: list of str
- REG_QWORD: int
- REG_SZ: str
.. note::
When setting REG_BINARY, string data will be converted to
binary. You can pass base64 encoded using the ``binascii``
built-in module. Use ``binascii.b2a_base64('your data')``
.. note::
The type for the (Default) value is always REG_SZ and cannot be
changed.
.. note::
This parameter is optional. If not passed, the Key will be
created with no associated item/value pairs.
vtype (str):
The value type. The possible values of the vtype parameter are
indicated above in the description of the vdata parameter.
use_32bit_registry (bool):
Sets the 32bit portion of the registry on 64bit installations. On
32bit machines this is ignored.
volatile (bool):
When this parameter has a value of True, the registry key will be
made volatile (i.e. it will not persist beyond a system reset or
shutdown). This parameter only has an effect when a key is being
created and at no other time.
Returns:
bool: True if successful, otherwise False
Usage:
This will set the version value to 2015.5.2 in the SOFTWARE\\Salt key in
the HKEY_LOCAL_MACHINE hive
.. code-block:: python
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='version', vdata='2015.5.2')
Usage:
This function is strict about the type of vdata. For instance this
example will fail because vtype has a value of REG_SZ and vdata has a
type of int (as opposed to str as expected).
.. code-block:: python
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='str_data', vdata=1.2)
Usage:
In this next example vdata is properly quoted and should succeed.
.. code-block:: python
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='str_data', vdata='1.2')
Usage:
This is an example of using vtype REG_BINARY. Both ``set_value``
commands will set the same value ``Salty Test``
.. code-block:: python
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='bin_data', vdata='Salty Test', vtype='REG_BINARY')
import binascii
bin_data = binascii.b2a_base64('Salty Test')
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='bin_data_encoded', vdata=bin_data, vtype='REG_BINARY')
Usage:
An example using vtype REG_MULTI_SZ is as follows:
.. code-block:: python
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='list_data', vdata=['Salt', 'is', 'great'], vtype='REG_MULTI_SZ')
"""
local_hive = _to_unicode(hive)
local_key = _to_unicode(key)
local_vname = _to_unicode(vname)
local_vtype = _to_unicode(vtype)
registry = Registry()
try:
hkey = registry.hkeys[local_hive]
except KeyError:
raise CommandExecutionError("Invalid Hive: {}".format(local_hive))
vtype_value = registry.vtype[local_vtype]
access_mask = registry.registry_32[
use_32bit_registry] | win32con.KEY_ALL_ACCESS
local_vdata = cast_vdata(vdata=vdata, vtype=local_vtype)
if volatile:
create_options = registry.opttype["REG_OPTION_VOLATILE"]
else:
create_options = registry.opttype["REG_OPTION_NON_VOLATILE"]
handle = None
try:
handle, result = win32api.RegCreateKeyEx(hkey,
local_key,
access_mask,
Options=create_options)
msg = ("Created new key: %s\\%s"
if result == 1 else "Opened existing key: %s\\%s")
log.debug(msg, local_hive, local_key)
try:
win32api.RegSetValueEx(handle, local_vname, 0, vtype_value,
local_vdata)
win32api.RegFlushKey(handle)
broadcast_change()
return True
except TypeError as exc:
log.exception('"vdata" does not match the expected data type.\n%s',
exc)
return False
except (SystemError, ValueError) as exc:
log.exception("Encountered error setting registry value.\n%s", exc)
return False
except win32api.error as exc:
log.exception(
"Error creating/opening key: %s\\%s\n%s",
local_hive,
local_key,
exc.winerror,
)
return False
finally:
if handle:
win32api.RegCloseKey(handle)
