3.0 devel

CHANGELOG.md

@@ -1,11 +1,52 @@
 ## 3.0.0
 
+- This release includes an overhaul of the COM and WinRT API generation, as
+  described below. Apps and packages that call traditional Win32 APIs should not
+  require changes, but apps that use COM or the highly-experimental WinRT APIs
+  should expect to make changes.
+- [BREAKING CHANGE] WinRT APIs have been moved to a separate library. This
+  provides isolation for apps that only use traditional APIs (Win32/COM) from
+  the more experimental WinRT APIs. To use WinRT from your code, change your
+  import statement to `import 'package:win32/winrt.dart';`. The WinRT library
+  also exports all Win32 APIs, so you don't have to import both libraries.
 - [BREAKING CHANGE] COM and Windows Runtime methods and properties are now
   camelCased, not TitleCased. This is inconvenient, but it avoids a whole class
   of name clashes and aligns COM and WinRT APIs more closely with Dart idioms.
   As the projections get smarter with more helpers, we think this is the right
   call for the future and worth a one-time tax to fix.
-- TODO: Add other changes.
+- [BREAKING CHANGE] You can now cast to a new COM interface without needing the
+  IID for the target interface. Instead of:
+
+```dart
+  final modalWindow = IModalWindow(fileDialog.toInterface(IID_IModalWindow));
+```
+
+write:
+
+```dart
+  final modalWindow = IModalWindow.from(fileDialog);
+```
+
+- [BREAKING CHANGE] WinRT classes now support projection of `List`s and
+  `String`s directly.
+- [BREAKING CHANGE] The WinRT `fromPointer` method is now `fromRawPointer`.
+- `GUIDFromString` now supports an optional custom allocator parameter.
+- Added various APIs from iphlpapi.dll for tracking and renewing IP addresses.
+- Added `DisableThreadLibraryCalls`, `FindStringOrdinal`, `GetConsoleCP`,
+  `GetConsoleOutputCP`, `GetModuleHandleExW`, `GetNumberOfConsoleInputEvents`,
+  `GetVolumeInformation`, `GetVolumeInformationByHandle`, `PeekConsoleInput`,
+  `ReadConsoleInputW`, `SetErrorMode`, `SetThreadErrorMode`, `SizeofResource`
+  APIs from kernel32.dll
+- Added `GetClassFile` API from ole32.dll
+- Added `SetupDiGetDeviceInstanceId`, `SetupDiGetDeviceRegistryPropertyW` APIs
+  from setupapi.dll
+- Added `GetAltTabInfoW`, `GetClassNameW`, `GetGUIThreadInfo` APIs from
+  user32.dll
+- Added various foundational WinRT types, including `IIterable`, `IIterator`,
+  `IKeyValuePair`, `IMapView`, `IVector`, `IVectorView`, `IPropertyValue`,
+  `IReference`, with tremendous thanks again to @halildurmus, who has driven
+  much of the recent WinRT work.
+- Major reworking of the WinRT generation code, thanks to @halildurmus.
 
 ## 2.7.0
 

doc/winrt.md

@@ -24,7 +24,7 @@ to the object type desired. For example:
 
 ```dart
 final comObject = CreateObject('Windows.Globalization.Calendar', IID_ICalendar);
-final calendar = ICalendar.from(comObject);
+final calendar = ICalendar.fromRawPointer(comObject);
 ```
 
 The object should be disposed of when it is no longer in use, for example:

example/appcontainer.dart

@@ -8,7 +8,7 @@
 import 'dart:ffi';
 
 import 'package:ffi/ffi.dart';
