Building ActiveX servers in Qt

Whether your COM server should run as a stand-alone executable or as a shared library in the client process depends mainly on the type of COM objects you want to provide in the server.

An executable server has the advantage of being able to run as a stand-alone application, but adds considerable overhead to the communication between the COM client and the COM object. If the control has a programming error only the server process running the control will crash, and the client application will probably continue to run. Not all COM clients support executable servers.

An in-process server is usually smaller and has faster startup time. The communication between client and server is done directly through virtual function calls and does not introduce the overhead required for remote procedure calls. However, if the server crashes the client application is likely to crash as well, and not every functionality is available for in-process servers (i.e. register in the COM's running-object-table).

Both server types can use Qt either as a shared library, or statically linked into the server binary.

For the ActiveQt specific post-processing steps to work the server has to meet some requirements:

• All controls exposed can be created with nothing but a QApplication instance being present

• The initial linking of the server includes a temporary type library resource

• All dependencies required to run the server are in the system path (or in the path used by the calling environment; note that Visual Studio has its own set of environment variables listed in the Tools|Options|Directories dialog).

If those requirements are not met one ore more of the following errors are likely to occur:

The Server Executable Crashes▲

The Server Executable Is Not a Valid Win32 Application▲

"Unable to locate DLL"▲

"Cannot open file ..."▲

The Control Cannot be Instantiated▲

The Qt data types that are supported for properties are:

The Qt data types that are supported for parameters in signals and slots are:

Also supported are exported enums and flags (see Q_ENUMS() and Q_FLAGS()). The in-parameter types are also supported as return values.

Properties and signals/slots that have parameters using any other data types are ignored by the ActiveQt framework.

COM objects can have multiple sub-objects that can represent a sub element of the COM object. A COM object representing a multi-document spread sheet application can for example provide one sub-object for each spread sheet.

Any QObject subclass can be used as the type for a sub object in ActiveX, as long as it is known to the QAxFactory. Then the type can be used in properties, or as the return type or parameter of a slot.

To make the properties bindable for the ActiveX client, use multiple inheritance from the QAxBindable class:

#include <QAxBindable>
#include <QWidget>

class MyActiveX : public QWidget, public QAxBindable
{
    Q_OBJECT

When implementing the property write functions, use the QAxBindable class's requestPropertyChange() and propertyChanged() functions to allow ActiveX clients to bind to the control properties. (3)

The compiler/linker errors listed are based on those issued by the Microsoft Visual C++ 6.0 compiler.

"No overloaded function takes 2 parameters"▲

MyFactory(const QUuid &, const QUuid &);

"Syntax error: bad suffix on number"▲

"Unresolved external symbol _ucm_instantiate"▲

"_ucm_initialize already defined in ..."▲

ActiveX servers written with Qt can use Qt either as a shared library, or have Qt linked statically into the binary. Both ways will produce rather large packages (either the server binary itself becomes large, or you have to ship the Qt DLL).

Installing Stand-Alone Servers▲

Installing In-Process Servers▲

HMODULE dll = LoadLibrary("myserver.dll");
typedef HRESULT(__stdcall *DllRegisterServerProc)();
DllRegisterServerProc DllRegisterServer =
    (DllRegisterServerProc)GetProcAddress(dll, "DllRegisterServer");

HRESULT res = E_FAIL;
if (DllRegisterServer)
    res = DllRegisterServer();
if (res != S_OK)
    // error handling

Distributing Servers over the Internet▲

[version]
    signature="$CHICAGO$"
    AdvancedINF=2.0
 [Add.Code]
    simpleax.exe=simpleax.exe
 [simpleax.exe]
    file-win32-x86=thiscab
    clsid={DF16845C-92CD-4AAB-A982-EB9840E74669}
    RegisterServer=yes

cabarc N simpleax.cab simpleax.exe simple.inf

The following is largly based on our own experiements with ActiveX controls and client applications, and is by no means complete.

Supported Clients▲

Unsupported Clients▲

The Server Does Not Respond▲

The Object Cannot Be Created▲

To debug an in-process server in Visual Studio, set the server project as the active project, and specify a client "executable for debug session" in the project settings (e.g. use the ActiveX Test Container). You can set breakpoints in your code, and also step into ActiveQt and Qt code if you installed the debug version.

To debug an executable server, run the application in a debugger and start with the command line parameter -activex. Then start your client and create an instance of your ActiveX control. COM will use the existing process for the next client trying to create an ActiveX control.

If you develop components you might want to control who is able to instantiate those components. Since the server binary can be shipped to and registered on any client machine it is possible for anybody to use those components in his own software.

Licensing components can be done using a variety of techniques, e.g. the code creating the control can provide a license key, or the machine on which the control is supposed to run needs to be licensed.

To mark a Qt class as licensed specify a "LicenseKey" using the Q_CLASSINFO() macro.

class MyLicensedControl : public QWidget
{
    Q_OBJECT
    Q_CLASSINFO("LicenseKey", "<key string>")
    ...
};

The key is required to be able to create an instance of MyLicensedControl on a machine that is not licensed itself. The licensed developer can now redistributes the server binary with his application, which creates the control using the value of "LicenseKey", while users of the application cannot create the control without the license key.

If a single license key for the control is not sufficient (ie. you want differnet developers to receive different license keys) you can specify an empty key to indicate that the control requires a license, and reimplement QAxFactory::validateLicenseKey() to verify that a license exists on the system (ie. through a license file).

ActiveX controls provided by ActiveQt servers support a minimal set of COM interfaces to implement the OLE specifications. When the ActiveX class inherits from the QAxBindable class it can also implement additional COM interfaces.

Create a new subclass of QAxAggregated and use multiple inheritance to subclass additional COM interface classes.

class AxImpl : public QAxAggregated, public ISomeCOMInterface
{
public:
    AxImpl() {}

    long queryInterface(const QUuid &iid, void **iface);

    // IUnknown
    QAXAGG_IUNKNOWN

    // ISomeCOMInterface
    ...
}

Reimplement the QAxAggregated::queryInterface() function to support the additional COM interfaces.

long AxImpl::queryInterface(const QUuid &iid, void **iface)
{
    *iface = 0;
    if (iid == IID_ISomeCOMInterface)
        *iface = (ISomeCOMInterface *)this;
    else
        return E_NOINTERFACE;

    AddRef();
    return S_OK;
}

Since ISomeCOMInterface is a subclass of IUnknown you will have to implement the QueryInterface(), AddRef(), and Release() functions. Use the QAXAGG_IUNKNOWN macro in your class definition to do that. If you implement the IUnknown functions manually, delegate the calls to the interface pointer returned by the QAxAggregated::controllingUnknown() function, e.g.

HRESULT AxImpl::QueryInterface(REFIID iid, void **iface)
{
    return controllingUnknown()->QueryInterface(iid, iface);
}

Do not support the IUnknown interface itself in your queryInterface() implementation.

Implement the methods of the COM interfaces, and use QAxAggregated::object() if you need to make calls to the QObject subclass implementing the control.

In your QAxBindable subclass, implement QAxBindable::createAggregate() to return a new object of the QAxAggregated subclass.

class MyActiveX : public QWidget, public QAxBindable
{
    Q_OBJECT

public:
    MyActiveX(QWidget *parent);

    QAxAggregated *createAggregate()
    {
        return new AxImpl();
    }
};