halildurmus / dartwinrt

Idiomatic Dart projection of the modern Windows Runtime (WinRT) APIs.

A family of packages that provide an idiomatic Dart projection of modern Windows Runtime (WinRT) APIs using FFI.

☠☠ Warning: These packages are highly experimental. ☠☠

Documentation 📝

For official documentation, please visit https://win32.pub/docs/category/winrt-programming.

Usage 📋

With these packages, you can build apps that directly call the WinRT APIs from Dart using Dart FFI.

For example, you can use them to:

• Retrieve geolocation coordinates:

  

• Access power information:

  

• Access battery information:

  

• Format phone numbers:

  

• Send push notifications:

  

• Show a modern message dialog:

  

• Recognize texts from images using OcrEngine APIs:

  

Examples

Each package contains several examples within its example subdirectory, demonstrating how to invoke various WinRT APIs.

Packages 📦

Package	Pub	Points	Popularity	Likes
windows_ai
windows_applicationmodel
windows_data
windows_devices
windows_foundation
windows_gaming
windows_globalization
windows_graphics
windows_management
windows_media
windows_networking
windows_perception
windows_security
windows_services
windows_storage
windows_system
windows_ui
windows_web

Feature requests and bugs

The WinRT APIs that are projected by dartwinrt are limited, but additional APIs will be added based on user demand, especially if it helps facilitate the development of new Dart packages for Windows.

If you encounter any issues or have any feature requests, please submit them through the issue tracker.

Acknowledgements

The summary WinRT API documentation comments are licensed by Microsoft under the Creative Commons Attribution 4.0 International Public License.

dartwinrt's Issues

Add `Windows.Networking.Connectivity.NetworkInformation` APIs

Add support for `Windows.Security.Authentication.Web.Core`

With the new async support (!) I'm working to add Windows.Security.Authentication.Web.Core for brokered SSO authentication on Windows. It appears to have generated fine, but the RequestTokenAsync requires a CoreWindow which is a UWP object. For Win32 API users, Microsoft has provided an IWebAuthenticationCoreManagerInterop with RequestTokenForWindowAsync that takes an HWND instead of a CoreWindow (API docs).

HRESULT RequestTokenForWindowAsync(
    [in] HWND appWindow,
    [in] IInspectable* request, // Windows.Security.Authentication.Web.Core.WebTokenRequest as IInspectable
    [in] REFIID riid, // __uuidof(IAsyncOperation<WebTokenRequestResult*>)
    [out, retval, iid_is(riid)] void** asyncInfo
);

The trouble I'm running into is with parameter REFIID riid which is the guid of IAsyncOperation<WebTokenRequestResult>. The docs and Raymond Chen's blog (link) use variations of winrt::guid_of<IAsyncOperation<WebTokenRequestResult>>() to obtain the guid but it's a generic typed cpp method, and I can't seem to locate the guid anywhere (maybe its generated at runtime?).

Any direction would be appreciated.

☂️ Prepare for Dart 3

• #142
• #143
• Class modifiers
  • Identify classes in windows_foundation pkg that need the class modifiers
  • Identify classes in winrtgen pkg that need the class modifiers
  • #150
• Do some refactoring by making use of the patterns and records features
  • #146
  • #147
  • #149

☂️ Migrate tests to `package:checks`

package:checks is currently in preview. Once it reaches a stable version, all tests should be migrated to it gradually.

Migration guide: https://github.com/dart-lang/test/blob/master/pkgs/checks/doc/migrating_from_matcher.md

Packages

• windows_ai
• windows_applicationmodel
• windows_data
• windows_devices
• windows_foundation
• windows_gaming
• windows_globalization
• windows_graphics
• windows_management
• windows_media
• windows_networking
• windows_perception
• windows_security
• windows_services
• windows_storage
• windows_system
• windows_ui
• windows_web
• winrtgen

Add an example that demonstrates how to send toast notifications

Is there any working example of showing a toast notification using the winrt api? Folder Source

I guess I will have to first create a notification data using function such as createNotificationDataWithValues() Source

And then create the notification using createToastNotification() function. Source

Add `Windows.Data.Xml.Dom` APIs

☂️ Support asynchronous methods that report progress

WinRT has four types of asynchronous operation objects:

• IAsyncAction
• IAsyncActionWithProgress<TProgress>
• IAsyncOperation<TResult>
• IAsyncOperationWithProgress<TResult, TProgress>

Currently, only the IAsyncAction and IAsyncOperation objects are supported.

