chore(release): v2.0.0

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+<!-- Thanks for contributing! -->
+
+## Description
+
+<!--- Describe your changes in detail -->
+
+## Related Issue
+
+<!--- Link the relevant issue here -->
+
+## Type of Change
+
+<!---
+  Please look at the following checklist and put an `x` in all the boxes that
+  apply to ensure that your PR can be accepted quickly:
+-->
+
+- [ ] ✨ `feat` -- New feature (non-breaking change which adds functionality)
+- [ ] 🛠️ `fix` -- Bug fix (non-breaking change which fixes an issue)
+- [ ] ❌ `!` -- Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] 🧹 `refactor` -- Code refactor
+- [ ] ✅ `ci` -- Build configuration change
+- [ ] 📝 `docs` -- Documentation
+- [ ] 🧪 `test` -- Test
+- [ ] 🗑️ `chore` -- Chore

CHANGELOG.md

@@ -1,3 +1,70 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.0] - 2024-11-02
+
+This release introduces significant changes to the API with a streamlined
+structure, new methods for specific registry data handling, and enhanced support
+for monitoring registry key changes.
+
+### 🔄 Breaking Changes
+
+- **`AccessRights`**:
+  - `win32Value` field renamed to `value`.
+
+- **`Registry`**:
+  - Now an `abstract final` class.
+  - Removed `performanceData` static getter.
+
+- **`RegistryHive`**:
+  - Constructor is now private.
+  - `win32Value` field renamed to `value`.
+
+- **`RegistryKey`**:
+  - Now a `final` class.
+
+- **`RegistryValue`**:
+  - Now a `sealed` class.
+  - Removed `fromWin32` factory constructor.
+  - Removed `toWin32` getter.
+  - Removed `data` field.
+
+- **`RegistryValueType`**:
+  - Constructor is now private.
+  - `win32Value` field renamed to `value`.
+  - Removed `unknown` value.
+  - Removed `win32Type` getter.
+
+### ✨ New Features
+
+- **Registry Hive Construction**:
+  - Added `RegistryHive.fromWin32` factory constructor for creating hives based
+    on Win32 constants.
+
+- **Enhanced Data Retrieval**:
+  - Added type-specific methods to `RegistryKey`: `getBinaryValue`,
+    `getIntValue`, `getStringValue`, and `getStringArrayValue` for retrieving
+    data in specific formats.
+  - Deprecated `getValueAsInt` and `getValueAsString` methods in favor of the
+    new type-specific methods.
+
+- **Registry Change Notifications**:
+  - Introduced `RegistryKey.onChanged` stream for monitoring registry key
+    changes, with optional subkey tracking.
+
+- **Typed Registry Values**:
+  - Introduced specialized subclasses in `RegistryValue` for each registry value
+    type, enhancing clarity and simplifying data handling.
+
+- **Registry Value Type Construction**:
+  - Added `RegistryValueType.fromWin32` factory constructor to handle value type
+    creation based on Win32 constants.
+
+### 🚨 Dart SDK Requirement
+
+- Bumped the minimum required Dart SDK version to `3.5.0`.
+
 ## 1.1.5
 
 - Fix issue where creating `REG_SZ` or `REG_EXPANDED_SZ` string registry values
@@ -44,3 +111,5 @@
 ## 1.0.0
 
 - First stable release.
+
+[2.0.0]: https://github.com/halildurmus/win32_registry/compare/v1.1.5...v2.0.0

README.md

@@ -11,6 +11,17 @@ This package builds on top of the Dart [win32][win32_pub_dev_link] package,
 offering a high-level Dart wrapper that avoids the need for users to understand
 FFI or write directly to the Win32 API.
 
+## Features
+
+- **Manage Registry Keys**: Create, open, delete, and rename registry keys.
+- **Set and Get Values**: Store and retrieve strings, integers, binary data, and
+  string arrays.
+- **Monitor Changes**: Listen for changes in registry keys.
+- **Query Key Details**: Get information about subkeys and values within a
+  registry key.
+
+To learn more, see the [API Documentation][api_documentation_link].
+
 ## Usage
 
 A simple example that reads the Windows build number from the Windows Registry:
@@ -22,22 +33,27 @@ void main() {
   const keyPath = r'Software\Microsoft\Windows NT\CurrentVersion';
   final key = Registry.openPath(RegistryHive.localMachine, path: keyPath);
 
-  final buildNumber = key.getValueAsString('CurrentBuild');
-  if (buildNumber != null) {
-    print('Windows build number: $buildNumber');
-  }
+  final buildNumber = key.getStringValue('CurrentBuild');
+  if (buildNumber != null) print('Windows build number: $buildNumber');
 
   key.close();
 }
 ```
 
 More examples can be found in the [example] subdirectory.
 
+## Feature requests and bugs
+
+Please file feature requests and bugs at the
+[issue tracker][issue_tracker_link].
+
+[api_documentation_link]: https://pub.dev/documentation/win32_registry/latest/
 [ci_badge]: https://github.com/halildurmus/win32_registry/actions/workflows/build.yml/badge.svg
 [ci_link]: https://github.com/halildurmus/win32_registry/actions/workflows/build.yml
 [codecov_badge_link]: https://codecov.io/gh/halildurmus/win32_registry/branch/main/graph/badge.svg?token=6ThVC4ejhx
 [codecov_link]: https://codecov.io/gh/halildurmus/win32_registry
 [example]: https://github.com/halildurmus/win32_registry/tree/main/example
+[issue_tracker_link]: https://github.com/halildurmus/win32_registry/issues
 [language_badge]: https://img.shields.io/badge/language-Dart-blue.svg
 [language_link]: https://dart.dev
 [license_badge]: https://img.shields.io/github/license/halildurmus/win32_registry?color=blue

analysis_options.yaml

@@ -1 +1,85 @@
 include: package:lints/recommended.yaml
+
+linter:
+  rules:
+    - always_declare_return_types
+    - always_put_required_named_parameters_first
+    - avoid_bool_literals_in_conditional_expressions
+    - avoid_catching_errors
+    - avoid_dynamic_calls
+    - avoid_escaping_inner_quotes
+    - avoid_final_parameters
+    - avoid_multiple_declarations_per_line
+    - avoid_positional_boolean_parameters
+    - avoid_private_typedef_functions
+    - avoid_redundant_argument_values
+    - avoid_returning_this
+    - avoid_setters_without_getters
+    - avoid_slow_async_io
+    - avoid_type_to_string
+    - avoid_types_on_closure_parameters
+    - avoid_unused_constructor_parameters
+    - avoid_void_async
+    - cancel_subscriptions
+    - cascade_invocations
+    - cast_nullable_to_non_nullable
+    - close_sinks
+    - combinators_ordering
+    - comment_references
+    - deprecated_consistency
+    - deprecated_member_use_from_same_package
+    - directives_ordering
+    - discarded_futures
+    - flutter_style_todos
+    - join_return_with_assignment
+    - leading_newlines_in_multiline_strings
+    - literal_only_boolean_expressions
+    - matching_super_parameters
+    - missing_code_block_language_in_doc_comment
+    - missing_whitespace_between_adjacent_strings
+    - no_literal_bool_comparisons
+    - no_runtimeType_toString
+    - no_self_assignments
+    - noop_primitive_operations
+    - omit_local_variable_types
+    # - omit_obvious_property_types
+    - one_member_abstracts
+    - only_throw_errors
+    - parameter_assignments
+    - prefer_asserts_in_initializer_lists
+    - prefer_asserts_with_message
+    - prefer_const_constructors
+    - prefer_const_declarations
+    - prefer_expression_function_bodies
+    - prefer_final_in_for_each
+    - prefer_final_locals
+    - prefer_if_elements_to_conditional_expressions
+    - prefer_int_literals
+    - prefer_mixin
+    - prefer_null_aware_method_calls
+    - prefer_relative_imports
+    - prefer_single_quotes
+    - prefer_void_to_null
+    - sort_constructors_first
+    - sort_pub_dependencies
+    - sort_unnamed_constructors_first
+    # - specify_nonobvious_property_types
+    - throw_in_finally
+    - unawaited_futures
+    - unintended_html_in_doc_comment
+    - unnecessary_await_in_return
+    - unnecessary_breaks
+    - unnecessary_lambdas
+    - unnecessary_library_directive
+    - unnecessary_library_name
+    - unnecessary_parenthesis
+    - unnecessary_raw_strings
+    - unnecessary_statements
+    - unreachable_from_main
+    - use_enums
+    - use_if_null_to_convert_nulls_to_bools
+    - use_is_even_rather_than_modulo
+    - use_named_constants
+    - use_raw_strings
+    - use_string_buffers
+    - use_to_and_as_if_applicable

example/create_values.dart

@@ -1,24 +1,45 @@
+import 'dart:typed_data';
+
 import 'package:win32_registry/win32_registry.dart';
 
 void main() {
   final hkcu = Registry.currentUser;
   const subkeyName = 'DemoTestKey';
   final subkey = hkcu.createKey(subkeyName);
 
-  const dword = RegistryValue('TestDWORD', RegistryValueType.int32, 0xFACEFEED);
+  const dword = RegistryValue.int32('TestDWORD', 0xFACEFEED);
   subkey.createValue(dword);
 
-  const qword =
-      RegistryValue('TestQWORD', RegistryValueType.int64, 0x0123456789ABCDEF);
+  const qword = RegistryValue.int64('TestQWORD', 0x0123456789ABCDEF);
   subkey.createValue(qword);
 
-  const string = RegistryValue(
+  const string = RegistryValue.string(
     'TestString',
-    RegistryValueType.string,
     'The human race has one really effective weapon, and that is laughter.',
   );
+  subkey.createValue(string);
+
+  const stringArray = RegistryValue.stringArray(
+    'TestStringArray',
+    ['One', 'Two', 'Three'],
+  );
+  subkey.createValue(stringArray);
+
+  const unexpandedString = RegistryValue.unexpandedString(
+    'TestUnexpandedString',
+    r'%SystemRoot%\System32',
+  );
+  subkey.createValue(unexpandedString);
+
+  final binary = RegistryValue.binary(
+    'TestBinary',
+    Uint8List.fromList([0xFF, 0x33, 0x77, 0xAA]),
+  );
+  subkey.createValue(binary);
+
+  const none = RegistryValue.none('TestNone');
   subkey
-    ..createValue(string)
+    ..createValue(none)
     ..close();
 
   hkcu.close();

example/main.dart

@@ -4,10 +4,8 @@ void main() {
   const keyPath = r'Software\Microsoft\Windows NT\CurrentVersion';
   final key = Registry.openPath(RegistryHive.localMachine, path: keyPath);
 
-  final buildNumber = key.getValueAsString('CurrentBuild');
-  if (buildNumber != null) {
-    print('Windows build number: $buildNumber');
-  }
+  final buildNumber = key.getStringValue('CurrentBuild');
+  if (buildNumber != null) print('Windows build number: $buildNumber');
 
   key.close();
 }

example/monitor_key.dart

@@ -0,0 +1,33 @@
+import 'package:win32_registry/win32_registry.dart';
+
+void main() async {
+  final hkcu = Registry.currentUser;
+  const subkeyName = 'DemoTestKey';
+  final subkey = hkcu.createKey(subkeyName);
+
+  const string = RegistryValue.string(
+    'TestString',
+    'The human race has one really effective weapon, and that is laughter.',
+  );
+  subkey.createValue(string);
+
+  // Subscribe to the onChanged stream to monitor changes to the subkey.
+  final subscription = subkey
+      .onChanged()
+      .listen((_) => print('Subkey changed.'), cancelOnError: true);
+
+  print('Monitoring registry key changes for 30 seconds...');
+  // Now, make a change to the subkey in RegEdit to trigger the onChanged event.
+  // For example, change the value of the "TestString" value in the subkey or
+  // add a new value to the subkey.
+
+  // Stop monitoring after 30 seconds.
+  await Future.delayed(const Duration(seconds: 30), () async {
+    await subscription.cancel();
+    subkey.close();
+    hkcu
+      ..deleteKey(subkeyName)
+      ..close();
+    print('Stopped monitoring.');
+  });
+}

example/read_values.dart

@@ -5,8 +5,22 @@ void main() {
   final key = Registry.openPath(RegistryHive.localMachine, path: keyPath);
 
   print('Values:');
-  for (final value in key.values) {
-    print(' - ${value.toString()}');
+  for (final registryValue in key.values) {
+    final RegistryValue(:name, :type) = registryValue;
+    switch (registryValue) {
+      case BinaryValue(:final value):
+        print(' - $name ($type): $value');
+      case Int32Value(:final value) || Int64Value(:final value):
+        print(' - $name ($type): $value');
+      case LinkValue(:final value) ||
+            StringValue(:final value) ||
+            UnexpandedStringValue(:final value):
+        print(' - $name ($type): $value');
+      case StringArrayValue(:final value):
+        print(' - $name ($type): $value');
+      case NoneValue():
+        print(' - $name ($type)');
+    }
   }
 
   print('\n${'-' * 80}\n');

lib/src/access_rights.dart

@@ -0,0 +1,36 @@
+import 'package:win32/win32.dart';
+
+/// Defines the access rights for registry operations.
+enum AccessRights {
+  /// Grants read-only access to a registry key.
+  ///
+  /// Use this option to read the contents of the key and its values.
+  readOnly(REG_SAM_FLAGS.KEY_READ),
+
+  /// Grants write-only access to a registry key.
+  ///
+  /// Use this option to modify the contents of the key or create subkeys.
+  writeOnly(REG_SAM_FLAGS.KEY_WRITE),
+
+  /// Grants full access to a registry key.
+  ///
+  /// Use this option to perform any operation on the key, including reading,
+  /// writing, and changing permissions.
+  allAccess(REG_SAM_FLAGS.KEY_ALL_ACCESS);
+
+  /// Creates an [AccessRights] enum instance with the specified access flag.
+  ///
+  /// The [value] parameter corresponds to a Win32 API constant representing
+  /// the access level.
+  const AccessRights(this.value);
+
+  /// The access level as an integer, corresponding to the Win32 API constant.
+  final int value;
+
+  @override
+  String toString() => switch (this) {
+        readOnly => 'KEY_READ',
+        writeOnly => 'KEY_WRITE',
+        allAccess => 'KEY_ALL_ACCESS'
+      };
+}