Создание серверов ActiveX в Qt

Модуль QAxServer является частью фреймворка ActiveQt. Он состоит из трёх классов:

• QAxFactory определяет фабрику для создания COM-объектов.
• QAxBindable предоставляет интерфейс между виджетом Qt и COM-объектом.
• QAxAggregated может быть переопределён для реализации дополнительных COM-интерфейсов.

Предоставлены примеры реализации ActiveX-контролей и COM-объектов.

Темы:

Использование библиотеки

Для преобразования стандартного приложения Qt в COM-сервер с помощью библиотеки QAxServer необходимо добавить axserver к переменной QT в файле .pro.

Сервер исполняемого файла вне процесса генерируется из файла .pro, как показано ниже:

TEMPLATE = app
QT  += axserver

RC_FILE  = qaxserver.rc
...

Для создания сервера внутри процесса используйте файл .pro следующим образом:

TEMPLATE = lib
QT += axserver
CONFIG  += dll

DEF_FILE = qaxserver.def
RC_FILE  = qaxserver.rc
...

Файлы qaxserver.rc и qaxserver.def являются частью фреймворка и могут быть использованы из их стандартного расположения (указать путь в файле .pro) или скопированы в каталог проекта. Вы можете изменять эти файлы, пока они содержат любой файл в качестве записи типа библиотеки, например, добавить информацию о версии или указать другой значок инструментария.

Использование модуля axserver заставит инструмент qmake добавить необходимые шаги сборки в систему сборки:

• Связать двоичный файл с qaxserver.lib вместо qtmain.lib
• Вызвать инструмент idc для генерации файла IDL для COM-сервера
• Компилировать IDL в библиотеку типов с помощью инструмента MIDL (часть установки компилятора)
• Прикрепить полученную библиотеку типов в качестве двоичного ресурса к двоичному файлу сервера (опять же, используя инструмент idc)
• Зарегистрировать сервер

Чтобы пропустить этап пост-обработки, также установите конфигурацию qaxserver_no_postlink.

Кроме того, вы можете указать номер версии с помощью переменной VERSION, например:

TEMPLATE = lib
VERSION = 2.5
...

Указанный номер версии будет использоваться как версия библиотеки типов и сервера при регистрации.

Сервер вне процесса против сервера внутри процесса

Выбор между сервером COM, работающим как автономный исполняемый файл, или как общая библиотека в процессе клиента, зависит главным образом от типа COM-объектов, которые вы хотите предоставить на сервере.

Сервер исполняемого файла имеет преимущество в работе в качестве автономного приложения, но добавляет значительную нагрузку на обмен данными между COM-клиентом и COM-объектом. Если в контроле есть ошибка программирования, то только процесс сервера, выполняющий контроль, потерпит крах, а приложение-клиент, вероятно, продолжит работу. Не все COM-клиенты поддерживают серверы исполняемых файлов.

Сервер внутри процесса обычно меньше и имеет более быстрое время запуска. Обмен данными между клиентом и сервером выполняется напрямую через виртуальные вызовы функций и не вводит накладные расходы, необходимые для вызовов удалённых процедур. Однако, если сервер потерпит крах, приложение-клиент, вероятно, также потерпит крах, и не все функции доступны для серверов внутри процесса (например, регистрация в таблице объектов COM).

Оба типа серверов могут использовать Qt как общую библиотеку или статически скомпилированную в двоичный файл сервера.

Типичные ошибки во время этапов пост-сборки

Для работы специфических для ActiveQt шагов пост-обработки сервер должен соответствовать некоторым требованиям:

• Все экспонируемые элементы управления могут быть созданы только при наличии экземпляра QApplication
• Начальная компоновка сервера включает временный ресурс библиотеки типов
• Все зависимости, необходимые для запуска сервера, находятся в системном пути (или в пути, используемом вызывающей средой; обратите внимание, что Visual Studio имеет свой собственный набор переменных среды, перечисленных в диалоговом окне Инструменты | Параметры | Каталоги).

Если эти требования не выполнены, одна или несколько из следующих ошибок могут возникнуть:

Исполняемый файл сервера терпит крах

Для генерации IDL, виджеты, экспонируемые как ActiveX-контролы, должны быть инициализированы (вызывается конструктор). В этот момент ничего кроме объекта QApplication не существует. Конструктор вашего виджета не должен полагаться на создание других объектов, например, он должен проверять указатели null.

Для отладки сервера запустите его с параметром -dumpidl outputfile и проверьте, где он терпит крах.

Обратите внимание, что функции контроля не вызываются.

Исполняемый файл сервера не является корректным приложением Win32