Add `FileSavePicker` and `FolderPicker` APIs

Expose `Char16` types as `String`

WinRT includes a Char16 type, representing a 16-bit non-numeric value that corresponds to a UTF-16 code unit.

Currently, these types are exposed as int; however, a more suitable approach would be to expose them as String instead.

windows_ai: float and double tensor's getAsVectorView() throws exception

Is there an existing issue for this?

• I have searched the existing issues

On which packages did you experience this issue?

windows_ai

What version are you using?

windows_ai: 0.0.2

What happened?

Creating a tensor of type float or double (using the TensorFloat or TensorDouble class) and calling getAsVectorView() throws exception.

Steps to reproduce

1. Run the following dart code:

import 'package:windows_ai/windows_ai.dart';

void main() {
  final tensor =
      TensorFloat.createFromShapeArrayAndDataArray([1, 4], [1, 2, 3, 4]);
  print(tensor?.getAsVectorView());
}

Expected Output: `[1, 2, 3, 4]`
Current Output:
Unhandled exception:
Invalid argument (T): Unsupported type: double
#0      new IVectorView.fromPtr (package:windows_foundation/src/collections/ivectorview.dart:133:5)
#1      ITensorFloat.getAsVectorView (package:windows_ai/src/machinelearning/itensorfloat.dart:48:24)
#2      TensorFloat.getAsVectorView (package:windows_ai/src/machinelearning/tensorfloat.dart:73:51)
#3      main (package:iamhear_app/services/windows_ai.dart:6:17)
#4      _delayEntrypointInvocation.<anonymous closure> (dart:isolate-patch/isolate_patch.dart:296:19)
#5      _RawReceivePort._handleMessage (dart:isolate-patch/isolate_patch.dart:189:12)

Supporting info to reproduce

Upon looking at the IVectorView.fromPtr factory in ivectorview.dart in windows_foundation, it seems that the error happens because the factory can handle bool, Guid, int, String and Uri, but has no method for double.

This is also seems to be the case when looking at the ivectorview_part.dart in the same package, as the said file does not ivectorview class for double type.

Relevant log output

Unhandled exception:
Invalid argument (T): Unsupported type: double
#0      new IVectorView.fromPtr (package:windows_foundation/src/collections/ivectorview.dart:133:5)
#1      ITensorFloat.getAsVectorView (package:windows_ai/src/machinelearning/itensorfloat.dart:48:24)
#2      TensorFloat.getAsVectorView (package:windows_ai/src/machinelearning/tensorfloat.dart:73:51)
#3      main (package:iamhear_app/services/windows_ai.dart:6:17)
#4      _delayEntrypointInvocation.<anonymous closure> (dart:isolate-patch/isolate_patch.dart:296:19)
#5      _RawReceivePort._handleMessage (dart:isolate-patch/isolate_patch.dart:189:12)

Flutter analyze output

Analyzing services...                                                   

   info - Don't invoke 'print' in production code - windows_ai.dart:6:3 - avoid_print

1 issue found. (ran in 0.4s)

Flutter doctor output

[√] Flutter (Channel stable, 3.10.5, on Microsoft Windows [Version 10.0.22621.1848], locale en-US)
    • Flutter version 3.10.5 on channel stable at C:\src\flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision 796c8ef792 (9 days ago), 2023-06-13 15:51:02 -0700
    • Engine revision 45f6e00911
    • Dart version 3.0.5
    • DevTools version 2.23.1

[√] Windows Version (Installed version of Windows is version 10 or higher)

[√] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
    • Android SDK at C:\Users\harsh\AppData\Local\Android\sdk
    • Platform android-34, build-tools 34.0.0
    • Java binary at: C:\Program Files\Android\Android Studio\jbr\bin\java
    • Java version OpenJDK Runtime Environment (build 17.0.6+0-b2043.56-9586694)
    • All Android licenses accepted.

[√] Chrome - develop for the web
    • CHROME_EXECUTABLE = C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe

[√] Visual Studio - develop for Windows (Visual Studio Community 2022 17.6.2)
    • Visual Studio at C:\Program Files\Microsoft Visual Studio\2022\Community
    • Visual Studio Community 2022 version 17.6.33723.286
    • Windows 10 SDK version 10.0.22000.0

[√] Android Studio (version 2022.2)
    • Android Studio at C:\Program Files\Android\Android Studio
    • Flutter plugin can be installed from:
       https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
       https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 17.0.6+0-b2043.56-9586694)

