https://wiki.winehq.org/api.php?action=feedcontributions&user=BernhardKoelbl&feedformat=atomWineHQ Wiki - User contributions [en]2024-03-28T17:46:35ZUser contributionsMediaWiki 1.41.0https://wiki.winehq.org/index.php?title=Debug_Channels&diff=4375Debug Channels2024-02-21T20:16:18Z<p>BernhardKoelbl: /* Useful Channels */</p>
<hr />
<div>'''''Translations of this page:''''' not yet ported. Translators, please see the discussion page. <br />
<br />
'''WINEDEBUG''' is an environment variable that turns debugging messages on or off.<br />
<br />
== Syntax ==<br />
<br />
WINEDEBUG=[[process:]class]+xxx,[[process:]class]-yyy,...<br />
<br />
'''process''' is optional and can be used to make the debug flag applied to only the specified process to limit output size. For example WINEDEBUG=notepad.exe:+relay only enable relay channel for notepad.exe. You can also do something like WINEDEBUG=+win,notepad.exe:-win to enable win channel for all processes but notepad.exe.<br />
<br />
'''class''' is optional and can be one of the following: '''trace''', '''warn''', '''err''', or '''fixme'''. These are ordered roughly from least to most severe. '''trace''' is used for code paths that occur as part of normal operation. '''warn''' is generally used for code paths that may cause failures, but are likely to be well-handled by a higher-level component. '''err''' is used for code paths that are likely to cause failures. '''fixme''' is used for code paths that are unimplemented in Wine. By default, only '''err''' and '''fixme''' are enabled. If a channel is specified without a class, all classes are enabled.<br />
<br />
Each channel will print messages about a particular component of Wine. The following character can be either + or - to switch the specified channel on or off respectively. If there is no class part before it, a leading + can be omitted. Note that spaces are not allowed any where in the string.<br />
<br />
'''channel''' specifies which debug channel to turn on or off. For complete list of channels run this command in the source directory:<br />
<br />
grep -r --include='*.c' --include='*.h' 'WINE_\(DEFAULT\|DECLARE\)_DEBUG_CHANNEL' dlls/ programs/<br />
<br />
And with some more work we have sorted and formatted list in BASH (you may want to adjust number 26 near the end of this composite to match your indentation taste):<br />
<br />
<pre><br />
for modname in $(find dlls/ programs/ -mindepth 1 -type d | sort); do<br />
echo $(grep -rE --include='*.[ch]' '^WINE_(DEFAULT|DECLARE)_DEBUG_CHANNEL' $modname \<br />
| awk -F "[()]" '{print $2}' | sort | uniq) \<br />
| awk -v modname=$modname '{if (NF>0) printf("%-*s%s\n", 26, modname": ", $0)}';<br />
done<br />
</pre><br />
<br />
== Examples ==<br />
; WINEDEBUG=warn+all<br />
: will turn on WARN messages for all channels, in addition to already enabled ERR and FIXME messages.<br />
; WINEDEBUG=fixme-all,warn+cursor,+relay<br />
: will turn off all FIXME messages, turn on cursor WARN messages (in addition to ERR and FIXME messages), and turn on all relay messages (API calls).<br />
; WINEDEBUG=+relay<br />
: will turn on all relay messages. For more control on including or excluding functions and dlls from the relay trace look into the [HKCU\Software\Wine\Debug] registry key (See [[Useful Registry Keys]] and the example below).<br />
; WINEDEBUG=-d3d<br />
: will turn off all d3d messages, and additionally disable checking for GL errors after operations. This may improve performance.<br />
<br />
== Useful Channels ==<br />
<br />
{| class="wikitable" style="margin:auto"<br />
|+ Some of the debug channels can be particularly useful<br />
|-<br />
! Channel !! Usage<br />
|-<br />
| +all || Logs everything, probably gives too much information in most cases, but may come in handy for subtle issues<br />
|-<br />
| +heap || Traces all heap activity in the program and switches on constant integrity checks. If an app is trashing the heap, doing a +relay,+heap trace will let you narrow down exactly where it's happening. If an inconsistency is detected, Wine will dump the contents of the heap and terminate the program. Although many things can lead to trashing the heap, the most common is Wine overrunning an internal buffer. Be sure to remember this channel; all Wine code uses the HeapAlloc/HeapFree APIs internally, and a primary reason is that Wine's built in heap debugging is so useful. Be warned that +heap can make a program extremely slow, and generate very large log files. If you're concerned that Wine may be corrupting the heap but are not sure, warn+heap will enable heap validation but will not trace every allocation and free.<br />
|-<br />
| +loaddll || Reports each DLL as it is loaded.<br />
|-<br />
| +module || Like +loaddll but more verbose.<br />
|-<br />
| +pid || Prefixes each debug output line with the ID of the process that generated it. This can be helpful when debugging multiprocess applications.<br />
|-<br />
| +relay || Logs every call that crosses the DLL boundary of Wine's built-in modules, including calls between (non-native) DLLs. This channel is often the first port of call when you have no idea what's going wrong. It shows you each call into and out of Wine modules at the DLL boundaries. If you're being overwhelmed by certain functions, look into setting the RelayInclude and RelayExclude strings in the Wine registry (under [HKCU\Software\Wine\Debug]). Note that this string is already pre-populated with some functions which are frequently called but don't usually give any clues as to why a program might be failing. '''Never use +relay or +snoop with native DLLs!''' This will show you the implementation of those DLLs, which means that any code you write to implement them violates our clean room reverse-engineering rules.<br />
|-<br />
| +seh || Logs Windows exceptions (Structured Exception Handling). These are invoked either when an application performs an illegal operation (i.e. crashes), or if a program throws its own exceptions. Wine converts UNIX signals into SEH exceptions and outputs them using this channel. This can be useful because applications will often trap their own crash, in order to perform an emergency save for instance. The most common exception to watch for is STATUS_ACCESS_VIOLATION or '''0xC0000005''' which is the closest equivalent in Win32 to a segfault. You may also see codes which don't appear in the headers; these are typically language-specific exceptions used by whichever compiler was used to produce the EXE. E.g. '''0xEEDFADE''' is the code for a Delphi internal exception, and '''0xE06D7363''' is a Microsoft Visual C++ exception, which has a magic value (info[0]) of '''0x19930520''', which is easy to remember because it looks like a date (and probably is). If you see any of these exceptions, it may mean a Win32 API call returned a non-zero error code somewhere.<br />
|-<br />
| +server || Shows each wineserver RPC. You don't normally need this but it may prove helpful when debugging wineserver issues.<br />
|-<br />
| +snoop || Logs every function call between native DLLs. This is similar to +relay but works between two native DLLs, although this channel provides poorer information because parameters aren't reported. +snoop may also break or destabilize an application as it inspects the stack and disassembles function prologues to try and guess parameters. '''Never use +relay or +snoop with native DLLs!''' This will show you the implementation of those DLLs, which means that any code you write to implement them violates our clean room reverse-engineering rules. (This feature may be broken and only works for i386)<br />
|-<br />
| +synchronous || Forces X11 into synchronous mode<br />
|-<br />
| +timestamp || Prefixes each debug output line with the timestamp when that line executed. This is invaluable for debugging performance issue.<br />
|-<br />
| +fps || Prints the number of frames per second in the terminal for OpenGL, D3D, or Vulkan applications.<br />
|-<br />
| +debugstr || Prints strings, sent to OutputDebugStringA and vDbgPrintExWithPrefix.<br />
|-<br />
| +threadname || Shows thread names when they are set or changed.<br />
|}<br />
<br />
== Other Debugging Tips ==<br />
* If a program is displaying a message box when it fails, and you don't know what is causing the problem, try performing a +relay,+msgbox trace. Then open the debug log in your favourite editor or text viewer (less is quite good) and search for trace:msgbox. Look at the relay data before the MessageBox API call, although the problem may not be caused by a call that happens ''immediately'' before the error. Keep an eye out for failing API calls in particular, and remember that there's little consistency in the Windows API as to what return codes mean. You just have to get used to what the specific API uses, and while many return non-zero for success and zero for fail, some use the opposite convention.<br />
<br />
* If a program fails at startup with nothing to suggest why, you can use an +all trace. If your program seems to be failing a long way from an API call, you might also try [Disassembly disassembling] it to see if it's accessing some of the parameters passed in to its entry point (for instance, [http://bugs.winehq.org/show_bug.cgi?id=3542 Dungeon Keeper crashes] if you run it without an absolute path for argv[0]).<br />
<br />
=== Making +relay less verbose ===<br />
If you're looking for a problem that happens a couple minutes into the run of an app, +relay can be too verbose. In that case, run it once, then send the log through a script like<br />
<br />
<pre><br />
# Make grep go fast<br />
LANG=C<br />
# Find top ten calls<br />
freq=`grep ':Ret ' | sed 's/(.*//;s/.* //' | sort | uniq -c | sort -n | tail | awk '{print $2}' | tr '\012' ';'`<br />
cat > quiet.reg << _EOF<br />
REGEDIT4<br />
<br />
[HKEY_CURRENT_USER\Software\Wine\Debug]<br />
"RelayExclude"="ntdll.RtlEnterCriticalSection;ntdll.RtlTryEnterCriticalSection;ntdll.RtlLeaveCriticalSection;kernel32.48;kernel32.49;kernel32.94;kernel32.95;kernel32.96;kernel32.97;kernel32.98;kernel32.TlsGetValue;kernel32.TlsSetValue;kernel32.FlsGetValue;kernel32.FlsSetValue;kernel32.SetLastError;$freq"<br />
<br />
_EOF<br />
<br />
wine regedit quiet.reg<br />
</pre><br />
This will tell Wine to not log the ten most frequent calls in your app, which should make your +relay log much more managable in size.<br />
<br />
You can also specify process name to enable relay only for the specified process, for example: WINEDEBUG=notepad.exe:+relay<br />
<br />
== See Also ==<br />
* [[Wine_User's_Guide#WINEDEBUG=channels|Environment Variables: WINEDEBUG]] - chapter of the [[Wine User's Guide]]<br />
* [http://source.winehq.org/WineAPI/ WineAPI documentation] - For each function the used debug channels are listed.<br />
----<br />
[[Category:Quality Assurance]] <br />
<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4053Wine Developer's Guide/WinRT in Wine2022-08-29T16:37:16Z<p>BernhardKoelbl: </p>
<hr />
<div>__NUMBEREDHEADINGS__<br />
'''Authors:''' Bernhard Koelbl<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
=== IDL 3.0 ===<br />
<br />
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.<br />
<br />
==== Structure ====<br />
<br />
A WinRT IDL file from the Windows platform SDK is generally structured like this:<br />
<br />
<pre><br />
import "other.idl"<br />
import "other2.idl"<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses from other files.<br />
namespace Windows<br />
{<br />
namespace OtherFeature<br />
{<br />
typedef enum OtherFooEnum;<br />
<br />
interface OtherFoo;<br />
}<br />
}<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses in this file.<br />
namespace Windows<br />
{<br />
namespace SomeFeature <br />
{<br />
interface IFoo;<br />
interface IFooStatics;<br />
interface IFooStatics2;<br />
<br />
runtimeclass Bar;<br />
runtimeclass BarResult;<br />
runtimeclass BazHappeningEventArgs;<br />
runtimeclass Foo;<br />
}<br />
}<br />
<br />
// Declaration block of generic interfaces with a type.<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
declare<br />
{<br />
interface Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*>;<br />
interface Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*>;<br />
}<br />
}<br />
}<br />
<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
// Definitions of enums, interfaces, structs and runtimeclasses from this file. For more on this, refer to the next section.<br />
<br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Windows.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Windows.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Windows.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Windows.SomeFeature.Bar *value);<br />
HRESULT CreateOtherFoo([out, retval] Windows.OtherFeature.OtherFoo **other_foo_obj);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Windows.SomeFeature.Foo*, Windows.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
<br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Windows.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Windows.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Windows.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Windows.SomeFeature.IFoo;<br />
interface Windows.SomeFeature.IFoo2;<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
(Note: I didn't work out this example into far detail, meaning some things may look incomplete.)<br />
<br />
==== Runtimeclasses ====<br />
<br />
Now, let's take a look at the definition part from above, in particular the "Foo" "runtimeclass". Runtime classes (I'll refer to them as just classes from now on), are basically COM-objects and the key feature of WinRT:<br />
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.<br />
<br />
Let's take a look at our example from above in more detail:<br />
*Foo resides in the "Wine.SomeFeature" namespace and has two interface members: "IFoo" and "IFoo2"<br />
*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.<br />
*It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
==== Interfaces ====<br />
<br />
Interfaces in WinRT are mostly the same as in COM, but they have some additional features.<br />
<br />
Let's take a closer look at "IFoo":<br />
*Like any COM-interface, IFoo has an interface-ID (UUID)<br />
*It's only meant to be used by the Foo class, thus marked with the "exclusiveto" property.<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
*The interface's contents:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
==== Properties ====<br />
<br />
You might already have noticed the huge amount of new properties IDL 3.0 brings with.<br />
This paragraph has a brief list of them:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime) class<br />
|-<br />
|| default || The default interface of an instantiated (runtime) class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| out || A value that is returned from a function, by reference - (Like out in C#)<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| retval || The value that's used as return value in the C++ WinRT API<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== Style ===<br />
<br />
WinRT components for Wine should be written in either Julliard style (e.g. ntdll, Windows.Gaming.Input) or WineD3D style (d3d11, vkd3d), with some minor additions:<br />
*In WinRT, lines can get very long due to the wild naming schemes introduced, so the imaginary max length of a line should be set at around 160 characters (instead of 120).<br />
*Replace STDMETHODCALLTYPE with WINAPI to reduce line length.<br />
<br />
<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4046Wine Developer's Guide/WinRT in Wine2022-08-27T20:50:59Z<p>BernhardKoelbl: </p>
<hr />
<div>__NUMBEREDHEADINGS__<br />
'''Authors:''' Bernhard Koelbl<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
=== IDL 3.0 ===<br />
<br />
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.<br />
<br />
==== Structure ====<br />
<br />
A WinRT IDL file from the Windows platform SDK is generally structured like this:<br />
<br />
<pre><br />
import "other.idl"<br />
import "other2.idl"<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses from other files.<br />
namespace Windows<br />
{<br />
namespace OtherFeature<br />
{<br />
typedef enum OtherFooEnum;<br />
<br />
interface OtherFoo;<br />
}<br />
}<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses in this file.<br />
namespace Windows<br />
{<br />
namespace SomeFeature <br />
{<br />
interface IFoo;<br />
interface IFooStatics;<br />
interface IFooStatics2;<br />
<br />
runtimeclass Bar;<br />
runtimeclass BarResult;<br />
runtimeclass BazHappeningEventArgs;<br />
runtimeclass Foo;<br />
}<br />
}<br />
<br />
// Declaration block of generic interfaces with a type.<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
declare<br />
{<br />
interface Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*>;<br />
interface Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*>;<br />
}<br />
}<br />
}<br />
<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
// Definitions of enums, interfaces, structs and runtimeclasses from this file. For more on this, refer to the next section.<br />
<br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Windows.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Windows.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Windows.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Windows.SomeFeature.Bar *value);<br />
HRESULT CreateOtherFoo([out, retval] Windows.OtherFeature.OtherFoo **other_foo_obj);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Windows.SomeFeature.Foo*, Windows.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
<br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Windows.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Windows.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Windows.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Windows.SomeFeature.IFoo;<br />
interface Windows.SomeFeature.IFoo2;<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
(Note: I didn't work out this example into far detail, meaning some things may look incomplete.)<br />
<br />
==== Runtimeclasses ====<br />
<br />
Now, let's take a look at the definition part from above, in particular the "Foo" "runtimeclass". Runtime classes (I'll refer to them as just classes from now on), are basically COM-objects and the key feature of WinRT:<br />
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.<br />
<br />
Let's take a look at our example from above in more detail:<br />
*Foo resides in the "Wine.SomeFeature" namespace and has two interface members: "IFoo" and "IFoo2"<br />
*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.<br />
*It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
==== Interfaces ====<br />
<br />
Interfaces in WinRT are mostly the same as in COM, but they have some additional features.<br />
<br />
Let's take a closer look at "IFoo":<br />
*Like any COM-interface, IFoo has an interface-ID (UUID)<br />
*It's only meant to be used by the Foo class, thus marked with the "exclusiveto" property.<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
*The interface's contents:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
==== Properties ====<br />
<br />
You might already have noticed the huge amount of new properties IDL 3.0 brings with.<br />
This paragraph has a brief list of them:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime) class<br />
|-<br />
|| default || The default interface of an instantiated (runtime) class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| out || A value that is returned from a function, by reference - (Like out in C#)<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| retval || The value that's used as return value in the C++ WinRT API<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4045Wine Developer's Guide/WinRT in Wine2022-08-27T20:47:08Z<p>BernhardKoelbl: </p>
<hr />
<div>__NUMBEREDHEADINGS__<br />
'''Authors:''' Bernhard Koelbl<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== IDL 3.0 ===<br />
<br />
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.<br />
<br />
==== Structure ====<br />
<br />
A WinRT IDL file from the Windows platform SDK is generally structured like this:<br />
<br />
<pre><br />
import "other.idl"<br />
import "other2.idl"<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses from other files.<br />
namespace Windows<br />
{<br />
namespace OtherFeature<br />
{<br />
typedef enum OtherFooEnum;<br />
<br />
interface OtherFoo;<br />
}<br />
}<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses in this file.<br />
namespace Windows<br />
{<br />
namespace SomeFeature <br />
{<br />
interface IFoo;<br />
interface IFooStatics;<br />
interface IFooStatics2;<br />
<br />
runtimeclass Bar;<br />
runtimeclass BarResult;<br />
runtimeclass BazHappeningEventArgs;<br />
runtimeclass Foo;<br />
}<br />
}<br />
<br />
// Declaration block of generic interfaces with a type.<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
declare<br />
{<br />
interface Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*>;<br />
interface Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*>;<br />
}<br />
}<br />
}<br />
<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
// Definitions of enums, interfaces, structs and runtimeclasses from this file. For more on this, refer to the next section.<br />
<br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Windows.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Windows.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Windows.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Windows.SomeFeature.Bar *value);<br />
HRESULT CreateOtherFoo([out, retval] Windows.OtherFeature.OtherFoo **other_foo_obj);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Windows.SomeFeature.Foo*, Windows.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
<br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Windows.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Windows.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Windows.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Windows.SomeFeature.IFoo;<br />
interface Windows.SomeFeature.IFoo2;<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
(Note: I didn't work out this example into far detail, meaning some things may look incomplete.)<br />
<br />
==== Runtimeclasses ====<br />
<br />
Now, let's take a look at the definition part from above, in particular the "Foo" "runtimeclass". Runtime classes (I'll refer to them as just classes from now on), are basically COM-objects and the key feature of WinRT:<br />
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.<br />
<br />
Let's take a look at our example from above in more detail:<br />
*Foo resides in the "Wine.SomeFeature" namespace and has two interface members: "IFoo" and "IFoo2"<br />
*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.<br />
*It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
==== Interfaces ====<br />
<br />
Interfaces in WinRT are mostly the same as in COM, but they have some additional features.<br />
<br />
Let's take a closer look at "IFoo":<br />
*Like any COM-interface, IFoo has an interface-ID (UUID)<br />
*It's only meant to be used by the Foo class, thus marked with the "exclusiveto" property.<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
*The interface's contents:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
==== Properties ====<br />
<br />
You might already have noticed the huge amount of new properties IDL 3.0 brings with.<br />
This paragraph has a brief list of them:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime) class<br />
|-<br />
|| default || The default interface of an instantiated (runtime) class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| out || A value that is returned from a function, by reference - (Like out in C#)<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| retval || The value that's used as return value in the C++ WinRT API<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4044Wine Developer's Guide/WinRT in Wine2022-08-27T20:34:46Z<p>BernhardKoelbl: </p>
<hr />
<div>__NUMBEREDHEADINGS__<br />
'''Authors:''' Bernhard Koelbl<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== IDL 3.0 ===<br />
<br />
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.<br />
<br />
==== Structure ====<br />
<br />
A WinRT IDL file from the Windows platform SDK is generally structured like this:<br />
<br />
<pre><br />
import "other.idl"<br />
import "other2.idl"<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses from other files.<br />
namespace Windows<br />
{<br />
namespace OtherFeature<br />
{<br />
typedef enum OtherFooEnum;<br />
<br />
interface OtherFoo;<br />
}<br />
}<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses in this file.<br />
namespace Windows<br />
{<br />
namespace SomeFeature <br />
{<br />
interface IFoo;<br />
interface IFooStatics;<br />
interface IFooStatics2;<br />
<br />
runtimeclass Bar;<br />
runtimeclass BarResult;<br />
runtimeclass BazHappeningEventArgs;<br />
runtimeclass Foo;<br />
}<br />
}<br />
<br />
// Declaration block of generic interfaces with a type.<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
declare<br />
{<br />
interface Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*>;<br />
interface Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*>;<br />
}<br />
}<br />
}<br />
<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
// Definitions of enums, interfaces, structs and runtimeclasses from this file. For more on this, refer to the next section.<br />
<br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Windows.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Windows.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Windows.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Windows.SomeFeature.Bar *value);<br />
HRESULT CreateOtherFoo([out, retval] Windows.OtherFeature.OtherFoo **other_foo_obj);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Windows.SomeFeature.Foo*, Windows.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
<br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Windows.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Windows.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Windows.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Windows.SomeFeature.IFoo;<br />
interface Windows.SomeFeature.IFoo2;<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
(Note: I didn't work out this example into far detail, meaning some things may look incomplete.)<br />
<br />
==== Runtimeclasses ====<br />
<br />
Now, let's take a look at the definition part, in particular the Foo "runtimeclass". Runtime classes (I'll refer to them as just classes from now on), are basically COM-objects and the key feature of WinRT:<br />
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.<br />
<br />
Let's take a look at our example from above in more detail:<br />
*Foo resides in the "Wine.SomeFeature" namespace and has two interface members: "IFoo" and "IFoo2"<br />
*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.<br />
*It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
==== Interfaces ====<br />
<br />
Interfaces in WinRT are mostly the same as in COM, but they have some additional features.<br />
<br />
Let's take a look at "IFoo".<br />
*Like any COM-interface, IFoo has an interface-ID (UUID) and it's only meant to be used by the Foo class (exclusiveto).<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
*The interface's contents:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
<br />
Summing up some properties:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime)class<br />
|-<br />
|| default || The default interface of an instantiated class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| out || A value that is returned from a function, by reference - (Like out in C#)<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| retval || The value that's used as return value in the C++ WinRT API<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4043Wine Developer's Guide/WinRT in Wine2022-08-27T18:39:04Z<p>BernhardKoelbl: </p>
<hr />
<div>__NUMBEREDHEADINGS__<br />
'''Authors:''' Bernhard Koelbl<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== IDL 3.0 ===<br />
<br />
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.<br />
<br />
=== Structure ===<br />
<br />
A WinRT IDL file from the Windows platform SDK is generally structured like this:<br />
<br />
<pre><br />
import "other.idl"<br />
import "other2.idl"<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses from other files.<br />
namespace Windows<br />
{<br />
namespace OtherFeature<br />
{<br />
typedef enum OtherFooEnum;<br />
<br />
interface OtherFoo;<br />
}<br />
}<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses in this file.<br />
namespace Windows<br />
{<br />
namespace SomeFeature <br />
{<br />
interface IFoo;<br />
interface IFooStatics;<br />
interface IFooStatics2;<br />
<br />
runtimeclass Bar;<br />
runtimeclass BarResult;<br />
runtimeclass BazHappeningEventArgs;<br />
runtimeclass Foo;<br />
}<br />
}<br />
<br />
// Declaration block of generic interfaces with a type.<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
declare<br />
{<br />
interface Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*>;<br />
interface Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*>;<br />
}<br />
}<br />
}<br />
<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
// Definitions of enums, interfaces, structs and runtimeclasses from this file. For more on this, refer to the next section.<br />
}<br />
}<br />
</pre><br />
<br />
(Note: I didn't work out this example into far detail, meaning some things may look incomplete.)<br />
<br />
==== Features ====<br />
<br />
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:<br />
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:<br />
<br />
<pre><br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Windows.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Windows.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Windows.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Windows.SomeFeature.IFoo;<br />
interface Windows.SomeFeature.IFoo2;<br />
}<br />
</pre><br />
<br />
This Foo class is in the "Wine.SomeFeature" namespace and exposes two interfaces: "IFoo" and "IFoo2":<br />
<br />
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.<br />
It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
Let's take a look at "IFoo":<br />
<br />
<pre><br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Windows.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Windows.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Windows.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Windows.SomeFeature.Bar *value);<br />
HRESULT CreateOtherFoo([out, retval] Windows.OtherFeature.OtherFoo **other_foo_obj);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Windows.SomeFeature.Foo*, Windows.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
</pre><br />
<br />
*Like any COM-interface, IFoo has an interface-ID (UUID) and it's only meant to be used by the Foo class (exclusiveto).<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
<br />
<br />
Let's take a look at the interface members:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
<br />
Summing up some properties:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime)class<br />
|-<br />
|| default || The default interface of an instantiated class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| out || A value that is returned from a function, by reference - (Like out in C#)<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| retval || The value that's used as return value in the C++ WinRT API<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4042Wine Developer's Guide/WinRT in Wine2022-08-27T18:16:29Z<p>BernhardKoelbl: </p>
<hr />
<div>__NUMBEREDHEADINGS__<br />
'''Authors:''' Bernhard Koelbl<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== IDL 3.0 ===<br />
<br />
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:<br />
<br />
=== Structure ===<br />
<br />
An IDL 3.0 file from the Windows platform SDK is generally structured like this:<br />
<br />
<pre><br />
import "other.idl"<br />
import "other2.idl"<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses from other files.<br />
namespace Windows<br />
{<br />
namespace OtherFeature<br />
{<br />
typedef enum OtherFooEnum;<br />
<br />
interface OtherFoo;<br />
}<br />
}<br />
<br />
// Forward declares of enums, interfaces, structs and runtimeclasses in this file.<br />
namespace Windows<br />
{<br />
namespace SomeFeature <br />
{<br />
interface IFoo;<br />
<br />
runtimeclass Foo;<br />
}<br />
}<br />
<br />
// Declaration block of generic interfaces with a type.<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
declare<br />
{<br />
interface Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*>;<br />
}<br />
}<br />
}<br />
<br />
namespace Windows<br />
{<br />
namespace SomeFeature<br />
{<br />
// Definitions of enums, interfaces, structs and runtimeclasses of this file. For more on this, refer to the next section.<br />
}<br />
}<br />
</pre><br />
<br />
==== Features ====<br />
<br />
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:<br />
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:<br />
<br />
<pre><br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Windows.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Windows.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Windows.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Windows.SomeFeature.IFoo;<br />
interface Windows.SomeFeature.IFoo2;<br />
}<br />
</pre><br />
<br />
This Foo class is in the "Wine.SomeFeature" namespace and exposes two interfaces: "IFoo" and "IFoo2":<br />
<br />
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.<br />
It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
Let's take a look at "IFoo":<br />
<br />
<pre><br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Windows.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Windows.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Windows.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Windows.SomeFeature.Bar *value);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Windows.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Windows.SomeFeature.Foo*, Windows.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
</pre><br />
<br />
*Like any COM-interface, IFoo has an interface-ID (UUID) and it's only meant to be used by the Foo class (exclusiveto).<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
<br />
<br />
Let's take a look at the interface members:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
<br />
Summing up some properties:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime)class<br />
|-<br />
|| default || The default interface of an instantiated class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4041Wine Developer's Guide/WinRT in Wine2022-08-26T15:58:27Z<p>BernhardKoelbl: </p>
<hr />
<div>__NUMBEREDHEADINGS__<br />
'''Authors:''' Bernhard Koelbl<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== IDL 3.0 ===<br />
<br />
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:<br />
<br />
==== Structure ====<br />
<br />
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:<br />
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:<br />
<br />
<pre><br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Wine.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Wine.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Wine.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Wine.SomeFeature.IFoo;<br />
interface Wine.SomeFeature.IFoo2;<br />
}<br />
</pre><br />
<br />
This Foo class is in the "Wine.SomeFeature" namespace and exposes two interfaces: "IFoo" and "IFoo2":<br />
<br />
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.<br />
It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
Let's take a look at "IFoo":<br />
<br />
<pre><br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Wine.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Wine.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Wine.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Wine.SomeFeature.Bar *value);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Wine.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
</pre><br />
<br />
*Like any COM-interface, IFoo has an interface-ID (UUID) and it's only meant to be used by the Foo class (exclusiveto).<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
<br />
<br />
Let's take a look at the interface members:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
<br />
Summing up some properties:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime)class<br />
|-<br />
|| default || The default interface of an instantiated class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4040Wine Developer's Guide/WinRT in Wine2022-08-26T15:35:52Z<p>BernhardKoelbl: </p>
<hr />
<div>__NOTOC__<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== IDL 3.0 ===<br />
<br />
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:<br />
<br />
==== Structure ====<br />
<br />
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:<br />
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:<br />
<br />
<pre><br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Wine.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Wine.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Wine.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Wine.SomeFeature.IFoo;<br />
interface Wine.SomeFeature.IFoo2;<br />
}<br />
</pre><br />
<br />
This Foo class is in the "Wine.SomeFeature" namespace and exposes two interfaces: "IFoo" and "IFoo2":<br />
<br />
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.<br />
It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
Let's take a look at "IFoo":<br />
<br />
<pre><br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Wine.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Wine.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Wine.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Wine.SomeFeature.Bar *value);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Wine.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
</pre><br />
<br />
*Like any COM-interface, IFoo has an interface-ID (UUID) and it's only meant to be used by the Foo class (exclusiveto).<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
<br />
<br />
Let's take a look at the interface members:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
<br />
Summing up some properties:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime)class<br />
|-<br />
|| default || The default interface of an instantiated class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4039Wine Developer's Guide/WinRT in Wine2022-08-26T15:34:31Z<p>BernhardKoelbl: </p>
<hr />
<div>__NOTOC__<br />
{{wip}}<br />
== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== IDL 3.0 ===<br />
<br />
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:<br />
<br />
==== Structure ====<br />
<br />
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:<br />
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:<br />
<br />
<pre><br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Wine.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Wine.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Wine.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Windows.SomeFeature.IFoo;<br />
interface Windows.SomeFeature.IFoo2;<br />
}<br />
</pre><br />
<br />
This Foo class is in the "Wine.SomeFeature" namespace and exposes two interfaces: "IFoo" and "IFoo2":<br />
<br />
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.<br />
It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
Let's take a look at "IFoo":<br />
<br />
<pre><br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Wine.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Windows.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Wine.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Wine.SomeFeature.Bar *value);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Wine.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
</pre><br />
<br />
*Like any COM-interface, IFoo has an interface-ID (UUID) and it's only meant to be used by the Foo class (exclusiveto).<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
<br />
<br />
Let's take a look at the interface members:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
<br />
Summing up some properties:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime)class<br />
|-<br />
|| default || The default interface of an instantiated class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
----<br />
[[Category:Development]]</div>BernhardKoelblhttps://wiki.winehq.org/index.php?title=Wine_Developer%27s_Guide/WinRT_in_Wine&diff=4038Wine Developer's Guide/WinRT in Wine2022-08-26T15:32:34Z<p>BernhardKoelbl: Initial page for WinRT development.</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is WinRT? ===<br />
<br />
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.<br />
<br />
Internally, WinRT is basically [[Wine Developer's Guide/COM in Wine|COM]] with extra spice and some "new" concepts.<br />
<br />
== Writing WinRT components for Wine ==<br />
<br />
=== IDL 3.0 ===<br />
<br />
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:<br />
<br />
==== Structure ====<br />
<br />
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:<br />
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:<br />
<br />
<pre><br />
[<br />
activatable(Windows.Foundation.UniversalApiContract, 1.0),<br />
activatable(Wine.SomeFeature.IFooFactory, Windows.Foundation.UniversalApiContract, 1.0),<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
marshaling_behavior(agile),<br />
static(Wine.SomeFeature.IFooStatics, Windows.Foundation.UniversalApiContract, 1.0),<br />
static(Wine.SomeFeature.IFooStatics2, Windows.Foundation.UniversalApiContract, 5.0)<br />
]<br />
runtimeclass Foo<br />
{<br />
[default] interface Windows.SomeFeature.IFoo;<br />
interface Windows.SomeFeature.IFoo2;<br />
}<br />
</pre><br />
<br />
This Foo class is in the "Wine.SomeFeature" namespace and exposes two interfaces: "IFoo" and "IFoo2":<br />
<br />
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.<br />
It also exposes static functions, through the interfaces "IFooStatics" and "IFooStatics2".<br />
<br />
Let's take a look at "IFoo":<br />
<br />
<pre><br />
[<br />
contract(Windows.Foundation.UniversalApiContract, 1.0),<br />
exclusiveto(Wine.SomeFeature.Foo),<br />
uuid(abababab-cdcd-efef-1234-56789abcdef)<br />
]<br />
interface IFoo : IInspectable<br />
requires<br />
Windows.SomeFeature.IFoo2<br />
{<br />
[propget] HRESULT MyProperty1([out, retval] Wine.SomeFeature.Bar **value);<br />
[propput] HRESULT MyProperty1(Wine.SomeFeature.Bar *value);<br />
HRESULT DoFoobarAsync([out, retval] Windows.Foundation.IAsyncOperation<Wine.SomeFeature.BarResult*> **operation);<br />
[eventadd] HRESULT OnBazHappening(<br />
[in] Windows.Foundation.TypedEventHandler<Wine.SomeFeature.Foo*, Wine.SomeFeature.BazHappeningEventArgs*> *handler,<br />
[out, retval] EventRegistrationToken *token);<br />
[eventremove] HRESULT OnBazHappening([in] EventRegistrationToken token);<br />
}<br />
</pre><br />
<br />
*Like any COM-interface, IFoo has an interface-ID (UUID) and it's only meant to be used by the Foo class (exclusiveto).<br />
*It inherits from IInspectable, which in turn also inherits IUnknown.<br />
*Any class that implements the IFoo interface also needs to implement the IFoo2 interface, denoted by "requires".<br />
<br />
<br />
Let's take a look at the interface members:<br />
# IFoo has a property with getter and setter for a Bar object: "MyProperty1".<br />
# IFoo has a method, which does its work asynchronously using the parameterized interface "IAsyncOperation".<br />
# IFoo provides an event system "OnBazHappening".<br />
<br />
<br />
Summing up some properties:<br />
<br />
{|class="wikitable"<br />
!Property<br />
!Description<br />
|-<br />
|| activatable || An activatable (runtime)class<br />
|-<br />
|| default || The default interface of an instantiated class<br />
|-<br />
|| eventadd || Function to add an event handler<br />
|-<br />
|| eventremove || Function to remove an event handler<br />
|-<br />
|| propget || Getter method of a property<br />
|-<br />
|| propput || Setter method of a property<br />
|-<br />
|| static || A static interface to a class<br />
|-<br />
|}<br />
----<br />
[[Category:Development]]</div>BernhardKoelbl