Windows Runtime C++ Template Library
The Windows Runtime C++ Template Library (WRL) is a COM-based template library that provides a low-level way to use Windows Runtime components.
Benefits
The Windows Runtime is implemented by using Component Object Model (COM) technology. COM depends on housekeeping techniques such as reference-counting to manage the lifetime of objects, and on testing HRESULT values to determine whether an operation succeeded or failed. To successfully write a COM app or library, you must carefully follow COM rules and techniques.
The Visual C++ component extensions (C++/CX) is a high-level, language-based way to use Windows Runtime components. Both the WRL and C++/CX simplify the writing of code for the Windows Runtime by automatically performing COM housekeeping tasks on your behalf.
The WRL and C++/CX provide different benefits. Here are some reasons you might want to use the WRL instead of C++/CX:
The WRL is a compiler-agnostic way to create and consume Windows Runtime APIs. Even if you don’t use the Microsoft compiler, linker, and other development tools, you can use WRL to write apps that use Windows Runtime components, or write custom Windows Runtime components that can be used by others.
By using the WRL, you can optimize your code for performance or for specific scenarios. C++/CX doesn’t expose the underlying COM technology in the Windows Runtime. However, your app or component might require control of the underlying COM code to better create or consume Windows Runtime APIs. When you use the WRL, you can control critical COM directly, but also allow the WRL to control the remaining COM on your behalf. You have complete command.
C++/CX represents COM HRESULT values as exceptions. If you’ve inherited a code base that uses COM, or one that doesn’t use exceptions, you might find that the WRL is a more natural way to work with the Windows Runtime because you don’t have to use exceptions.
Although C++/CX is easy to use, you might prefer not to use “handle to object (^)”, ref new, ref class, and its other language features to write your code. WRL provides an alternative for people who want to use a template library and standard C++ to write Windows Runtime code.
The purpose and design of the WRL is inspired by the Active Template Library (ATL), which is a set of template-based C++ classes that simplify the programming of COM objects. If you already know ATL, you might find that WRL programming is easier.
Overview (WRL)
The Windows Runtime C++ Template Library (WRL) is a set of template-based C++ classes, functions, and macros that enable you to write Component Object Model (COM) objects. WRL is optimized to enable you to use types and programming patterns provided by the Windows Runtime.
WRL compared to ATL
WRL is similar to the Active Template Library (ATL) because it enables you to create small, fast COM objects. WRL and ATL also share concepts such as defining objects in modules, explicitly registering interfaces, and openly creating objects with factories. You might be comfortable using WRL if you’re familiar with using ATL.
WRL differs from the ATL because it omits direct support for key COM features such as stock implementations, dual interfaces, standard enumerator interfaces, connection points, tear-off interfaces, and ActiveX controls.
Concepts
WRL provides types that represent a few basic concepts. The following sections describe those types.
ComPtr
A ComPtr object is a smart pointer type that represents the interface specified by the template parameter. Use a ComPtr to declare a variable that can access the members of an object derived from the interface. ComPtr automatically maintains a reference count for the underlying interface pointer and releases the interface when the reference count goes to zero.
For more information, see Create and Consume Objects (WRL).
RuntimeClass
A RuntimeClass object represents an instantiated class that inherits a set of specified interfaces. A RuntimeClass object can provide a combination of support for one or more of the Windows Runtime, classic COM, or a weak reference.
For more information, see Create and Consume Objects (WRL).
Module
The Module class represents a collection of related objects. A Module object manages class factories, which create objects; and registration, which enables other applications can use an object.
For more information, see Create and Consume Objects (WRL).
Callback
The Callback function creates an object whose member function is an event handler (a callback method). Use the Callback function to write asynchronous operations.
For more information, see Asynchronous Operations (WRL).
EventSource
An EventSource object is used to manage delegate event handlers. Use WRL to implement a delegate, and use EventSource to add, remove, and invoke delegates.
AsyncBase
The AsyncBase class provides virtual methods that represent the Windows Runtime asynchronous programming model. Override the members in this class to create a custom class that can start, stop, or check the progress of an asynchronous operation.
For more information about asynchronous operations, see Asynchronous Operations (WRL).
FtmBase
The FtmBase class represents a free-threaded marshaler object. FtmBase creates a global interface table (GIT), and helps manage marshaling and proxy objects.
WeakRef
A WeakRef smart-pointer represents a weak reference, which references an object that might or might not be accessible. A WeakRef object can be used by only the Windows Runtime, not classic COM.
A WeakRef typically represents an object whose existence is controlled by an external thread or application. For example, a WeakRef can reference a file object. While the file is open, the WeakRef is valid and the referenced file is accessible. But when the file is closed, the WeakRef is invalid and the file is inaccessible.