[√] VS Code (version 1.79.2)
    • VS Code at C:\Users\harsh\AppData\Local\Programs\Microsoft VS Code
    • Flutter extension version 3.66.0

[√] Connected device (3 available)
    • Windows (desktop) • windows • windows-x64    • Microsoft Windows [Version 10.0.22621.1848]
    • Chrome (web)      • chrome  • web-javascript • unknown
    • Edge (web)        • edge    • web-javascript • Microsoft Edge 112.0.1722.58

[√] Network resources
    • All expected network resources are available.

• No issues found!
[√] Network resources

• No issues found!

Code of Conduct

• I agree to follow this project's Code of Conduct

Types `Uri` and WinRT objects such as `XmlDocument` should be declared as nullable in constructors parameters

Currently, these parameters are projected as non-nullable, which is incorrect.

Support `MediaCapture` APIs

Is it possible to support video capturing API mentioned here: https://learn.microsoft.com/en-us/windows/win32/multimedia/using-video-capture?

Refactor `winrtgen` projection tests

This package will support WinRT ```NetworkOperatorTetheringManager```?

Hi, nowadays i use a powershell script run by my flutter app to get thetering state, precisely NetworkOperatorTetheringManager.TheteringOperationalState.
Full support of this api would also add possibility to start and stop tethering.
https://docs.microsoft.com/en-us/uwp/api/windows.networking.networkoperators.networkoperatortetheringmanager?view=winrt-22621

Add more APIs from `Windows.Storage` namespace

e.g. StorageFile, StorageFolder, KnownFolders etc.

Support `DateTime`, `Duration`, and `TextRange` type arguments in Vectors

Methods with `out` parameters should return a `Record`

Is there an existing issue for this?

• I have searched the existing issues

Please select which package this feature is related to

winrtgen

Is your feature request related to a problem?

