winreg

Reads and writes the Windows registry.

This API is VFS-aware: it operates through the VFS in scope for the current strand, so it works transparently under remote or elevated contexts such as admin.with. It is supported only on Windows targets; elsewhere every operation throws sys.UnsupportedError.

Types

Type	Description
AccessMask	Access rights for a registry key.
Key	An open registry key.
LinkTarget	A registry link's target, kept in both its native and canonical forms.
Value	One named value read from a key.
AccessMaskSpec	Rights, given as an AccessMask, one right, or an iterable of rights.
AccessRight	A right of an AccessMask: a registry-specific right or composite, or a generic Windows AccessRight.
Data	Registry value data in its natural Do representation. See Value.value for how each value kind maps to it.
LinkResolution	How opening a key treats a registry link.
RegistryRoot	A registry root.
RegistryView	A registry view.
ValueKind	The kind of a stored registry value.

AccessMaskSpec = (AccessMask | AccessRight | Iterable[AccessRight])

Rights, given as an AccessMask, one right, or an iterable of rights.

AccessRight

@let AccessRight = $
  | :QUERY_VALUE:
  | :SET_VALUE:
  | :CREATE_SUB_KEY:
  | :ENUMERATE_SUB_KEYS:
  | :NOTIFY:
  | :CREATE_LINK:
  | :WOW64_64KEY:
  | :WOW64_32KEY:
  | :READ:
  | :WRITE:
  | :READ_WRITE:
  | security.windows.AccessRight

A right of an AccessMask: a registry-specific right or composite, or a generic Windows AccessRight.

Symbol	Meaning
:QUERY_VALUE:	Queries key values
:SET_VALUE:	Sets key values
:CREATE_SUB_KEY:	Creates subkeys
:ENUMERATE_SUB_KEYS:	Enumerates subkeys
:NOTIFY:	Receives change notifications
:CREATE_LINK:	Creates symbolic-link keys
:WOW64_64KEY:	Uses the 64-bit registry view
:WOW64_32KEY:	Uses the 32-bit registry view

Registry composites, the ones worth reaching for by default:

Symbol	Equivalent to
:READ:	Query values, enumerate subkeys, receive change notifications, and read security information
:WRITE:	Set values, create subkeys, and read security information
:READ_WRITE:	:READ: and :WRITE: together

Data

@let Data = $
  | Str
  | Array[Str]
  | Int
  | Bin
  | nil

Registry value data in its natural Do representation. See Value.value for how each value kind maps to it.

LinkResolution

How opening a key treats a registry link.

Type	Description
:TARGET:	Follow the link
:LINK:	Open the link key itself

RegistryRoot

A registry root.

Type	Description
:CLASSES_ROOT:	File associations and class settings
:CURRENT_USER:	Current user's profile
:LOCAL_MACHINE:	Computer-wide configuration
:USERS:	All user profiles
:CURRENT_CONFIG:	Current hardware profile

RegistryView

A registry view.

Type	Description
:NATIVE:	The target process's native registry view
:WOW32:	The 32-bit registry view
:WOW64:	The 64-bit registry view

ValueKind

The kind of a stored registry value.

Type	Description
:SZ:	UTF-16 string
:EXPAND_SZ:	Expandable UTF-16 string
:MULTI_SZ:	Sequence of UTF-16 strings
:DWORD:	Little-endian 32-bit integer
:DWORD_BIG_ENDIAN:	Big-endian 32-bit integer
:QWORD:	Little-endian 64-bit integer
:BINARY:	Raw bytes
:NONE:	No data

Functions

open root … -> Key ^{overload 1 of 2}

Opens a predefined registry root.

Parameters

Name	Type	Description
root	RegistryRoot	Registry root to open.
:view?	RegistryView	Registry view. Defaults to :NATIVE:.
:access?	AccessMaskSpec	Access rights. Defaults to :READ:.

Example

open :CURRENT_USER: do |root|
  echo (root.open("Environment").get "TEMP")

let root = open :LOCAL_MACHINE: access: :READ_WRITE:
root.close()

open[R] root func … -> R ^{overload 2 of 2}

Opens a registry root and calls func with it. The key is closed when func returns.

Parameters

Name	Type	Description
root	RegistryRoot	Registry root to open.
:view?	RegistryView	Registry view. Defaults to :NATIVE:.
:access?	AccessMaskSpec	Access rights. Defaults to :READ:.
func	((Key) -> R)	Called with the Key.