From e1860b07df6a4bb14800f611bcb965a3bb6dee0c Mon Sep 17 00:00:00 2001 From: BobBuehler Date: Thu, 5 May 2016 12:02:41 -0500 Subject: [PATCH] Update to winreg 1.2.0 (#9157) * Update to winreg 1.2.0 * Used @link for jsdoc on WinregStatic constructor. Updated jsdoc on Options.arch. --- winreg/winreg-tests.ts | 93 +++++++++---- winreg/winreg.d.ts | 289 ++++++++++++++++++++++++++--------------- 2 files changed, 250 insertions(+), 132 deletions(-) diff --git a/winreg/winreg-tests.ts b/winreg/winreg-tests.ts index 376006aed638f4..4a930b39168345 100644 --- a/winreg/winreg-tests.ts +++ b/winreg/winreg-tests.ts @@ -16,7 +16,7 @@ var regKey3 = new Winreg({ }) var str: string = regKey.parent.key -var par: Winreg = regKey.parent +var par: Winreg.Registry = regKey.parent regKey.values((err, items) => { var itemsC: Array = items; @@ -28,11 +28,11 @@ regKey.values((err, items) => { }); regKey.keys((err, items) => { - var itemsC: Array = items; + var itemsC: Array = items; var errorC: Error = err; items.forEach((item) => { - var regKey4: Winreg = item; + var regKey4: Winreg.Registry = item; }); }); @@ -47,49 +47,94 @@ var r2 = new Winreg({ hive: Winreg.HKCU, key: '\\Control Panel\\Desktop' }) +var r3 = new Winreg({ + host: 'blah', + arch: 'x64' +}) // get parent key console.log('parent of "'+r2.path+'" -> "'+r2.parent.path+'"'); -// list subkeys -r2.keys(function (err, items) { +// list values +r1.values(function (err, items) { if (!err) { - for (var i = 0, l = items.length; i < l; i++) { - console.log('subkey of "'+r2.path+'": '+items[i].path); - } + console.log(JSON.stringify(items, null, '\t')); } - // list values - r1.values(function (err, items) { + // query named value + r1.get(items[0].name, function (err, item) { if (!err) { - console.log(JSON.stringify(items, null, '\t')); + console.log(JSON.stringify(item, null, '\t')); } - // query named value - r1.get(items[0].name, function (err, item) { + // add value + r1.set('bla', Winreg.REG_SZ, 'hello world!', function (err) { if (!err) { - console.log(JSON.stringify(item, null, '\t')); + console.log('value written'); } - // add value - r1.set('bla', Winreg.REG_SZ, 'hello world!', function (err) { + // delete value + r1.remove('bla', function (err) { if (!err) { - console.log('value written'); + console.log('value deleted'); } - // delete value - r1.remove('bla', function (err) { + }); + }); + }); +}); - if (!err) { - console.log('value deleted'); - } +// check for key +r2.keyExists(function (err, exists) { + + if (!err) { + if (exists) { + console.log('key ' + r2.key + ' exists'); + } else { + + console.log('key ' + r2.key + ' does not exist'); + } + } + + // check for value + r2.valueExists('bla', function (err, exists) { + + if (!err) { + if (exists) { + console.log('value bla exists on key ' + r2.key); + } else { + console.log('value bla does not exist on key ' + r2.key); + } + } + + }); +}); + +// create new key or no-op +r3.create(function (err) { + + if (!err) { + console.log('key created'); + } + + // clear subkeys of key and values on key + r3.clear(function (err) { + + if (!err) { + console.log('key cleared'); + } + + // remove this key and all its subkeys + r3.destroy(function (err) { + + if (!err) { + console.log('key destroyed'); + } - }); - }); }); }); }); diff --git a/winreg/winreg.d.ts b/winreg/winreg.d.ts index 0b23f6981d5aef..3860bc237b2e07 100644 --- a/winreg/winreg.d.ts +++ b/winreg/winreg.d.ts @@ -1,44 +1,60 @@ -// Type definitions for Winreg v0.0.16 -// Project: https://github.com/fresc81/node-winreg/ -// Definitions by: RX14 +// Type definitions for Winreg v1.2.0 +// Project: http://fresc81.github.io/node-winreg/ +// Definitions by: RX14 , BobBuehler // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped declare var Winreg: WinregStatic; interface WinregStatic { /** - * Create a new Winreg instance with the given options. - * @param options options object + * Creates a registry object, which provides access to a single registry key. + * Note: This class is returned by a call to ```require('winreg')```. + * + * @public + * @class + * + * @param {@link Options} options - the options + * + * @example + * var Registry = require('winreg') + * , autoStartCurrentUser = new Registry({ + * hive: Registry.HKCU, + * key: '\\Software\\Microsoft\\Windows\\CurrentVersion\\Run' + * }); */ - new (options: Winreg.Options): Winreg; + new (options: Winreg.Options): Winreg.Registry; /** - * HKEY_LOCAL_MACHINE registry hive. + * Registry hive key HKEY_LOCAL_MACHINE. + * Note: For writing to this hive your program has to run with admin privileges. */ HKLM: string; /** - * HKEY_CURRENT_USER registry hive. + * Registry hive key HKEY_CURRENT_USER. */ HKCU: string; /** - * HKEY_CLASSES_ROOT registry hive. + * Registry hive key HKEY_CLASSES_ROOT. + * Note: For writing to this hive your program has to run with admin privileges. */ HKCR: string; /** - * HKEY_USERS registry hive. + * Registry hive key HKEY_USERS. + * Note: For writing to this hive your program has to run with admin privileges. */ HKU: string; /** - * HKEY_CURRENT_CONFIG registry hive. + * Registry hive key HKEY_CURRENT_CONFIG. + * Note: For writing to this hive your program has to run with admin privileges. */ HKCC: string; /** - * Array of available registry hives. + * Collection of available registry hive keys. */ HIVES: Array; @@ -92,168 +108,225 @@ interface WinregStatic { REG_NONE: string; /** - * Array of available registry value types. + * Collection of available registry value types. */ REG_TYPES: Array; -} -interface Winreg { /** - * Hostname, if set in options. - * @readonly + * The name of the default value. May be used instead of the empty string literal for better readability. */ - host: string; + DEFAULT_VALUE: string; +} - /** - * Hive ID. - * @readonly - */ - hive: string; +declare namespace Winreg { + export interface Options { + /** + * Optional hostname, must start with '\\' sequence. + */ + host?: string; - /** - * The registry key. - * @readonly - */ - key: string; + /** + * Optional hive ID, default is HKLM. + */ + hive?: string; - /** - * The path of the registry key, including hostname (if set) and hive. - * @readonly - */ - path: string; + /** + * Optional key, default is the root key. + */ + key?: string; - /** - * Architecture this key belongs to. - * @readonly - */ - arch: string; + /** + * Optional registry hive architecture ('x86' or 'x64'; only valid on Windows 64 Bit Operating Systems). + */ + arch?: string; + } /** - * A new Winreg instance of the parent key. - * @readonly + * A registry object, which provides access to a single registry key. */ - parent: Winreg; + export interface Registry { + /** + * The hostname. + * @readonly + */ + host: string; - /** - * Retrieves all values from this registry key. - * - * @param cb Callback with an array of RegistryItem objects, one for each value. - */ - values(cb: (err: Error, result: Array) => void): void; + /** + * The hive id. + * @readonly + */ + hive: string; - /** - * Retrieves all subkeys of this registry key. - * - * @param cb Callback with an array of Winreg objects, one for each subkey. - */ - keys(cb: (err: Error, result: Array) => void): void; + /** + * The registry key name. + * @readonly + */ + key: string; - /** - * Retrieves a named value from this registry key. - * - * @param name Name of the value to retrieve. - * @param cb Callback with a RegistryItem object for the value. - */ - get(name: string, cb: (err: Error, result: Winreg.RegistryItem) => void): void; + /** + * The full path to the registry key. + * @readonly + */ + path: string; - /** - * Sets a named value in this registry key. Overwrites existing value. - * - * @param name Name of the value to set. - * @param type Type of the value to set. - * @param value Value of value to set. - * @param cb Callback with any errors. - */ - set(name: string, type: string, value: string, cb: (err: Error) => void): void; + /** + * The registry hive architecture ('x86' or 'x64'). + * @readonly + */ + arch: string; - /** - * Remove a named value from this registry key. - * - * @param name Name of the value to remove. - * @param cb Callback with any errors. - */ - remove(name: string, cb: (err: Error) => void): void; + /** + * Creates a new {@link Registry} instance that points to the parent registry key. + * @readonly + */ + parent: Registry; - /** - * Create this registry key. - * - * @param cb Callback with any errors. - */ - create(cb: (err: Error) => void): void; + /** + * Retrieve all values from this registry key. + * @param {valuesCallback} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @param {array=} cb.items - an array of {@link RegistryItem} objects + * @returns {Registry} this registry key object + */ + values(cb: (err: Error, result: Array) => void): Registry; - /** - * Erase this registry key and its contents. - * - * @param cb Callback with any errors. - */ - erase(cb: (err: Error) => void): void; -} + /** + * Retrieve all subkeys from this registry key. + * @param {function (err, items)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @param {array=} cb.items - an array of {@link Registry} objects + * @returns {Registry} this registry key object + */ + keys(cb: (err: Error, result: Array) => void): Registry; -declare namespace Winreg { - export interface Options { /** - * Optional hostname, must start with '\\' sequence. + * Gets a named value from this registry key. + * @param {string} name - the value name, use {@link Registry.DEFAULT_VALUE} or an empty string for the default value + * @param {function (err, item)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @param {RegistryItem=} cb.item - the retrieved registry item + * @returns {Registry} this registry key object */ - host?: string; + get(name: string, cb: (err: Error, result: Winreg.RegistryItem) => void): Registry; /** - * Optional hive ID, default is HKLM. + * Sets a named value in this registry key, overwriting an already existing value. + * @param {string} name - the value name, use {@link Registry.DEFAULT_VALUE} or an empty string for the default value + * @param {string} type - the value type + * @param {string} value - the value + * @param {function (err)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @returns {Registry} this registry key object */ - hive?: string; + set(name: string, type: string, value: string, cb: (err: Error) => void): Registry; /** - * Optional key, default is the root key. + * Remove a named value from this registry key. If name is empty, sets the default value of this key. + * Note: This key must be already existing. + * @param {string} name - the value name, use {@link Registry.DEFAULT_VALUE} or an empty string for the default value + * @param {function (err)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @returns {Registry} this registry key object */ - key?: string; + remove(name: string, cb: (err: Error) => void): Registry; /** - * Optional architecture of the registry. + * Remove all subkeys and values (including the default value) from this registry key. + * @param {function (err)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @returns {Registry} this registry key object */ - arch?: string; + clear(cb: (err: Error) => void): Registry; + + /** + * Alias for the clear method to keep it backward compatible. + * @method + * @deprecated Use {@link Registry#clear} or {@link Registry#destroy} in favour of this method. + * @param {function (err)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @returns {Registry} this registry key object + */ + erase(cb: (err: Error) => void): Registry; + + /** + * Delete this key and all subkeys from the registry. + * @param {function (err)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @returns {Registry} this registry key object + */ + destroy(cb: (err: Error) => void): Registry; + + /** + * Create this registry key. Note that this is a no-op if the key already exists. + * @param {function (err)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @returns {Registry} this registry key object + */ + create(cb: (err: Error) => void): Registry; + + /** + * Checks if this key already exists. + * @param {function (err, exists)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @param {boolean=} cb.exists - true if a registry key with this name already exists + * @returns {Registry} this registry key object + */ + keyExists(cb: (err: Error, exists: boolean) => void): Registry; + + /** + * Checks if a value with the given name already exists within this key. + * @param {string} name - the value name, use {@link Registry.DEFAULT_VALUE} or an empty string for the default value + * @param {function (err, exists)} cb - callback function + * @param {error=} cb.err - error object or null if successful + * @param {boolean=} cb.exists - true if a value with the given name was found in this key + * @returns {Registry} this registry key object + */ + valueExists(name: string, cb: (err: Error, exists: boolean) => void): Registry; } /** - * A single registry value record + * A single registry value record. + * Objects of this type are created internally and returned by methods of {@link Registry} objects. */ - interface RegistryItem { + export interface RegistryItem { /** - * Hostname, if set in options. + * The hostname. * @readonly */ host: string; /** - * Hive ID. + * The hive id. * @readonly */ hive: string; /** - * Key that the registry value belongs to. + * The registry key. * @readonly */ key: string; /** - * Name of the registry value. + * The value name. * @readonly */ name: string; /** - * Type of the registry value. + * The value type. * @readonly */ type: string; /** - * Value of the registry value, as a string. + * The value. * @readonly */ value: string; /** - * Architecture this value belongs to. + * The hive architecture. * @readonly */ arch: string;