As Dart currently lacks support for out parameters (see dart-lang/language#1911), the most viable alternative at present seems to be records.

Describe the solution that you'd like

See #299

Describe alternatives that you have considered

No response

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Refactor WinRT parameter projection

We should move the logic of each parameter to the files in the declarations\ folder.

For example:

  // declarations\string.dart
  ...

  class WinRTStringParameterProjection extends WinRTParameterProjection {
  WinRTStringParameterProjection(super.method, super.name, super.type);

  @override
  String get preamble => 'final ${name}HString = convertToHString($name);';

  @override
  String get postamble => 'WindowsDeleteString(${name}HString);';

  @override
  String get localIdentifier => '${name}HString';
}

  // winrt_parameter.dart
  ...

  /// Returns the appropriate projection for the parameter.
  WinRTParameterProjection? get parameterProjection {
    if (isString) return WinRTStringParameterProjection(method, name, type);
    if (isTimeSpan) return WinRTDurationParameterProjection(method, name, type);
    ...

    return null;
  }

  /// Code to be inserted prior to the function call to set up the variable
  /// conversion.
  ///
  /// Any preamble that allocates memory should have a matching postamble that
  /// frees the memory.
  String get preamble => parameterProjection?.preamble ?? '';

  /// Code to be inserted prior to the function call to tear down allocated
  /// memory.
  String get postamble => parameterProjection?.postamble ?? '';

  /// The name of the converted variable that should be passed inside the method
  /// call (e.g. `today` -> `todayDateTime`)
  String get localIdentifier =>
      parameterProjection?.localIdentifier ?? identifier;

Remove `IInspectable` methods (`getIids`, `getRuntimeClassName`, and `getTrustLevel`)

We should remove these methods as they clutter up Intellisense and autocomplete. However, we should provide a way for consumers to get access to these methods if they want to.

See the post from Raymond Chen: How do I access and customize the IInspectable methods of a Windows Runtime class written in C++/WinRT?

We should also remove the queryInterface method from the IUnknown interface as there is a much better alternative (toInterface) for this. I already deprecated the queryInterface in the dev branch.

Support `Windows.AI.MachineLearning` APIs

Since Windows.AI.MachineLearning depends on windows_graphics, it should be added after all packages are published in pub.dev.

Wrap struct fields

WinRT structs are exposed as classes to consumers, but the struct fields within these classes are not wrapped as expected.

For instance, SortEntry struct contains a field called propertyName, which is of type String, but it is currently exposed as an int, representing the HSTRING handle:

final class SortEntry implements WinRTStruct {
  SortEntry(this.propertyName, this.ascendingOrder);

  final int propertyName; // This should be of type String, not int.
  final bool ascendingOrder;
  ...
}

Similarly, MediaTimeRange struct has two fields, start and end, both of which should be of type Duration, but are currently exposed as int:

final class MediaTimeRange implements WinRTStruct {
  MediaTimeRange(this.start, this.end);
  
  // These should be of type Duration, not int.
  final int start; 
  final int end;

Support `WinRTStruct` type arguments in `IReference`

Convert the constructors of the struct classes into `const` constructors

Support projection of `Object` types

Object types can be found in WinRT methods, properties, parameters, and type arguments. The types will need to be treated as nullable. We already support Object? type arguments in IMap, IMapView, and IKeyValuePair interfaces.

Here are some examples:
https://learn.microsoft.com/en-us/uwp/api/windows.data.xml.dom.xmldocument.nodevalue?view=winrt-22621#windows-data-xml-dom-xmldocument-nodevalue
https://learn.microsoft.com/en-us/uwp/api/windows.data.xml.dom.xmldocument.createattributens?view=winrt-22621#windows-data-xml-dom-xmldocument-createattributens(system-object-system-string)

Support `double` type arguments in `IAsyncOperation`

Support delegates

WinRT delegates are COM interfaces that act as function objects. They are primarily used to implement events and are also used as callbacks for some APIs and are therefore required by many WinRT APIs.

Support `WinRTStruct` type arguments in `IAsyncOperation`

Add `Windows.System.User`

Since Windows.System.User depends on windows_storage, it should be added after all packages are published in pub.dev.

Generate package exports

Currently, we are manually specifying which files to export in packages. It will quickly get out of control as we generate more APIs.

We should make this process automatic by generating exports according to some rules (e.g. exclude xxfactory?.dart and xxstatics?.dart files).

GetThumbnailAsync

Is there an existing issue for this?

• I have searched the existing issues

On which packages did you experience this issue?

windows_storage

Description

Hi.

How to get thumbnail bytes from file in

StorageFile.getThumbnailAsyncOverloadDefaultOptions

??

Code of Conduct

• I agree to follow this project's Code of Conduct

Integrate logging into the `package:winrtgen`

Some packages that can be used for logging:
https://pub.dev/packages/logging
https://pub.dev/packages/logger

MIDI Support

Is there an existing issue for this?

• I have searched the existing issues

Please select which package this feature is related to

windows_devices

Is your feature request related to a problem?

I would like to be able to use the windows.devices.midi APIs from dart, but they do not appear to be included.

Describe the solution that you'd like

I would like to be able to use the windows.devices.midi APIs from dartwinrt.

https://learn.microsoft.com/en-us/uwp/api/windows.devices.midi?view=winrt-22621

Describe alternatives that you have considered

No response

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Support `Windows.System.Launcher` APIs

Since Windows.System.Launcher depends on windows_storage, it should be added after all packages are published in pub.dev.

Support (`Uri`, `String`) and (`Object`, `Object?`) key-value pairs in Maps

Support `Windows.Media.Ocr` APIs

I want to call Windows.Media.Ocr in my flutter desktop application. Could I simply add this package to my project? And are there any demo codes from this function? Thank you.

Support `Windows.UI.UIAutomation` APIs

Hello, I came across two questions regarding UI Automation APIs:

1. if I'd like to access the WinRT APIs in the Microsoft.UI.Automation namespace, it this the right project to make feature a request and/or make contributions?

2. if the answer for 1) is no, what is the recommended way of consuming C++ libraries in dart?

Thanks!

Support annotating types and members with `@Deprecated`

In WinMD, deprecated types and members have DeprecatedAttribute in their attributes.

While projecting types and members, we should annotate them with Deprecated if they have DeprecatedAttribute in their attributes.

Create a wrapper for `HSTRING`

Create a wrapper for HSTRING, which represents immutable strings in the Windows Runtime, similar to dart-windows/win32's BSTR implementation.

☂️ Support creating collections

Certain WinRT APIs, such as the FileIO.WriteLinesAsync Method, require the caller to supply a collection of values represented by objects like IIterable or IVectorView.

Currently, the creation of these objects is not supported.

However, once this is supported, it would be beneficial to change the method parameters to accept Dart List or Map instead. The projection would then handle the internal transformation of these related objects, providing a more user-friendly and enhanced user experience.

Getters that return collection objects such as `IVector` should be nullable

Currently, these getters are projected as non-nullable, which is incorrect.

Support boxing enums and structs

Enums and structs need to be boxed so that they can be passed to WinRT APIs that expect IInspectable objects.

Generate the private concrete classes of the WinRT generic interfaces

See #64 for context.

Support boxing `Uri` objects

Collection objects such as `IIterable` should be declared as nullable in method parameters

Currently, these parameters are projected as non-nullable, which is incorrect.

Support events

Now that halildurmus/win32#370 has been closed I was hoping to get BLE device discovery and communication going.

Unfortunately the BluetoothFindFirstDevice function does not work for BLE devices, and instead it's recommended to use the BluetoothLEAdvertisementWatcher class for finding nearby BLE devices.

I've been able to make some progress toward this (thanks to the Calendar example), but I'm struggling to understand how to add event handlers for Receivedand Stopped events. Running the generate.cmd script with some debug modifications this is the error it's generating:

Projecting method: add_Received
Unable to project method: add_Received
Exception: Type information missing for GenericTypeModifier, TYPE: Windows.Foundation.TypedEventHandler`2.
#0      TypeProjection.projectType (file:///C:/Projects/win32/tool/projection/type.dart:246:5)
dart-windows/win32#1      TypeProjection.projection (file:///C:/Projects/win32/tool/projection/type.dart:54:21)
dart-windows/win32#2      TypeProjection.dartType (file:///C:/Projects/win32/tool/projection/type.dart:63:26)
dart-windows/win32#3      ParameterProjection.dartProjection (file:///C:/Projects/win32/tool/projection/parameter.dart:20:37)
dart-windows/win32#4      MethodProjection.methodParams.<anonymous closure> (file:///C:/Projects/win32/tool/projection/method.dart:76:42)
dart-windows/win32#5      MappedListIterable.elementAt (dart:_internal/iterable.dart:413:31)
dart-windows/win32#6      ListIterable.join (dart:_internal/iterable.dart:165:22)
dart-windows/win32#7      MethodProjection.methodParams (file:///C:/Projects/win32/tool/projection/method.dart:76:62)
dart-windows/win32#8      WinRTMethodProjection.toString (file:///C:/Projects/win32/tool/projection/winrt_method.dart:86:37)
dart-windows/win32#9      InterfaceProjection.toString.<anonymous closure> (file:///C:/Projects/win32/tool/projection/interface.dart:201:42)
dart-windows/win32#10     MappedListIterable.elementAt (dart:_internal/iterable.dart:413:31)
dart-windows/win32#11     ListIterable.join (dart:_internal/iterable.dart:156:22)
dart-windows/win32#12     InterfaceProjection.toString (file:///C:/Projects/win32/tool/projection/interface.dart:201:54)
dart-windows/win32#13     generateWinRTApis (file:///C:/Projects/win32/tool/generation/generate_winrt_apis.dart:27:43)
dart-windows/win32#14     main (file:///C:/Projects/win32/tool/generation/generate.dart:36:3)
dart-windows/win32#15     _delayEntrypointInvocation.<anonymous closure> (dart:isolate-patch/isolate_patch.dart:297:19)
dart-windows/win32#16     _RawReceivePortImpl._handleMessage (dart:isolate-patch/isolate_patch.dart:192:12)

I'd be happy to give this a go, but unsure where to start and whether this is currently possible at all?

Add `Windows.System.Power.PowerManager` APIs

☂️ Create examples for each package

• windows_ai
  • #272
• windows_applicationmodel
  • TBD
• windows_data
  • JSON (#164)
  • XML DOM (#164)
  • PdfDocument
• windows_devices
  • Battery
  • DeviceInformation (#157)
  • DisplayMonitor
  • Geolocator
• windows_foundation
  • IMap (#164)
• windows_gaming
  • Gamepad
• windows_globalization
  • Calendar
  • PhoneNumberFormatter (#164)
• windows_graphics
  • TBD
• windows_management
  • TBD
• windows_media
  • OcrEngine
  • MediaCapture
• windows_networking
  • NetworkInformation (#164)
  • NetworkOperatorTetheringManager (#164)
• windows_perception
  • TBD
• windows_security
  • TBD
• windows_services
  • TBD
• windows_storage
  • FileOpenPicker
  • StorageFile & StorageFolder (#164)
• windows_system
  • Launcher
  • PowerManager (#157)
• windows_ui
  • #158
  • MessageDialog
  • UISettings
• windows_web
  • HttpClient (blocked on #209)