-import 'package:win32/win32.dart';
+import 'package:win32/winrt.dart';
 
 bool isAppContainer() {
   final phToken = calloc<HANDLE>();

example/calendar.dart

@@ -4,7 +4,7 @@
 
 // Simple example of calling WinRT APIs
 
-import 'package:win32/win32.dart';
+import 'package:win32/winrt.dart';
 
 String calendarData(Calendar calendar) =>
     'Calendar: ${calendar.getCalendarSystem()}\n'

example/shell_notify_icon/_menu.dart

@@ -2,7 +2,7 @@ import 'dart:ffi';
 import 'dart:math';
 
 import 'package:ffi/ffi.dart';
-import 'package:win32/win32.dart' hide Point;
+import 'package:win32/win32.dart';
 
 import '_app.dart' as app;
 import '_tray.dart' as tray;

example/tetris/pieceset.dart

@@ -1,6 +1,6 @@
 import 'dart:math' show Random;
 
-import 'package:win32/win32.dart' hide Point;
+import 'package:win32/win32.dart';
 
 import 'piece.dart';
 

example/winrt_picker.dart

@@ -7,7 +7,7 @@
 import 'dart:ffi';
 
 import 'package:ffi/ffi.dart';
-import 'package:win32/win32.dart';
+import 'package:win32/winrt.dart';
 
 void main() async {
   winrtInitialize();

lib/src/utils.dart

@@ -10,9 +10,12 @@ import 'dart:ffi';
 
 import 'package:ffi/ffi.dart';
 
+import 'api_ms_win_core_winrt_string_l1_1_0.dart';
 import 'constants.dart';
+import 'exceptions.dart';
 import 'extensions/int_to_hexstring.dart';
 import 'kernel32.dart';
+import 'macros.dart';
 import 'shell32.dart';
 import 'structs.g.dart';
 import 'types.dart';
@@ -102,6 +105,38 @@ void printStruct(Pointer struct, int sizeInBytes) {
 /// [free] when it has been used.
 LPWSTR TEXT(String string) => string.toNativeUtf16();
 
+/// Takes a `HSTRING` (a WinRT String handle), and converts it to a Dart
+/// `String`.
+///
+/// {@category winrt}
+String convertFromHString(int hstring) =>
+    WindowsGetStringRawBuffer(hstring, nullptr).toDartString();
+
+/// Takes a Dart String and converts it to an `HSTRING` (a WinRT String),
+/// returning an integer handle.
+///
+/// The caller is responsible for deleting the `HSTRING` when it is no longer
+/// used, through a call to `WindowsDeleteString(HSTRING hstr)`, which
+/// decrements the reference count of that string. If the reference count
+/// reaches 0, the Windows Runtime deallocates the buffer.
+///
+/// {@category winrt}
+int convertToHString(String string) {
+  final hString = calloc<HSTRING>();
+  final stringPtr = string.toNativeUtf16();
+  // Create a HSTRING representing the object
+  try {
+    final hr = WindowsCreateString(stringPtr, string.length, hString);
+    if (FAILED(hr)) {
+      throw WindowsException(hr);
+    } else {
+      return hString.value;
+    }
+  } finally {
+    free(stringPtr);
+  }
+}
+
 /// Allocates memory for a Unicode string and returns a pointer.
 ///
 /// The parameter indicates how many characters should be allocated. The

lib/src/winmd_constants.dart

@@ -0,0 +1,60 @@
+// Copyright (c) 2020, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+// Enums and constants used for Windows Metadata
+
+// ignore_for_file: constant_identifier_names
+
+/// @nodoc
+const CLSID_CorMetaDataDispenser = '{E5CB7A31-7512-11D2-89CE-0080C792E5D8}';
+
+/// Contains flag values that control metadata behavior upon opening manifest
+/// files.
+///
+/// {@category Enum}
+class CorOpenFlags {
+  /// Indicates that the file should be opened for reading only.
+  static const ofRead = 0x00000000;
+
+  /// Indicates that the file should be opened for writing.
+  static const ofWrite = 0x00000001;
+
+  /// A mask for reading and writing.
+  static const ofReadWriteMask = 0x00000001;
+
+  /// Indicates that the file should be read into memory. Metadata should
+  /// maintain its own copy.
+  static const ofCopyMemory = 0x00000002;
+
+  /// Obsolete. This flag is ignored.
+  static const ofCacheImage = 0x00000004;
+
+  /// Obsolete. This flag is ignored.
+  static const ofManifestMetadata = 0x00000008;
+
+  /// Indicates that the file should be opened for reading, and that a call to
+  /// QueryInterface for an IMetaDataEmit cannot be made.
+  static const ofReadOnly = 0x00000010;
+
+  /// Indicates that the memory was allocated using a call to CoTaskMemAlloc and
+  /// will be freed by the metadata.
+  static const ofTakeOwnership = 0x00000020;
+
+  /// Obsolete. This flag is ignored.
+  static const ofNoTypeLib = 0x00000080;
+
+  /// Indicates that automatic transforms of .winmd files should be disabled. In
+  /// other words, the projection of a Windows Runtime type to a .NET Framework
+  /// type should be disabled.
+  static const ofNoTransform = 0x00001000;
+
+  /// Reserved for internal use.
+  static const ofReserved1 = 0x00000100;
+
+  /// Reserved for internal use.
+  static const ofReserved2 = 0x00000200;
+
+  /// Reserved for internal use.
+  static const ofReserved = 0xffffff40;
+}

lib/src/winrt/data/json/ijsonarraystatics.dart

@@ -14,7 +14,6 @@ import '../../../macros.dart';
 import '../../../types.dart';
 import '../../../utils.dart';
 import '../../../winrt/data/json/jsonarray.dart';
-import '../../../winrt_helpers.dart';
 
 /// @nodoc
 const IID_IJsonArrayStatics = '{DB1434A9-E164-499F-93E2-8A8F49BB90BA}';

lib/src/winrt/data/json/ijsonobjectstatics.dart

@@ -14,7 +14,6 @@ import '../../../macros.dart';
 import '../../../types.dart';
 import '../../../utils.dart';
 import '../../../winrt/data/json/jsonobject.dart';
-import '../../../winrt_helpers.dart';
 
 /// @nodoc
 const IID_IJsonObjectStatics = '{2289F159-54DE-45D8-ABCC-22603FA066A0}';

lib/src/winrt/data/json/ijsonvaluestatics.dart

@@ -14,7 +14,6 @@ import '../../../macros.dart';
 import '../../../types.dart';
 import '../../../utils.dart';
 import '../../../winrt/data/json/jsonvalue.dart';
-import '../../../winrt_helpers.dart';
 
 /// @nodoc
 const IID_IJsonValueStatics = '{5F6B544A-2F53-48E1-91A3-F78B50A6345C}';

lib/src/winrt/internal/hstring_array.dart

@@ -8,7 +8,7 @@ import 'dart:ffi';
 
 import '../../api_ms_win_core_winrt_string_l1_1_0.dart';
 import '../../types.dart';
-import '../../winrt_helpers.dart';
+import '../../utils.dart';
 
 extension HStringHelper on Pointer<HSTRING> {
   /// Creates a [List] from `Pointer<HSTRING>`.