winrt topic

Windows Runtime API

The Windows Runtime (WinRT) is a suite of APIs and architectural model, introduced in Windows 8, that powers the latest generation of Windows APIs. It is an evolution of the COM API that is designed for access from a variety of languages. WinRT introduces standardized interfaces for collections (e.g. IVectorView), as well as support for generic types and asynchronous programming models.

Initializing the Windows Runtime

All threads that activate and interact with Windows Runtime objects must be initialized prior to calling into the Windows Runtime. This package provides the winrtInitialize helper function to do this. Call the matching winrtUninitialize function to close the Windows Runtime on the current thread. A successful call to winrtInitialize should be balanced with a corresponding call to winrtUninitialize.

Instantiating Windows Runtime objects

The CreateObject function provides a convenient way to create a new Windows Runtime object. This returns a generic Pointer<COMObject>, which can be cast to the object type desired. For example:

final comObject = CreateObject('Windows.Globalization.Calendar', IID_ICalendar);
final calendar = ICalendar(comObject);

The object should be disposed of when it is no longer in use, for example:

free(calendar.ptr);

Strings (Windows Runtime)

Windows Runtime APIs use HSTRING as their native type. An HSTRING is an immutable string object, which is created with the WindowsCreateString API and deleted with the WindowsDeleteString API. The HSTRING itself is an integer value, just like other HANDLE objects in the Win32 programming interface.

Helper functions exist to easily convert between the Dart String type and Windows Runtime strings: specifically, convertToHString and convertFromHString.

Make sure you dispose of HSTRINGs by calling WindowsDeleteString; you do not need to free the pointer itself, since Windows reference counts the backing store and frees the memory when the reference count reaches 0.

Mixins

IApplicationData winrt Interface
IAsyncAction winrt Interface

Functions

convertFromHString(int hstring) → String winrt
Takes a HSTRING (a WinRT String handle), and converts it to a Dart String.
convertToHString(String string) → int winrt
Takes a Dart String and converts it to an HSTRING (a WinRT String), returning an integer handle.
CreateActivationFactory(String className, String iid, {Allocator allocator = calloc}) → Pointer<COMObject> winrt
Creates the activation factory for the specified runtime class using the className and iid.
CreateObject(String className, String iid) → Pointer<COMObject> winrt
Creates a WinRT object.
MetaDataGetDispenser(Pointer<GUID> rclsid, Pointer<GUID> riid, Pointer<Pointer<NativeType>> ppv) → int winrt
Creates a dispenser class.
RoActivateInstance(int activatableClassId, Pointer<Pointer<COMObject>> instance) → int winrt
Activates the specified Windows Runtime class.
RoGetActivationFactory(int activatableClassId, Pointer<GUID> iid, Pointer<Pointer<NativeType>> factory) → int winrt
Gets the activation factory for the specified runtime class.
RoGetApartmentIdentifier(Pointer<Uint64> apartmentIdentifier) → int winrt
Gets a unique identifier for the current apartment.
RoGetMetaDataFile(int name, Pointer<IntPtr> metaDataDispenser, Pointer<IntPtr> metaDataFilePath, Pointer<Pointer<NativeType>> metaDataImport, Pointer<Uint32> typeDefToken) → int winrt
Locates and retrieves the metadata file that describes the Application Binary Interface (ABI) for the specified typename.
RoInitialize(int initType) → int winrt
Initializes the Windows Runtime on the current thread with the specified concurrency model.
RoUninitialize() → void winrt
Closes the Windows Runtime on the current thread.
WindowsCompareStringOrdinal(int string1, int string2, Pointer<Int32> result) → int winrt
Compares two specified HSTRING objects and returns an integer that indicates their relative position in a sort order.
WindowsConcatString(int string1, int string2, Pointer<IntPtr> newString) → int winrt
Concatenates two specified strings.
WindowsCreateString(Pointer<Utf16> sourceString, int length, Pointer<IntPtr> string) → int winrt
Creates a new HSTRING based on the specified source string.
WindowsDeleteString(int string) → int winrt
Decrements the reference count of a string buffer.
WindowsDeleteStringBuffer(int bufferHandle) → int winrt
Discards a preallocated string buffer if it was not promoted to an HSTRING.
WindowsDuplicateString(int string, Pointer<IntPtr> newString) → int winrt
Creates a copy of the specified string.
WindowsGetStringLen(int string) → int winrt
Gets the length, in Unicode characters, of the specified string.
WindowsGetStringRawBuffer(int string, Pointer<Uint32> length) → Pointer<Utf16> winrt
Retrieves the backing buffer for the specified string.
WindowsIsStringEmpty(int string) → int winrt
Indicates whether the specified string is the empty string.
WindowsPreallocateStringBuffer(int length, Pointer<Pointer<Uint16>> charBuffer, Pointer<IntPtr> bufferHandle) → int winrt
Allocates a mutable character buffer for use in HSTRING creation.
WindowsPromoteStringBuffer(int bufferHandle, Pointer<IntPtr> string) → int winrt
Creates an HSTRING from the specified HSTRING_BUFFER.
WindowsReplaceString(int string, int stringReplaced, int stringReplaceWith, Pointer<IntPtr> newString) → int winrt
Replaces all occurrences of a set of characters in the specified string with another set of characters to create a new string.
WindowsStringHasEmbeddedNull(int string, Pointer<Int32> hasEmbedNull) → int winrt
Indicates whether the specified string has embedded null characters.
WindowsSubstring(int string, int startIndex, Pointer<IntPtr> newString) → int winrt
Retrieves a substring from the specified string. The substring starts at the specified character position.
WindowsSubstringWithSpecifiedLength(int string, int startIndex, int length, Pointer<IntPtr> newString) → int winrt
Retrieves a substring from the specified string. The substring starts at a specified character position and has a specified length.
WindowsTrimStringEnd(int string, int trimString, Pointer<IntPtr> newString) → int winrt
Removes all trailing occurrences of a specified set of characters from the source string.
WindowsTrimStringStart(int string, int trimString, Pointer<IntPtr> newString) → int winrt
Removes all leading occurrences of a specified set of characters from the source string.
winrtInitialize() → void winrt
Initializes the Windows Runtime on the current thread with a single-threaded concurrency model.
winrtUninitialize() → void winrt
Closes the Windows Runtime on the current thread.