Прикрепление библиотеки типов повредило двоичный файл сервера. Это ошибка Windows и происходит только со сборками релиз.

Первый этап компоновки должен скомпоновать фиктивную библиотеку типов в исполняемый файл, которую можно заменить позже с помощью idc. Добавьте файл ресурсов с библиотекой типов в свой проект, как показано в примерах.

"Не удаётся найти DLL"

Система сборки должна запустить исполняемый файл сервера для генерации определения интерфейса и регистрации сервера. Если динамическая библиотека, с которой связывается сервер, не находится в пути, это может не удаться (например, Visual Studio вызывает сервер, используя настройки среды, указанные в параметре "Каталоги"). Убедитесь, что все DLL и плагины, необходимые для вашего сервера, находятся в каталоге, который указан в пути, как показано в сообщении об ошибке (см. также Инструмент развертывания Windows).

"Невозможно открыть файл ..."

Сервер ActiveX не смог корректно завершить работу, когда последний клиент перестал его использовать. Обычно для завершения приложения требуется около двух секунд, но вам может потребоваться использовать диспетчер задач для завершения процесса (например, когда клиент не высвобождает элементы управления должным образом).

Элемент управления не может быть инициализирован

В этом случае может помочь регистрация сервера как администратора.

Реализация элементов управления

Для реализации COM-объекта с помощью Qt создайте подкласс QObject или любого существующего подкласса QObject. Если класс является подклассом QWidget, COM-объект будет ActiveX-контролем.

#include <QWidget>

class MyActiveX : public QWidget
{
    Q_OBJECT

Макрос Q_OBJECT необходим для предоставления метаобъектной информации о виджете фреймворку ActiveQt.

Q_CLASSINFO("ClassID", "{1D9928BD-4453-4bdd-903D-E525ED17FDE5}")
Q_CLASSINFO("InterfaceID", "{99F6860E-2C5A-42ec-87F2-43396F4BE389}")
Q_CLASSINFO("EventsID", "{0A3E9F27-E4F1-45bb-9E47-63099BCCD0E3}")

Используйте макрос Q_CLASSINFO() для указания идентификаторов COM для COM-объекта. ClassID и InterfaceID необходимы, в то время как EventsID требуется только в том случае, если ваш объект имеет сигналы. Для генерации этих идентификаторов используйте системные инструменты, такие как uuidgen или guidgen.

Вы можете указать дополнительные атрибуты для каждого из ваших классов; см. Информацию о классе и настройки для получения подробностей.

Q_PROPERTY(int value READ value WRITE setValue)

Используйте макрос Q_PROPERTY() для объявления свойств для ActiveX-контроля.

Объявите стандартный конструктор, принимающий родительский объект, и функции, сигналы и слоты, как для любого подкласса QObject.

public:
    MyActiveX(QWidget *parent = 0)
    ...

    int value() const;

public slots:
    void setValue(int v);
    ...

signals:
    void valueChange(int v);
    ...

};

Фреймворк ActiveQt экспонирует свойства и публичные слоты как свойства и методы ActiveX, а сигналы – как события ActiveX, и преобразует между типами данных Qt и эквивалентными типами данных COM.

Типы данных

Типы данных Qt, которые поддерживаются для свойств:

Типы данных Qt, которые поддерживаются в качестве параметров в сигналах и слотах:

Также поддерживаются экспортированные перечисления и флаги (см. Q_ENUMS() и Q_FLAGS()). Типы параметров ввода также поддерживаются в качестве значений возврата.

Свойства и сигналы/слоты, имеющие параметры других типов данных, игнорируются фреймворком ActiveQt.

Под-объекты

Объекты COM могут иметь несколько под-объектов, которые могут представлять подэлемент объекта COM. Например, объект COM, представляющий приложение многодокументной электронной таблицы, может предоставлять один под-объект для каждой электронной таблицы.

Любой подкласс QObject может использоваться в качестве типа под-объекта в ActiveX, если он известен QAxFactory. Тогда этот тип может использоваться в свойствах или в качестве типа возвращаемого значения или параметра слота.

Уведомление о свойствах

Чтобы сделать свойства привязываемыми для клиента ActiveX, используйте множественное наследование от класса QAxBindable:

#include <QAxBindable>
#include <QWidget>

