WineHQ

Wine Developer's Guide/WinRT in Wine

Work in progress: This page is currently undergoing extensive revision. External links to specific parts of this page may now be broken due to the section having been edited, moved, merged with another section, or removed altogether. Consult the table of contents to find the section you are looking for. There may be related discussion on the talk page.

Introduction

What is WinRT?

Windows Runtime (short: WinRT) is a new Win32 independent ABI, used by the Windows operating system. It finds its primary use in the Universal Windows Platform (UWP), which provides an API and execution environment (sandbox) to run apps in, but can also be directly accessed from Win32 programs.

Internally, WinRT is basically COM with extra spice and some "new" concepts.

Writing WinRT components for Wine

IDL 3.0

WinRT defines its ABI in IDL files, much like COM. For this, it uses the IDL format 3.0, that has some new concepts, keywords and generally an even more object-oriented approach than the COM-IDLs:

Structure

First, we have the introduction of "runtimeclasses" (this article just refers to them as classes), which are basically COM-objects and the key feature of WinRT: Based on their definition and attributes, they expose different COM-interfaces as members or statically. Classes can be instantiated directly [and/or only] through an activation factory (COM class factory), when they are marked by an "activatable" attribute:

[
    activatable(Windows.Foundation.UniversalApiContract, 1.0),
    activatable(Wine.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),
    contract(Windows.Foundation.UniversalApiContract, 1.0),
    marshaling_behavior(agile),
    static(Wine.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),
    static(Wine.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)
]
runtimeclass Foo
{
    [default] interface Windows.SomeFeature.IFoo;
    interface Windows.SomeFeature.IFoo2;
}

This Foo class is in the "Wine.SomeFeature" namespace and exposes two interfaces: "IFoo" and "IFoo2":

It can be activated (instantiated) either directly (much like a parameterless constructor in any OOP language) or through the "IFooFactory" iface, which provides all (parameterized and non parm.) constructors. It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".

Let's take a look at "IFoo":

[
    contract(Windows.Foundation.UniversalApiContract, 1.0),
    exclusiveto(Wine.SomeFeature.Foo),
    uuid(abababab-cdcd-efef-1234-56789abcdef)
]
interface IFoo : IInspectable
    requires
        Windows.SomeFeature.IFoo2
{
    [propget] HRESULT MyProperty1([out, retval] Wine.SomeFeature.Bar **value);
    [propput] HRESULT MyProperty1(Wine.SomeFeature.Bar *value);
    HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Wine.SomeFeature.BarResult*> **operation);
    [eventadd] HRESULT OnBazHappening(
        [in] Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*> *handler,
        [out, retval] EventRegistrationToken *token);
    [eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);
}
  • Like any COM-interface, IFoo has an interface-ID (UUID) and it's only meant to be used by the Foo class (exclusiveto).
  • It inherits from IInspectable, which in turn also inherits IUnknown.
  • Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".


Let's take a look at the interface members:

  1. IFoo has a property with getter and setter for a Bar object: "MyProperty1".
  2. IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".
  3. IFoo provides an event system "OnBazHappening".


Summing up some properties:

Property Description
activatable An activatable (runtime)class
default The default interface of an instantiated class
eventadd Function to add an event handler
eventremove Function to remove an event handler
propget Getter method of a property
propput Setter method of a property
static A static interface to a class

This page was last edited on 26 August 2022, at 15:34.