Tag Archives: WRL

WRL and Standard ISO C++

Here is three new technical articles about how to write WinRT components using Windows Runtime Library (WRL) with Standard ISO C++ but not C++/CX. There are few documentation about that.

Windows C++

WRL and C++ | WRL and Async with C++ | WRL and STL collections with C++

It is all about how to implement those COM components using the WRL template library.

The WRL project template to download

Just update your Visual Studio to download the WRL Project template here. It allows to target WinRT component.

Be careful, you have to update your project with Linker -> Windows Metadata -> Generate Windows Metadata to TRUE.

This project template allows to build WinRT components using the real C++. Not the C++/CX compiler extensions.

Building WinRT or COM Components with C++ and WRL

When you want to make Windows 8.x applications using C++, there are few possibilities:

  • using C++/CX which are C++ compiler extensions
  • using WRL in standard C++ project

C++/CX is a complete change for writting C++ classes. The pointer and references symbols have changed. You have to pass only Windows Runtime types in your methods. Objects need to be constructed using ref new instead of new. Example:

// h file
namespace WindowsRuntimeComponent1
{
public ref class Logger sealed
{
public:
Logger();

public:
void LogInfo(String^ message);
};
}

// cpp file
using namespace WindowsRuntimeComponent1;

Logger::Logger()
{
}

void Logger::LogInfo(String^ message)
{
std::wstring str = message->Data();
String^ str2 = ref new String();
str2 = L"hello String^";
}

C++/CX is easy but your code is completely stucked with thoses ugly C++/CX extensions. There is another way to make WinRT components. This is the Microsoft way of doing things. It is called WRL, Windows Runtime Library. It is like ATL, the new ATL. Here is an example of a WinRT component using WRL:

// idl file
import "inspectable.idl";
import "Windows.Foundation.idl";

#define COMPONENT_VERSION 1.0

namespace Library1
{
interface ILogger;
runtimeclass Logger;

[uuid(3EC4B4D6-14A6-4D0D-BB96-31DA25224A15), version(COMPONENT_VERSION), exclusiveto(Logger)]
interface ILogger : IInspectable
{
HRESULT LogInfo([in] HSTRING value);
HRESULT GetInt32([out] int * pValue);
}

[version(COMPONENT_VERSION), activatable(COMPONENT_VERSION)]
runtimeclass Logger
{
[default] interface ILogger;
}
}

// h file
namespace ABI
{
namespace Library1
{
class Logger : public RuntimeClass<ILogger>
{
InspectableClass(L"Library1.Logger", BaseTrust)

public:
Logger();

public:
STDMETHOD(LogInfo)(HSTRING value);
STDMETHOD(GetInt32)(int * pValue);
};

ActivatableClass(Logger);
}
}

// cpp file
namespace ABI
{
namespace Library1
{
Logger::Logger()
{
}

STDMETHODIMP Logger::LogInfo(HSTRING value)
{
HString str;
str.Set(value);
std::wstring ws = str.GetRawBuffer(nullptr);
return S_OK;
}

STDMETHODIMP Logger::GetInt32(int * pValue)
{
*pValue = 10;
return S_OK;
}
}
}

With this kind of code, you stay with the real C++ and you use the built-in Windows type.
For string handling, there is a new handle or pointer called HSTRING and the WRL class that handles it is HString.

With WRL you can also create standard COM components. You just have to change the header or your classes to use a different RuntimeClass template and adjust your IDL file to use COM built-in types:

// idl file
import "oaidl.idl";
import "ocidl.idl";

#define COMPONENT_VERSION 1.0

[uuid(3AAF07AA-A699-4E7C-8F01-BFF237D22B1B), version(COMPONENT_VERSION)]
interface ILogger : IUnknown
{
HRESULT LogInfo([in] BSTR bstrMessage);
}

[uuid(F15D3912-E8B8-40C8-8CF3-354F0B8B93CC), version(COMPONENT_VERSION)]
library WRLCOMLibrary1
{
[uuid(75DB8F5A-F13F-4E16-A487-9CD26A874654), version(COMPONENT_VERSION)]
coclass Logger
{
[default] interface ILogger;
}
}

// h file
class Logger : public RuntimeClass<RuntimeClassFlags<ClassicCom>, ILogger>
{
public:
Logger();

public:
STDMETHOD(LogInfo)(BSTR bstrMessage);
};

CoCreatableClass(Logger);

This kind of construction works if you build a standard Win32 dll and add runtimeobject.lib to your linker input.

MSDN Library Visual C++ 2012 RC – Windows Runtime C++ Template Library Overview and Benefits

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.