class MyActiveX : public QWidget, public QAxBindable
{
    Q_OBJECT

При реализации функций записи свойств используйте функции класса QAxBindable requestPropertyChange() и propertyChanged(), чтобы позволить клиентам ActiveX привязываться к свойствам управления.

Сервирование элементов управления

Чтобы сделать сервер COM доступным для системы COM, его необходимо зарегистрировать в системном реестре с использованием пяти уникальных идентификаторов. Эти идентификаторы предоставляются такими инструментами, как guidgen или uuidgen. Информация о регистрации позволяет COM локализовать двоичный файл, предоставляющий запрашиваемый ActiveX-элемент управления, передавать удалённые вызовы процедур в элемент управления и читать информацию о типах методов и свойств, предоставляемых элементом управления.

Чтобы создать объект COM при запросе клиентом, сервер должен экспортировать реализацию QAxFactory. Самый простой способ сделать это — использовать набор макросов:

QAXFACTORY_BEGIN("{ad90301a-849e-4e8b-9a91-0a6dc5f6461f}",
                 "{a8f21901-7ff7-4f6a-b939-789620c03d83}")
    QAXCLASS(MyWidget)
    QAXCLASS(MyWidget2)
    QAXTYPE(MySubType)
QAXFACTORY_END()

Это экспортирует MyWidget и MyWidget2 как объекты COM, которые могут быть созданы клиентами COM, и зарегистрирует MySubType как тип, который может использоваться в свойствах и параметрах MyWidget и MyWidget2.

Документация класса QAxFactory объясняет, как использовать этот макрос, а также как реализовать и использовать пользовательские фабрики.

Для серверов исполняемых файлов вне процесса вы можете реализовать функцию main() для создания объекта QApplication и входа в цикл обработки событий, как и в любом обычном приложении Qt. По умолчанию приложение будет запущено как стандартное приложение Qt, но если вы передадите -activex в командной строке, оно будет запущено как сервер ActiveX. Используйте QAxFactory::isServer() для создания и запуска стандартного интерфейса приложения или для предотвращения автономного выполнения:

#include <QApplication>
#include <QAxFactory>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    if (!QAxFactory::isServer()) {
        // create and show main window
    }
    return app.exec();
}

Однако это необязательно, так как ActiveQt предоставляет реализацию функции main по умолчанию. Реализация по умолчанию вызывает QAxFactory::startServer(), создаёт экземпляр QApplication и вызывает exec().

Для построения исполняемого файла сервера ActiveX запустите qmake для генерации файла makefile и используйте инструмент make вашего компилятора, как и для любого другого приложения Qt. Процесс создания также зарегистрирует элементы управления в системном реестре, вызвав полученный исполняемый файл с параметром командной строки -regserver.

Если сервер ActiveX является исполняемым файлом, поддерживаются следующие параметры командной строки:

Серверы в процессе могут быть зарегистрированы с помощью инструмента regsvr32, доступного на всех системах Windows.

Типичные проблемы во время компиляции

Перечисленные ошибки компилятора/линковщика основаны на ошибках, выдаваемых компилятором Microsoft Visual C++ 6.0.

"Нет перегруженной функции, принимающей 2 параметра"

Когда ошибка возникает в коде, использующем макрос QAXFACTORY_DEFAULT(), класс виджета не имел конструктора, который может быть использован фабрикой по умолчанию. Либо добавьте стандартный конструктор виджета, либо реализуйте пользовательскую фабрику, которая не требует его.

Когда ошибка возникает в коде, использующем макрос QAXFACTORY_EXPORT(), подкласс QAxFactory не имел подходящего конструктора. Предоставьте публичный конструктор класса, как

MyFactory(const QUuid &, const QUuid &);

для вашего класса фабрики.

"Синтаксическая ошибка: неверный суффикс числа"

Уникальные идентификаторы не были переданы в виде строк в макрос QAXFACTORY_EXPORT() или QAXFACTORY_DEFAULT().

"Неразрешённая внешняя переменная _ucm_instantiate"

Сервер не экспортирует реализацию QAxFactory. Используйте макрос QAXFACTORY_EXPORT() в одном из файлов реализации проекта для создания и экспорта фабрики или используйте макрос QAXFACTORY_DEFAULT() для использования фабрики по умолчанию.

"_ucm_initialize уже определено в ..."

Сервер экспортирует более одной реализации QAxFactory или экспортирует одну реализацию дважды. Если вы используете фабрику по умолчанию, макрос QAXFACTORY_DEFAULT() должен использоваться только один раз в проекте. Используйте пользовательскую реализацию QAxFactory и макрос QAXFACTORY_EXPORT(), если сервер предоставляет несколько ActiveX-элементов управления.

Распространение двоичных файлов QAxServer

Серверы ActiveX, написанные с помощью Qt, могут использовать Qt либо как общую библиотеку, либо связывать Qt статически в двоичный файл. Оба способа приведут к довольно большим пакетам (либо сам двоичный файл сервера станет большим, либо вам придётся распространять DLL Qt).

Установка автономных серверов

