13 Windows Registry

▼ |  | File: Racket File and Format Libraries

1 | Convertible: Data-Conversion Protocol
2 | gzip Compression and File Creation
3 | gzip Decompression
4 | zip File Creation
5 | zip File Extraction
6 | tar File Creation
7 | tar File Extraction
8 | tar+gzip File Extraction
9 | MD5 Message Digest
10 | SHA1 Message Digest
11 | GIF File Writing
12 | ICO File Reading and Writing
13 | Windows Registry
14 | Caching
15 | Globbing
| Bibliography
| Index

On this page:

get-resource
write-resource

top contents ← prev up next →

### 13`` Windows Registry🔗ℹ

(require file/resource) | package: base

> > procedure
> > (get-resource |  | section |
> > |  | entry |
> > | [ | value-box |
> > |  | file |
> > |  | #:type type]) |
> → (or/c #f string? bytes? exact-integer? #t)
> section : string?
> entry : string?
> | value-box |  | : |  | (or/c #f (box/c (or/c string? bytes? exact-integer?)))
> |  |  | = |  | #f
> file : (or/c #f path-string?) = #f
> | type |  | : |  | (or/c 'string 'string/utf-16 'bytes 'bytes* 'integer)
> |  |  | = |  | derived-from-value-box

Gets a value from the Windows registry or an ".ini" file. For backward compatibility, the result is #f for platforms other than Windows. The registry is read when file is #f and when section is "HKEY_CLASSES_ROOT", "HKEY_CURRENT_CONFIG", "HKEY_CURRENT_USER", "HKEY_LOCAL_MACHINE", or "HKEY_USERS". When file is #f and section is not one of the special registry strings, then (build-path (find-system-path 'home-dir) "mred.ini") is read.

The resource value is keyed on the combination of section and entry. The result is #f if no value is found for the specified section and entry. If value-box is a box, then the result is #t if a value is found, and the box is filled with the value; when value-box is #f, the result is the found value.

Registry values of any format can be extracted. A combination of the type argument and the type of the resource determines how the resource is initially converted to a Racket value:

- A REG_SZ registry value’s bytes are first converted to a string by a nul-terminated UTF-16 interpretation (not including the terminator in the string)—unless type is 'bytes*, in which case the bytes are kept as-is in a byte string.

- A REG_DWORD registry value’s bytes are first interpreted as a 32-bit signed integer, and then the integer is converted to a string with number->string.

- Any other kind of register value’s bytes are kept as a byte string.

That initial conversion produces either a string or a byte string. The requested type might then trigger an additional transformation:

- 'string: a string is kept as-is, but a byte string are converted to a string using bytes->string/utf-8. Note that a UTF-8 conversion is not appropriate for some resource types, such as REG_EXPAND_SZ; use 'string/utf-16, instead.

- 'string/utf-16: a string is kept as-is, but a byte string is converted to a string by a nul-terminated UTF-16 interpretation (omitting the nul terminator from the string).

- 'bytes: a byte string is kept as-is, but a string is converted using string->bytes/utf-8. Note that this conversion does not produce the original bytes for a REG_SZ resource; use 'bytes*, instead, since that avoids the initial conversion to a string.

- 'bytes*: the same as 'bytes, but 'bytes* affects the initial conversion for a REG_SZ resource.

- 'integer: a string is converted to a number using string->number, and a byte string is converted by composing bytes->string/utf-8 with string->number.

If value-box is a box, then the default type is derived from the initial box content: 'string, 'bytes, or 'integer. Otherwise, the default type is 'string.

Resources from ".ini" files are always strings, and are converted like REG_SZ registry values.

To get the “default” value for a registry entry, use a trailing backslash. For example, the following expression gets a command line for starting a browser:

> (get-resource "HKEY_CLASSES_ROOT"
> "htmlfile\\shell\\open\\command\\")

Changed in version 8.0.0.10 of package base: Added 'sting/utf-16 and 'bytes* options for type.

> > procedure
> > (write-resource |  | section |  |  |  |
> > |  | entry |  |  |  |
> > |  | value |  |  |  |
> > | [ | file |  |  |  |
> > |  | #:type type |  |  |  |
> > |  | #:create-key? create-key?]) |  | → |  | boolean?
> section : string?
> entry : string?
> value : (or/c string? bytes? exact-integer?)
> file : (or/c path-string? #f) = #f
> | type |  | : |  |
> (or/c 'string 'expand-string 'bytes 'dword
> 'bytes/string 'bytes/expand-string)
> |  | = |  | 'string
> create-key? : any/c = #f

Write a value to the Windows registry or an ".ini" file. For backward compatibility, the result is #f for platforms other than Windows. The registry is written when file is #f and when section is "HKEY_CLASSES_ROOT", "HKEY_CURRENT_CONFIG", "HKEY_CURRENT_USER", "HKEY_LOCAL_MACHINE", or "HKEY_USERS". When file is #f and section is not one of the special registry strings, then (build-path (find-system-path 'home-dir) "mred.ini") is written.

The resource value is keyed on the combination of section and entry. If create-key? is false when writing to the registry, the resource entry must already exist, otherwise the write fails. If writing to the registry fails (due to a permissions issue or when the entry does not exist and create-key? is false), then (build-path (find-system-path 'home-dir) "mred.ini") is written to instead. The result is #f if the ".ini" write fails or #t if either the registry write or the ".ini" write succeeds.

The type argument determines both the format of the value written to the registry and its conversion of the to bytes:

- 'string: writes as REG_SZ, where a string value is converted to UTF-16 bytes adding a nul terminator. A byte string value is converted first with bytes->string/utf-8, and an integer value is first converted with number->string, and then the result in each case is treated like a string. Note that 'string is unlikely to be a useful conversion for a byte string value; use 'bytes/string, instead.

- 'expand-string: like 'string, but written as REG_EXPAND_SZ. Note that 'expand-string is unlikely to be a useful conversion for a byte string value; use 'bytes/expand-string, instead.

- 'bytes: REG_BINARY, where a byte string value is written as-is, a string value is converted to bytes by string->bytes/utf-8, and an integer value is converted to bytes by composing number->string with string->bytes/utf-8.

- 'bytes/string: writes as REG_SZ, where a byte string value is written as-is (unlike 'string, so the byte string must be a UTF-16 encoding with a nul terminator), a string value is converted to UTF-16 bytes adding a nul terminator, and an integer value is converted to a string with number->string and then to UTF-16 bytes adding a nul terminator.

- 'bytes/expand-string: like 'bytes/string, but writes as REG_EXPAND_SZ.

- 'dword: writes as REG_DWORD, where an integer value is converted to 32-bit signed integer bytes, a string value is converted with string->number and then the same as an integer, and a byte string value is converted by composing bytes->string/utf-8 with string->number and then the same as an integer.

When writing to an ".ini" file, the format is always a string, independent of type.

Changed in version 8.0.0.10 of package base: Added 'expand-string, 'bytes/string, and 'bytes/expand-string options for type.

top contents ← prev up next →