Если ваш сервер ActiveX также может работать как автономное приложение, запустите исполняемый файл сервера с параметром командной строки -regserver после установки исполняемого файла на целевую систему. После этого элементы управления, предоставляемые сервером, станут доступными для клиентов ActiveX.

Установка серверов в процессе

Если ваш сервер ActiveX входит в пакет установки, используйте инструмент regsvr32 от Microsoft для регистрации элементов управления на целевой системе. Если этот инструмент отсутствует, загрузите DLL в свой процесс установщика, найдите символ DllRegisterServer и вызовите функцию:

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

Распространение серверов через Интернет

Если вы хотите использовать элементы управления на своём сервере в веб-страницах, вам нужно сделать сервер доступным для браузера, используемого для просмотра вашей страницы, и указать расположение пакета сервера на вашей странице.

Для указания расположения сервера используйте атрибут CODEBASE в теге OBJECT вашей веб-страницы. Значение может указывать на сам файл сервера, на файл INF, перечисляющий другие файлы, необходимые для сервера (например, DLL Qt), или на сжатый архив CAB.

Файлы INF и CAB документированы практически в каждой книге по программированию ActiveX и COM, а также в библиотеке MSDN и различных других онлайн-ресурсах. Примеры включают файлы INF, которые могут быть использованы для создания архивов CAB:

[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 от Microsoft может легко генерировать архивы CAB:

cabarc N simpleax.cab simpleax.exe simple.inf

Файлы INF предполагают статическую сборку Qt, поэтому зависимости от других DLL не перечислены в файлах INF. Для распространения сервера ActiveX, зависящего от DLL, необходимо добавить зависимости и предоставить файлы библиотеки в архив.

Использование элементов управления

Для использования элементов управления ActiveX, например, для их встраивания в веб-страницу, используйте тег <object> HTML.

<object ID="MyActiveX1" CLASSID="CLSID:ad90301a-849e-4e8b-9a91-0a6dc5f6461f">
   ...
<\object>

Для инициализации свойств элемента управления используйте

<object ID=...>
    <param name="name" value="value">
<\object>

Если веб-браузер поддерживает скрипты, используйте JavaScript, VBScript и формы для управления элементом управления. Примеры ActiveQt включают демонстрационные HTML-страницы для примеров элементов управления.

Поддерживаемые и неподдерживаемые клиенты ActiveX

Следующая информация в значительной степени основана на наших собственных экспериментах с элементами управления ActiveX и клиентскими приложениями и ни в коем случае не является исчерпывающей.

Поддерживаемые клиенты

Эти стандартные приложения работают с элементами управления ActiveX, разработанными с помощью ActiveQt. Обратите внимание, что некоторые клиенты поддерживают только элементы управления в процессе.

• Internet Explorer
• Контейнер для тестирования элементов управления Microsoft ActiveX
• Microsoft Visual Studio 6.0
• Microsoft Visual Studio .NET/2003
• Microsoft Visual Basic 6.0
• Контейнеры на основе MFC и ATL
• Sybase PowerBuilder
• Контейнеры на основе ActiveQt

Приложения Microsoft Office поддерживаются, но вам необходимо зарегистрировать элементы управления как объекты «Вставляемые». Переопределите QAxFactory::registerClass, чтобы добавить этот атрибут к классу COM, или установите информацию о классе «Вставляемый» для вашего класса в «да» с помощью макроса Q_CLASSINFO.

Неподдерживаемые клиенты

Мы не смогли заставить объекты COM на основе ActiveQt работать со следующими клиентскими приложениями.

• Borland C++ Builder (версии 5 и 6)
• Borland Delphi

Типичные ошибки во время выполнения

Сервер не отвечает

Если система не может запустить сервер (проверьте с помощью диспетчера задач, запущен ли сервер), убедитесь, что ни одна DLL, от которой зависит сервер, не отсутствует в системном пути (например, DLL Qt!). Используйте средство просмотра зависимостей для просмотра всех зависимостей двоичного файла сервера.

Если сервер работает (например, диспетчер задач отображает процесс), см. следующий раздел для получения информации об отладке вашего сервера.

Объект не может быть создан

Если сервер был успешно построен и зарегистрирован во время процесса сборки, но объект не может быть инициализирован, например, приложением OLE/COM Object Viewer, убедитесь, что ни одна DLL, от которой зависит сервер, не отсутствует в системном пути (например, DLL Qt). Используйте средство просмотра зависимостей для просмотра всех зависимостей двоичного файла сервера.

Если сервер работает, см. следующий раздел для получения информации об отладке вашего сервера.

Отладка ошибок во время выполнения

Для отладки сервера в процессе в Visual Studio установите проект сервера как активный проект и укажите в настройках проекта клиентское «приложение для сеанса отладки» (например, используйте контейнер для тестирования ActiveX). Вы можете установить точки останова в своем коде и также переходить в код ActiveQt и Qt, если вы установили отладочную версию.

Для отладки исполняемого сервера запустите приложение в отладчике и начните с параметра командной строки -activex. Затем запустите клиент и создайте экземпляр вашего элемента управления ActiveX. COM будет использовать существующий процесс для следующего клиента, пытающегося создать элемент управления ActiveX.

Информация о классе и настройка

Для предоставления атрибутов для каждого класса COM используйте макрос Q_CLASSINFO, который является частью системы метаобъектов Qt.

Обратите внимание, что и ключи, и значения чувствительны к регистру.

Следующее объявление версии 2.0 класса, который отображает только свой собственный API и доступен в диалоговом окне «Вставка объектов» приложений Microsoft Office.

class MyActiveX : public QWidget
{
    Q_OBJECT
    Q_CLASSINFO("Version", "2.0")
    Q_CLASSINFO("ClassID", "{7a4cffd8-cbcd-4ae9-ae7e-343e1e5710df}")
    Q_CLASSINFO("InterfaceID", "{6fb035bf-8019-48d8-be51-ef05427d8994}")
    Q_CLASSINFO("EventsID", "{c42fffdf-6557-47c9-817a-2da2228bc29c}")
    Q_CLASSINFO("Insertable", "yes")
    Q_CLASSINFO("ToSuperClass", "MyActiveX")
    Q_PROPERTY(...)

public:
    MyActiveX(QWidget *parent = 0);

    ...
};

Разработка лицензионных компонентов

Если вы разрабатываете компоненты, вам может потребоваться управлять тем, кто может создавать экземпляры этих компонентов. Поскольку двоичный файл сервера может быть отправлен и зарегистрирован на любой клиентской машине, любой может использовать эти компоненты в своем собственном программном обеспечении.

Лицензирование компонентов может осуществляться с помощью различных методов, например, код, создающий элемент управления, может предоставить ключ лицензии, или машина, на которой должен работать элемент управления, должна быть лицензирована.

Для обозначения класса Qt как лицензионного укажите «LicenseKey» с помощью макроса Q_CLASSINFO().

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

Ключ необходим для создания экземпляра MyLicensedControl на машине, которая сама не лицензирована. Теперь лицензированный разработчик может перераспределить двоичный файл сервера вместе со своим приложением, которое создает элемент управления, используя значение «LicenseKey», в то время как пользователи приложения не могут создать элемент управления без ключа лицензии.

Если одного ключа лицензии для элемента управления недостаточно (например, вы хотите, чтобы разные разработчики получали разные ключи лицензии), вы можете указать пустой ключ, чтобы указать, что элемент управления требует лицензии, и переопределить QAxFactory::validateLicenseKey(), чтобы проверить, существует ли лицензия на системе (например, через файл лицензии).

Дополнительные интерфейсы

Серверы ActiveX, предоставляемые ActiveQt, поддерживают минимальный набор COM-интерфейсов для реализации спецификаций OLE. Когда класс ActiveX наследуется от класса QAxBindable, он также может реализовать дополнительные COM-интерфейсы.

Создайте новый подкласс QAxAggregated и используйте множественное наследование для наследования дополнительных классов COM-интерфейсов.

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

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

    // IUnknown
    QAXAGG_IUNKNOWN

    // ISomeCOMInterface
    ...
}

Переопределите функцию QAxAggregated::queryInterface() для поддержки дополнительных COM-интерфейсов.

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;
}

Поскольку ISomeCOMInterface является подклассом IUnknown, вам необходимо реализовать функции QueryInterface(), AddRef() и Release(). Используйте макрос QAXAGG_IUNKNOWN в определении вашего класса для этого. Если вы реализуете функции IUnknown вручную, передавайте вызовы указателю на интерфейс, возвращаемому функцией QAxAggregated::controllingUnknown(), например:

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

Не поддерживайте сам интерфейс IUnknown в вашей реализации queryInterface().

Реализуйте методы COM-интерфейсов и используйте QAxAggregated::object(), если вам нужно выполнить вызовы подклассу QObject, реализующему элемент управления.

В вашем подклассе QAxBindable реализуйте QAxBindable::createAggregate() для возврата нового объекта подкласса QAxAggregated.

class MyActiveX : public QWidget, public QAxBindable
{
    Q_OBJECT

public:
    MyActiveX(QWidget *parent);

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

См. также Фреймворк ActiveQt.