1С:Предприятие 7.5, 7.7, 8.0 Технология создания внешних компонент

• Обновлено: 14.08.2008

  Введение
  • Версии компонент
  • Что Вы должны знать
  • Структура руководства
• Глава 1. Внешние компоненты
  • Средства встроенного языка 1С:Предприятия, предназначенные для работы с внешними компонентами
  • Разработка внешней компоненты
• Глава 2. Примеры внешних компонент
  • Структура каталогов
  • Описание конфигураций
  • Описание компонент
  • Microsoft Visual C++
  • Microsoft Visual Basic 5.0 и 6.0 (Enterprise Edition)
  • Visual Basic .NET
  • Borland Delphi
  • Шаблоны
  • Рекомендации по построению компоненты
• Глава 3. Введение в COM
  • Интерфейсы в COM
  • Объекты COM
  • OLE Automation

Введение

Система программ 1С:Предприятие предназначена для решения самых разнообразных задач автоматизации деятельности организаций. Она обладает мощными средствами конфигурирования, которые позволяют штатными средствами настроить систему на особенности обработки информации в конкретной организации. В тоже время, 1С:Предприятие является открытой системой. Для связи с другими программами могут использоваться встроенные средства загрузки-выгрузки информации в текстовом формате, в форматах DBF и XML, система поддерживает стандарт интеграции программ OLE Automation. Однако для специальных задач интеграции может потребоваться более тесное взаимодействие между 1С:Предприятием и другими программами.

Для решения таких задач разработана "Технология создания внешних компонент". Данная технология позволяет создавать программы, которые будут динамически подключаться и тесно взаимодействовать с системой 1С:Предприятие, расширяя ее возможности. Внешние компоненты позволяют решать широкий спектр специальных задач, в частности, задачи, связанные с использованием различного торгового оборудования совместно с 1С:Предприятием.

В комплект поставки входит данное руководство и набор примеров реализации внешних компонент с помощью различных программных средств.

В данном руководстве описана технология создания внешних компонент версии 1.0 и 2.0.

Версии компонент

Технология создания внешних компонент версии 2.0 является развитием версии 1.0 и предназначена для использования с 1С:Предприятием 7.7 и 8. Все возможности, описанные в данной книге, относятся к версиям 1.0 и 2.0, если нет явного указания, что данная возможность относится исключительно к версии 2.0. Ниже приводится информация о совместимости различных версий внешних компонент и 1С:Предприятия между собой.

Версия компоненты определяется по возвращаемому методом GetInfo значению.

Компоненты версии 1.0 полностью совместимы с 1С:Предприятием 7.5, 7.7 и 8. При работе компоненты с 1С:Предприятием 7.7 и 8 создание нескольких однотипных объектов невозможно.

Компоненты версии 2.0 полностью совместимы с 1С:Предприятием 7.7 и 8. Эти компоненты могут работать с 1С:Предприятием 7.5 при условии, что они используют только возможности версии 1.0. При работе компоненты с 1С:Предприятием 7.5 создание нескольких однотипных объектов невозможно.

1С:Предприятие 7.5 может использовать внешние компоненты версии 1.0. Компоненты версии 2.0 могут быть использованы при условии, что они не задействуют возможностей версии 2.0.

1С:Предприятие 7.7 и 8 может использовать внешние компоненты версий 1.0 и 2.0. При использовании компоненты версии 1.0 создание нескольких однотипных объектов невозможно.

В 1С:Предприятии 8 возможности версии 2.0 по созданию окон сохранены в сокращенном виде для совместимости с существующими компонентами. Для отображения нестандартной информации в окнах 1С:Предприятия 8 рекомендуется использовать формы с элементами управления ActiveX или же Активные документы.

Что Вы должны знать

Настоящая методика предназначена для специалистов, выполняющих конфигурирование 1С:Предприятия и решающих задачи, выходящие за возможности встроенных в 1С:Предприятие механизмов.

Для работы с методикой необходимо знание основ COM (ActiveX). Желательно также знакомство с используемыми средами программирования.

Замечание: Для работы внешних компонент, поставляемых в этом комплекте, необходимы дополнительные библиотеки, входящие в поставку используемых сред разработки.

Структура руководства

В первой части настоящей методики описывается стандарт, которому должна следовать внешняя компонента при работе с 1С:Предприятием. В этой части также приводится описание интерфейсов, предоставляемых 1С:Предприятием внешней компоненте.

Во второй части разбираются примеры построения внешних компонент в различных средах разработки. Используются следующие программные продукты: Visual C++ 5.0 - 7.0, Visual Basic 5.0 и 6.0 (Enterprise Edition), Visual Basic .NET, Borland Delphi 3.0 –5.0. Для каждой среды разобраны структура и код примера и сложные детали реализации.

Третья часть описывает основы COM и может быть использована как краткая справка по COM.

Глава 1. Внешние компоненты

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

Возможности внешней компоненты:

• расширение встроенного языка 1С:Предприятия (добавление новых агрегатных объектов);
• добавление страницы свойств в параметры 1С:Предприятия;
• сохранение параметров внешней компоненты через механизмы сохранения параметров 1С:Предприятия;
• создание дополнительных окон в окне 1С:Предприятия (версия 2.0, только для 1С:Предприятия 7.7);
• доступ к функциям 1С:Предприятия через OLE Automation (версия 2.0);
• вызов процедуры обработки событий, контролируемых внешней компонентой;
• доступ к строке состояния 1С:Предприятия.

Внешние компоненты используются в 1С:Предприятии для расширения его возможностей при выполнении различных задач. В частности, в число таких задач входит вызов функции из библиотеки (DLL), использование различного торгового оборудования, нестандартное отображение данных и т.д. Все внешние компоненты следуют единому стандарту, поэтому при работе можно использовать как уже существующие компоненты, так и разрабатывать новые. В данную поставку входят шаблоны и примеры для различных сред разработки, которые позволяют упростить разработку новых компонент.

Средства встроенного языка 1С:Предприятия, предназначенные для работы с внешними компонентами

ЗагрузитьВнешнююКомпоненту (LoadAddIn)

Загружает внешнюю компоненту, создает соответствующие COM-объекты и подключает их к 1С:Предприятию.

Синтаксис:

Копировать в буфер обмена

ЗагрузитьВнешнююКомпоненту(<ИмяФайлаКомпоненты>)

Параметры:

<ИмяФайлаКомпоненты>      Обязательный

Тип: строка. Имя файла внешней компоненты. <ИмяФайлаКомпоненты> должно иметь вид "Имя.Расширение" и не должно содержать путь. Файл компоненты должен находиться в каталоге исполняемых файлов 1С:Предприятия.

Возвращаемое значение:

1С:Предприятие 7.5, 7.7

Тип: число. 0 - при загрузке компоненты произошла ошибка. 1 - компонента успешно загружена. При возникновении ошибок при загрузке 1С:Предприятие выдает информацию об ошибке в окно сообщений.

1С:Предприятие 8

отсутствует. В случае ошибки возникает исключительная ситуация.

Описание:

Внешние компоненты загружаются функцией встроенного языка ЗагрузитьВнешнююКомпоненту. Файл внешней компоненты должен быть динамически загружаемой библиотекой (например, DLL или OCX), то есть работать как InProc сервер. При загрузке внешней компоненты 1С:Предприятие вызывает функцию DllRegisterServer, если она экспортирована из внешней компоненты. Это позволяет просто переносить компоненты между компьютерами без дополнительной регистрации их как COM-серверов. О создании COM-объекта внешней компоненты при загрузке - см. Разработка внешней компоненты.

ПодключитьВнешнююКомпоненту(AttachAddIn)

Создает COM-объекты внешней компоненты и подключает их к 1С:Предприятию.

Синтаксис:

Копировать в буфер обмена

ПодключитьВнешнююКомпоненту(<ИмяОбъектаКомпоненты>)

Параметры:

<ИмяОбъектаКомпоненты>      Обязательный

ProgID (Programmatic Identifier) объекта внешней компоненты. <ИмяОбъектаКомпоненты> должно соответствовать информации, находящейся в регистрационной базе данных системы (Registry).

Возвращаемое значение:

1С:Предприятие 7.5, 7.7

Тип: число. 0 - при загрузке компоненты произошла ошибка. 1 - компонента успешно загружена. При возникновении ошибок при подключении 1С:Предприятие выдает информацию об ошибке в окно сообщений.

1С:Предприятие 8

Отсутствует. В случае ошибки возникает исключительная ситуация.

Описание:

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

ОбработкаВнешнегоСобытия (ExternEventProcessing)

Предопределенная процедура встроенного языка. Вызывается при возникновении сообщения от внешней компоненты.

Синтаксис:

Копировать в буфер обмена

ОбработкаВнешнегоСобытия(<Источник>, <Событие>, <Данные>)

Параметры:

<Источник> Тип:строка. Наименование источника сообщения.

<Событие> Тип:строка. Наименование сообщения.

<Данные> Тип:строка. Параметры сообщения.

Описание:

Процедура ОбработкаВнешнегоСобытия — предопределенная процедура обработки сообщений от внешних компонент.

1С:Предприятие 7.5, 7.7

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

1С:Предприятие 8

Процедура может быть описана в модуле приложения системы 1С:Предприятие. При получении сообщения будут вызваны обработчики внешнего события, определенные в модулях всех открытых на этот момент форм. После этого будет вызвана процедура ОбработкаВнешнегоСобытия, определенная в модуле приложения.

Вызов этой процедуры синхронизирован с обработкой сообщений системой 1С:Предприятие и происходит только при отсутствии других выполняемых системой операций (проведении документов, построении отчетов и т.д.).

ВнешнееСобытие (ExternalEvent)

Процедура обработки внешнего события во встроенном языке. Вызывается при возникновении сообщения от внешней компоненты. В 1С:Предприятии 7.5, 7.7 отсутствует – в качестве этого обработчика используется предопределенная процедура ОбработкаВнешнегоСобытия.

Синтаксис:

Копировать в буфер обмена

ВнешнееСобытие (<Источник>, <Событие>, <Данные>)

Параметры:

<Источник> Тип:строка. Наименование источника сообщения.

<Событие> Тип:строка. Наименование сообщения.

<Данные> Тип:строка. Параметры сообщения.

Описание:

Процедура может быть описана в модуле любой формы системы 1С:Предприятие. При получении сообщения будет вызвана процедура ВнешнееСобытие, определенная в модулях открытых на этот момент форм. После обработки внешнего события в формах будет вызвана предопределенная процедура ОбработкаВнешнегоСобытия, определенная в модуле приложения. Процедура ОбработкаВнешнегоСобытия в модуле приложения всегда вызывается последней. Для отличия активной в данный момент формы можно использовать функцию ВводДоступен.

Вызов этой процедуры синхронизирован с обработкой сообщений системой 1С:Предприятие и происходит только при отсутствии других выполняемых системой операций (проведении документов, построении отчетов и т.д.).

Разработка внешней компоненты

Создание COM—объекта внешней компоненты

При загрузке внешней компоненты функцией ЗагрузитьВнешнююКомпоненту 1С:Предприятие определяет ProgID COM—объекта компоненты следующим образом:

• ProgID имеет вид <Vendor>.<Component>;
• в качестве первой части (<Vendor>) используется строка "AddIn";
• в качестве второй части (<Component>) используется строка с ID 100 из таблицы строк компоненты. Строка может иметь вид "Name1|Name2|...|NameN", и в этом случае будут созданы все объекты с ProgID вида "AddIn.NameX". Если такая строка отсутствует, то используется имя файла внешней компоненты без расширения.

При использовании функции ПодключитьВнешнююКомпоненту ProgID COM-объекта компоненты передается в качестве параметра функции и также может представляться строкой вида ProgID1| ProgID2|...|ProgIDX.

Инициализация и выгрузка компоненты

Для инициализации и выгрузки компоненты используется интерфейс IInitDone. Этот интерфейс наследован от IUnknown и предназначен для инициализации объекта и завершения работы с объектом.

Init

Синтаксис:

Копировать в буфер обмена

HRESULT Init(IDispatch *pBackConnection)

Параметры:

<pBackConnection> Тип: IDispatch. Указатель на интерфейс 1С:Предприятия.

Возвращаемое значение:

• E_FAIL - при инициализации произошла ошибка
• S_OK - инициализация прошла успешно

Описание:

При загрузке 1С:Предприятие инициализирует объект компоненты, вызывая метод Init и передавая указатель на IDispatch. Объект может сохранить этот указатель для дальнейшего использования. Все остальные интерфейсы 1С:Предприятия объект может получить, вызвав метод QueryInterface переданного ему интерфейса IDispatch. Объект должен возвратить S_OK, если инициализация прошла успешно, и E_FAIL при возникновении ошибки. Данный метод может использовать интерфейс IErrorLog для вывода информации об ошибках. При этом инициализация считается неудачной, если одна из переданных структур EXCEPINFO имеет поле scode, не равное S_OK. Все переданные в IErrorLog данные обрабатываются при возврате из данного метода. В момент вызова этого метода свойство AppDispatch не определено.

Done

Синтаксис:

Копировать в буфер обмена

HRESULT Done(void)

Возвращаемое значение:

• S_OK - объект завершил работу

Описание:

1С:Предприятие вызывает этот метод при завершении работы с объектом компоненты. Объект должен возвратить S_OK. Этот метод вызывается независимо от результата инициализации объекта (метод Init).

GetInfo

Синтаксис:

Копировать в буфер обмена

HRESULT GetInfo(SAFEARRAY **pInfo)

Параметры:

<PInfo> Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT. Память для массива выделяется 1С:Предприятием.

Возвращаемое значение:

• S_OK - информация о компоненте возвращена

Описание:

1С:Предприятие вызывает этот метод для получения информации о компоненте. В текущей версии 2.0 компонентной технологии в элемент с индексом 0 необходимо записать версию поддерживаемой компонентной технологии в формате V_I4 — целого числа, при этом старший номер версии записывается в тысячные разряды, младший номер версии — в единицы. Например: версия 3.56 — число 3560. В настоящее время все объекты внешних компонент могут поддерживать версию 1.0 (соответствует числу 1000) или 2.0 (соответствует 2000). Память для pInfo выделяется 1С:Предприятием. Метод должен возвращать S_OK.

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

Страница свойств

Для добавления страницы свойств объекта компоненты в диалог настройки параметров 1С:Предприятия используются интерфейсы IPropertyPage или ISpecifyPropertyPages (объект может реализовать любой из этих интерфейсов). Каждый объект может добавить одну страницу свойств. Странице свойств при инициализации передается указатель на интерфейс IUnknown соответствующего объекта внешней компоненты. Интерфейсы IPropertyPage, ISpecifyPropertyPages являются стандартными для COM, поэтому их описание Вы сможете найти в документации на COM.

Расширение встроенного языка

Для расширения встроенного языка компонента должна реализовать интерфейс ILanguageExtender. Этот интерфейс унаследован от IUnknown и предназначен для расширения встроенного языка 1С:Предприятия. Для использования этого расширения необходимо вызвать функцию СоздатьОбъект (Новый в 1С:Предприятии 8), передав ей строку вида "AddIn.<ИмяРасширения>", где <ИмяРасширения> возвращается методом этого интерфейса Затем можно использовать созданный объект, вызывая его методы и свойства.

Версия 2.0 позволяет создавать несколько объектов одного типа "AddIn.<ИмяРасширения>", однако компонента должна явно указать поддержку версии 2.0 в методе GetInfo. В противном случае допускается создание только одного объекта.

RegisterExtensionAs

Синтаксис:

Копировать в буфер обмена

HRESULT RegisterExtensionAs(BSTR *pExtensionName)

Параметры:

<pExtensionName> Тип: BSTR*. Наименование расширения встроенного языка 1С:Предприятия.

Возвращаемое значение:

• S_OK

Описание:

В переменную pExtensionName помещается наименование расширения. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. 1С:Предприятие освобождает эту память вызовом SysFreeString).

Первое свойство имеет порядковый номер 0.

GetNProps

Синтаксис:

Копировать в буфер обмена

HRESULT GetNProps(long *plProps)

Параметры:

<plProps> Тип: long*. Указатель на переменную, содержащую при возврате количество свойств расширения.

Возвращаемое значение:

• S_OK

Описание:

Возвращает количество свойств данного расширения, 0 – при отсутствии свойств. Память для переменной plProps выделяется 1С:Предприятием.

FindProp

Синтаксис:

Копировать в буфер обмена

HRESULT FindProp(BSTR pszPropName,long*plPropNum)

Параметры:

<pszPropName> Тип: BSTR. Наименование свойства.

<plPropNum> Тип: long*. Указатель на переменную, содержащую при возврате порядковый номер свойства.

Возвращаемое значение:

• S_OK - операция завершена успешно
• S_FALSE - свойство с именем pszPropName в данном расширении отсутствует

Описание:

Возвращает порядковый номер свойства с именем pszPropName; -1, если свойство не найдено. Память для переменной plPropNum выделяется 1С:Предприятием.

GetPropName

Синтаксис:

Копировать в буфер обмена

HRESULT GetPropName(long lPropNum,long lAliasNum,BSTR *pPropName)

Параметры:

<lPropNum> Тип: long. Порядковый номер свойства.

<lAliasNum> Тип: long. Язык наименования:

• 0 — английское наименование;
• 1 — локальное наименование.

<pPropName> Тип: BSTR*. Указатель на строку, содержащую при возврате наименование свойства.

Возвращаемое значение:

• S_OK - операция завершена успешно
• S_FALSE - свойство с номером lPropNum в данном расширении отсутствует

Описание:

В переменную pPropName помещается имя свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, в pPropName помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. 1С:Предприятие освобождает эту память вызовом SysFreeString).

GetPropVal

Синтаксис:

Копировать в буфер обмена

HRESULT GetPropVal(long lPropNum,VARIANT *pvPropVal)

Параметры:

<lPropNum> Тип: long. Порядковый номер свойства.

<pvPropVal> Тип: VARIANT*. Указатель на структуру VARIANT, содержащую при возврате значение свойства.

Возвращаемое значение:

• S_OK - операция завершена успешно
• S_FALSE - свойство с номером lPropNum в данном расширении отсутствует или недоступно для чтения.

Описание:

В переменную pvPropVal помещается значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует или недоступно для чтения, должен иметь тип VT_EMPTY.

SetPropVal

Синтаксис:

Копировать в буфер обмена

HRESULT SetPropVal(long lPropNum, VARIANT *pvPropVal)

Параметры:

<lPropNum> Тип: long. Порядковый номер свойства.

<pvPropVal> Тип: VARIANT*. Структура VARIANT, содержащая новое значение свойства.

Возвращаемое значение:

• S_OK - операция завершена успешно
• S_FALSE - свойство с номером lPropNum в данном расширении отсутствует или недоступно для записи.

Описание:

Переменная pvPropVal содержит значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, недоступно для чтения или тип переданного pvPropVal не приводится к необходимому, метод должен возвратить S_FALSE.

IsPropReadable

Синтаксис:

Копировать в буфер обмена

HRESULT IsPropReadable(long lPropNum, BOOL *pboolPropReadable)

Параметры:

lPropNum Тип: long. Порядковый номер свойства.

pboolPropReadable Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг возможности чтения свойства.

Возвращаемое значение:

• S_OK - операция завершена успешно.
• S_FALSE - свойство с номером lPropNum в данном расширении отсутствует.

Описание:

В переменную pboolPropReadable помещается флаг возможности чтения свойства с порядковым номером lPropNum: FALSE(0) — свойство недоступно для чтения, TRUE(1) — свойство допускает чтение. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.

IsPropWritable

Синтаксис:

Копировать в буфер обмена

HRESULT IsPropWritable(long lPropNum, BOOL *pboolPropWritable)

Параметры:

<lPropNum> Тип: long. Порядковый номер свойства.

<pboolPropWritable> Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг возможности записи свойства.

Возвращаемое значение:

• S_OK - операция завершена успешно.
• S_FALSE - свойство с номером в данном расширении отсутствует.

Описание:

В переменную pboolPropWritable помещается флаг возможности записи свойства с порядковым номером lPropNum: FALSE(0) — свойство недоступно для записи, TRUE(1) — свойство допускает запись. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.

Первый метод имеет порядковый номер 0. Первый параметр метода имеет порядковый номер 0.

GetNMethods

Синтаксис:

Копировать в буфер обмена

HRESULT GetNMethods(long *plMethods)

Параметры:

<plMethods> Тип: long*. Указатель на переменную, содержащую при возврате количество методов расширения языка.

Возвращаемое значение:

• S_OK

Описание:

В переменную plMethods помещается количество методов данного расширения, 0 - при отсутствии методов.

FindMethod

Синтаксис:

Копировать в буфер обмена

HRESULT FindMethod(BSTR bstrMethodName,long *plMethNum)

Параметры:

<bstrMethodName> Тип: BSTR. Имя метода

<plMethNum> Тип: long*. Указатель на переменную, содержащую при возврате порядковый номер метода с именем methodName.

Возвращаемое значение:

• S_OK

Описание:

В переменную plMethNum помещается порядковый номер метода с именем bstrMethodName; -1 — при отсутствии метода.

GetMethodName

Синтаксис:

Копировать в буфер обмена

HRESULT GetMethodName(long lMethodNum, long lAliasNum, BSTR *pbstrMethName)

Параметры:

<lMethodNum> Тип: long. Порядковый номер метода.

<lAliasNum> Тип: long. Язык имени метода:

• 0 — английское наименование;
• 1 — локальное наименование.

<pbstrMethName> Тип: BSTR*. Указатель на строку, содержащую при возврате имя метода.

Возвращаемое значение:

• S_OK - операция завершена успешно
• S_FALSE - метод с номером в данном расширении отсутствует

Описание:

В переменную помещается имя свойства с порядковым номером; если свойство с таким номером отсутствует, в помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. 1С:Предприятие освобождает эту память вызовом SysFreeString).

GetNParams

Синтаксис:

Копировать в буфер обмена

HRESULT GetNParams(long lMethodNum, long *plMethParams)

Параметры:

<lMethodNum> Тип: long. Порядковый номер метода.

<plMethParams> Тип: long*. Указатель на переменную, содержащую при возврате количество параметров метода.

Возвращаемое значение:

• S_OK - операция завершена успешно
• S_FALSE - метод с номером в данном расширении отсутствует

Описание:

В переменную plMethParams помещается количество параметров метода с порядковым номером lMethodNum; если свойство с таким номером отсутствует или не имеет параметров, в помещается 0. Память для переменной выделяется 1С:Предприятием.

GetParamDefValue

Синтаксис:

Копировать в буфер обмена

HRESULT GetParamDefValue(long lMethodNum, long lParamNum, VARIANT *pvParamDefVal)

Параметры:

<lMethodNum> Тип: long. Порядковый номер метода.

<lParamNum> Тип: long. Порядковый номер параметра.

<pvParamDefVal> Тип: VARIANT*. Указатель на структуру VARIANT, содержащую при возврате значение параметра по умолчанию.

Возвращаемое значение:

• S_OK - операция завершена успешно (вне зависимости от наличия у параметра значения по умолчанию)
• S_FALSE - метод или параметр метода отсутствует

Описание:

В переменную pvParamDefVal помещается значение по умолчанию параметра lParamNum метода с порядковым номером lMethodNum. В pvParamDefVal помещается тип VT_EMPTY, если метод с таким номером отсутствует, не имеет параметра с номером или параметр не имеет значения по умолчанию. Память для переменной выделяется 1С:Предприятием.

HasRetVal

Синтаксис:

Копировать в буфер обмена

HRESULT HasRetVal(long lMethodNum,BOOL *pboolHasRetVal)

Параметры:

<lMethodNum> Тип: long. Порядковый номер метода.

<pboolHasRetVal> Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг наличия возвращаемого значения.

Возвращаемое значение:

• S_OK - операция завершена успешно
• S_FALSE - метод отсутствует

Описание:

В переменную pboolHasRetVal помещается флаг наличия возвращаемого значения у метода с порядковым номером lMethodNum: TRUE для методов с возвращаемым значением и FALSE в противном случае. Память для переменной выделяется 1С:Предприятием.

CallAsProc

Синтаксис:

Копировать в буфер обмена

HRESULT CallAsProc(long lMethodNum, SAFEARRAY **pVars)

Параметры:

<lMethodNum> Тип: long. Порядковый номер метода.

<pVars> Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.

Возвращаемое значение:

• S_OK - соответствующий метод вызван, ошибок не произошло.
• E_FAIL - соответствующий метод вызван, произошла ошибка времени исполнения (runtime error). Исполнение модуля прекращается.
• S_FALSE – отсутствует метод, соответствующий переданному lMethodNum.

Описание:

Выполняется метод с порядковым номером lMethodNum. Если метод возвращает E_FAIL, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров выделяется 1С:Предприятием.

CallAsFunc

Синтаксис:

Копировать в буфер обмена

HRESULT CallAsFunc(long lMethodNum, VARIANT *pRetValue, SAFEARRAY **pVars)

Параметры:

<lMethodNum> Тип: long. Порядковый номер метода.

<pRetValue> Тип: VARIANT*. Указатель на структуру VARIANT, при возврате содержащую возвращаемое значение.

<pVars> Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.

Возвращаемое значение:

• S_OK - соответствующий метод вызван, ошибок не произошло.
• E_FAIL - соответствующий метод вызван, произошла ошибка времени исполнения (runtime error). Исполнение модуля прекращается.
• S_FALSE – отсутствует метод, соответствующий переданному lMethodNum.

Описание:

Выполняется метод с порядковым номером lMethodNum. Если метод возвращает E_FAIL, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров и возвращаемого значения выделяется 1С:Предприятием.

Использование типа COM VARIANT при обмене данными

Вызов функции компоненты

Соответствие между типами 1С:Предприятия и COM:

• неопределенное значение соответствует VT_EMPTY;
• целочисленное значение соответствует VT_I4 и помещается в lVal;
• дробное значение соответствует VT_R8 и помещается в dblVal;

Следует учесть, что внутреннее представление может иметь точность, превосходящую точность типа double (около 15 цифр после запятой), поэтому при конвертации может происходить потеря точности.

• значение даты соответствует VT_DATE и помещается в date;
• строковое значение соответствует VT_BSTR и помещается в bstrVal;
• объекты соответствуют VT_DISPATCH и помещаются в pdispVal. При использовании объектов 1С:Предприятия в компоненте необходимо определить DISPIDы методов объекта (вызвав GetIDsOfNames) и затем вызвать Invoke;

При конвертации COM-объекта в IDispatch проверяются ситуации взаимного вызова "1С:Предприятие->Компонента->1С:Предприятие" и "Компонента->1С:Предприятие->Компонента" и все необходимые операции проводятся корректно.

Платформа 1С:Предприятие работает со строками в формате Unicode. Это следует учитывать при разработке компонент, взаимодействующих с драйверами, которые используют ASCII коды.

Возвращение значений из компоненты

Соответствие между типами 1С:Предприятия и COM:

• VT_EMPTY соответствует неопределенному значению. При передаче в качестве параметра метода подставляется значение параметра по умолчанию;
• значения типа VT_I2, VT_I4, VT_BOOL, VT_ERROR, VT_UI1 соответствуют целочисленному значению и находятся в lVal;
• значения типа VT_R4, VT_R8, VT_CY соответствуют дробному значению и находятся в dblVal;
• значение типа VT_DATE соответствует значению даты и находится в date;
• значение типа VT_BSTR соответствует строковому значению и находится в bstrVal;
• значение типа VT_ARRAY соответствует массиву и находится в parray (только для 1С:Предприятия 8);
• значение типа VT_DISPATCH соответствует значению объекта и находится в pdispVal.

Типы VT_DECIMAL, VT_VARIANT и VT_UNKNOWN не поддерживаются.

При конвертации IDispatch в COM-объект проверяются ситуации взаимного вызова "1С:Предприятие->Компонента->1С:Предприятие" и "Компонента->1С:Предприятие->Компонента" и все необходимые операции проводятся корректно.

Вызов метода объекта 1С:Предприятия из компоненты

Для вызова метода объекта необходимо вызвать метод Invoke полученного ранее интерфейса IDispatch, передав ему все необходимые параметры, в том числе номер (DISPID) вызываемого метода объекта. Этот номер можно получить из метода GetIDsOfNames интерфейса IDispatch, передав ему название метода объекта.

Соответствие между параметрами метода объекта и массивом структур VARIANT прямое: первому параметру соответствует структура с индексом 0, второму параметру - структура с индексом 1 и т.д. При передаче параметров метода объекта следует учесть, что необходимо передавать значения всех параметров, включая значения параметров, подставляемые по умолчанию. Для подстановки значений по умолчанию достаточно присвоить тип VT_EMPTY (VT_ERROR для 1С:Предприятия 8) соответствующей структуре VARIANT.

COM-интерфейсы 1C:Предприятия

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

Сохранение параметров объекта компоненты

Для сохранения параметров объект внешней компоненты может использовать механизмы сохранения 1С:Предприятия через интерфейс IPropertyProfile. Этот интерфейс унаследован от интерфейса IPropertyBag, стандартного для COM, и отличается единственным методом:

RegisterProfileAs

Синтаксис:

Копировать в буфер обмена

HRESULT RegisterProfileAs(BSTR bstrProfileName)

Параметры:

<bstrProfileName> Тип: BSTR. Наименование списка параметров компоненты.

Возвращаемое значение:

• S_OK - регистрация прошла успешно.
• E_FAIL - при регистрации произошла ошибка. Информация об ошибке выводится в окно сообщений.

Описание:

Регистрирует список параметров компоненты с именем bstrProfileName.

При загрузке и сохранении параметры могут быть структурированы в виде дерева – для этого при передаче в методах Read и Write имя параметра необходимо записывать в виде "Узел1\Узел2\...\УзелN\ИмяПараметра:ЗначениеПараметраПоУмолчанию". При работе с 1С:Предприятием 7.5 параметры сохраняются в регистрационной базе данных системы (Registry) в ключе HKEY_CURRENT_USER\Software\1C\1Cv7\7.5\Options, при работе с 1С:Предприятием 7.7 - в ключе HKEY_CURRENT_USER\Software\1C\1Cv7\7.7\Options, при работе с 1С:Предприятием 8 – в профиле, соответствующем сочетанию "компьютер – ИБ - пользователь".

Информационные сообщения о работе объекта

Для сообщения пользователю информации о своей работе объект может использовать интерфейс IErrorLog, стандартный для COM (описание метода AddError интерфейса IErrorLog приводится здесь исключительно для удобства работы). Возникающие сообщения обрабатываются как в течение работы программы (при асинхронном помещении их в очередь), так и в следующих случаях: при возврате из метода инициализации Init и при возврате из метода расширения. Все сообщения помещаются в очередь и обрабатываются по порядку появления. Количество запоминаемых сообщений не ограничено.

AddError

Синтаксис:

Копировать в буфер обмена

HRESULT AddError(BSTR pszPropName, LPEXCEPINFO pExcepInfo)

Параметры:

<pszPropName> Тип: BSTR. В настоящей реализации параметр pszPropName игнорируется.

<pExcepInfo> Тип: LPEXCEPINFO. Указатель на структуру EXCEPINFO.

Возвращаемое значение:

• S_OK - сообщение добавлено успешно.
• E_OUTOFMEMORY - Недостаточно памяти.

Возможны другие коды возврата, сигнализирующие об ошибке.

Описание:

Добавляет информационное сообщение при работе методов расширения языка.

Возможные коды сообщений:

#define ADDIN_E_NONE 1000
#define ADDIN_E_ORDINARY 1001
#define ADDIN_E_ATTENTION 1002
#define ADDIN_E_IMPORTANT 1003
#define ADDIN_E_VERY_IMPORTANT 1004
#define ADDIN_E_INFO 1005
#define ADDIN_E_FAIL 1006
#define ADDIN_E_MSGBOX_ATTENTION 1007
#define ADDIN_E_MSGBOX_INFO 1008
#define ADDIN_E_MSGBOX_FAIL 1009

Код сообщения помещается в wCode структуры EXEPINFO. Коды ошибок 1000 – 2000 зарезервированы.

При обработке сообщения выводится окно предупреждения (Message Box) для кодов ADDIN_E_MSGBOX_ATTENTION, ADDIN_E_MSGBOX_INFO и ADDIN_E_MSGBOX_FAIL или строка с сообщением в окне сообщений для остальных кодов. В общем случае строка имеет вид:

<Иконка> <ИсточникСообщения> : <ОписаниеСообщения> (Код сообщения = <КодСообщения>),

где <Иконка>:

ADDIN_E_NONE – иконка отсутствует

ADDIN_E_ORDINARY -

ADDIN_E_ATTENTION -

ADDIN_E_IMPORTANT -

ADDIN_E_VERY_IMPORTANT -

ADDIN_E_INFO -

ADDIN_E_FAIL - (7.5, 7.7) или (8)

Иконка отсутствует, если используется код cообщения, не совпадающий с вышеперечисленными.

<ИсточникОшибки> : поле bstrSource в структуре EXCEPINFO

<ОписаниеОшибки> : поле bstrDescription в структуре EXCEPINFO

<КодОшибки> : числовой код сообщения в десятичном виде. Код сообщения не выводится, если используется один из вышеперечисленных кодов.

Для кодов ADDIN_E_MSGBOX_ATTENTION, ADDIN_E_MSGBOX_INFO и ADDIN_E_MSGBOX_FAIL выводится окно сообщения с кнопкой OK и иконками MB_ICONEXCLAMATION, MB_ICONINFORMATION и MB_ICONERROR соответственно.

Сообщение имеет вид:

<ИсточникСообщения>:<ОписаниеСообщения>(Код cообщения = <КодСообщения>),

где <ИсточникСообщения>, <ОписаниеСообщения> и <КодСообщения> см. выше.

Внешние события

При возникновении асинхронного события (например, считывания штрих-кода) объект может использовать интерфейс IAsyncEvent для создания внешнего события в 1С:Предприятии. Интерфейс IAsyncEvent унаследован от IUnknown. Все события помещаются в очередь и обрабатываются по порядку появления. Количество запоминаемых событий ограничено длиной очереди. При инициализации длина очереди устанавливается равной 1 и может быть изменена вызовами GetEventBufferDepth и SetEventBufferDepth. Для каждого объекта внешней компоненты поддерживается своя очередь событий. Обработка внешнего события производится предопределенной процедурой ОбработкаВнешнегоСобытия и обработчиками внешних событий в модулях форм.

SetEventBufferDepth

Синтаксис:

Копировать в буфер обмена

HRESULT SetEventBufferDepth(long lDepth)

Параметры:

<lDepth> Тип: long. Длина очереди сообщений.

Возвращаемое значение:

• S_OK - размер очереди установлен успешно
• E_FAIL - при установке размера очереди произошла ошибка

Возможны другие коды возврата, сигнализирующие об ошибке.

Описание:

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

GetEventBufferDepth

Синтаксис:

Копировать в буфер обмена

HRESULT GetEventBufferDepth(long *plDepth)

Параметры:

<plDepth> Тип: long*. Указатель на переменную, содержащую при возврате длину очереди сообщений.

Возвращаемое значение:

• S_OK - размер очереди возвращен успешно
• E_FAIL - при получении размера очереди произошла ошибка

Возможны другие коды возврата, сигнализирующие об ошибке.

Описание:

В переменную plDepth помещается размер очереди событий для данного объекта.

ExternalEvent

Синтаксис:

Копировать в буфер обмена

HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData)

Параметры:

<bstrWho> Тип: BSTR. Строка с наименованием источника сообщения.

<bstrWhat> Тип: BSTR. Строка с наименованием сообщения.

<bstrData> Тип: BSTR. Строка с параметрами сообщения.

Возвращаемое значение:

• S_OK – событие помещено в очередь
• E_FAIL – очередь переполнена или неизвестная ошибка
• E_OUTOFMEMORY – отсутствие памяти

Возможны другие коды возврата, сигнализирующие об ошибке.

Описание:

Помещает событие в очередь, записывая источник события, наименование и параметры события. При обработке события эти данные передаются процедуре ОбработкаВнешнегоСобытия. При вызове метода ExternalEvent дальнейшая обработка события происходит следующим образом: событие записывается в очередь событий (если очередь полностью занята, событие теряется), затем при отсутствии системных событий из очереди берется первое событие (если очередь не пуста) и запускается процесс обработки внешних событий. Этот процесс повторяется для всех объектов внешних компонент. Таким образом, обработка внешних событий синхронизируется с обработкой системных событий.

CleanBuffer

Синтаксис:

Копировать в буфер обмена

HRESULT CleanBuffer()

Возвращаемое значение:

• S_OK — очередь успешно очищена
• E_FAIL – при очищении очереди произошла ошибка

Возможны другие коды возврата, сигнализирующие об ошибке.

Описание:

Очищает очередь событий, удаляя все присутствующие в очереди события.

Работа со строкой состояния

Для информирования пользователя о своем состоянии объект компоненты может использовать интерфейс IStatusLine. При вызове метода SetStatusLine переданный текст немедленно отображается в строке состояния. При вызове метода ResetStatusLine в строке состояния отображается стандартный текст.

SetStatusLine

Синтаксис:

Копировать в буфер обмена

HRESULT SetStatusLine(BSTR bstrStatusText)

Параметры:

<bstrStatusText> Тип: BSTR. Текст строки состояния.

Возвращаемое значение:

• S_OK — текст отображен в строке состояния
• E_FAIL – неизвестная ошибка

Возможны другие коды возврата, сигнализирующие об ошибке.

Описание:

Устанавливает текст строки состояния.

ResetStatusLine

Синтаксис:

Копировать в буфер обмена

HRESULT ResetStatusLine()

Возвращаемое значение:

• S_OK —строка состояния успешно переинициализирована
• E_FAIL – неизвестная ошибка

Возможны другие коды возврата, сигнализирующие об ошибке.

Описание:

Инициализирует строку состояния.

Создание окон в среде 1С:Предприятия 7.5, 7.7

Версия технологии: 2.0

Внешние компоненты могут создавать свои окна для отображения различной информации, используя интерфейс IExtWndsSupport. Компонента может создавать три типа окон: модальные диалоги, немодальные диалоги и формы.

Модальные диалоги

Модальные диалоги создаются самой компонентой, но при их создании необходимо в качестве родительского окна указать окно, возвращаемое методом GetAppMainFrame для того, чтобы диалог не воспринимался операционной системой как отдельная задача с кнопкой на полосе задач. Работа системы 1С:Предприятие приостанавливается до завершения работы с диалогом.

Немодальные диалоги

Немодальные диалоги также создаются самой компонентой, но при их создании необходимо в качестве родительского окна указать окно, возвращаемое методом GetAppMDIFrame для того, чтобы диалог не воспринимался операционной системой как отдельная задача с кнопкой на полосе задач. Диалог не останавливает работу 1С:Предприятия и по сути аналогичен формам 1С:Предприятия. Однако следует учесть, что созданный диалог не входит в список открытых окон и не появляется на панели окон, поэтому использование таких диалогов не рекомендуется (вместо них можно использовать формы самого 1С:Предприятия или формы, созданные внешней компонентой).

Формы

Формы создаются функцией CreateAddInWindow и аналогичны формам, созданным в 1С:Предприятии. При создании окна внешняя компонента передает в качестве одного из параметров ProgID COM-объекта, поддерживающего некоторый предопределенный набор интерфейсов, описанный в технологии Активных документов (Active Documents, см. документацию по COM). Этот объект отображается в окне 1С:Предприятия и может управляться внешней компонентой через возвращаемый интерфейс IDispatch.

От объекта, отображаемого в окне 1С:Предприятия, не требуется следование технологии внешних компонент, необходимо лишь следование стандарту на Активные документы.

GetAppMainFrame

Синтаксис:

Копировать в буфер обмена

HRESULT GetAppMainFrame(HWND *pHWnd)

Параметры:

<pHWnd> Тип: HWND*. Указатель на дескриптор окна

Возвращаемое значение:

• S_OK

Описание:

Возвращает дескриптор основного окна 1С:Предприятия.

GetAppMDIFrame

Синтаксис:

Копировать в буфер обмена

HRESULT GetAppMDIFrame(HWND *pHWnd)

Параметры:

<pHWnd> Тип: HWND*. Указатель на дескриптор окна

Возвращаемое значение:

• S_OK

Описание:

Возвращает дескриптор окна 1С:Предприятия, являющегося родительским для форм 1С:Предприятия.

CreateAddInWindow

Синтаксис:

Копировать в буфер обмена

HRESULT CreateAddInWindow(BSTR bstrProgID, BSTR bstrTitle, long lStyles, long lExStyles, RECT *rctSize, long lFlags, HWND *pHwnd, IDispatch **pDisp)

Параметры:

<bstrProgID> Тип: BSTR. ProgID COM-объекта, являющегося Активным документом.

<bstrWindowName> Тип: BSTR. Заголовок окна.

<lStyles> Тип: long. Стили окна.

<lExStyles> Тип: long. Дополнительные стили окна.

<rctSize> Тип: RECT*. Размеры окна.

<lFlags> Тип: long. Дополнительные флаги.

<pHwnd> Тип: HWND*. Указатель на дескриптор окна.

<pDisp> Тип: IDispatch**. Указатель на интерфейс IDispatch созданного Активного документа.

Возвращаемое значение:

• S_OK —окно успешно создано
• E_FAIL –ошибка при создании окна

Возможны другие коды возврата, сигнализирующие об ошибке.

Описание:

Создает окно 1С:Предприятия с объектом bstrProgID. Окно имеет заголовок bstrWindowName и стили lStyles и lExStyles. При передаче 0 в качестве стилей используются стили окна по умолчанию. Размеры окна указываются следующим образом: верхний левый угол rctSize обозначает верхний левый угол создаваемого окна в координатах экрана, ширина и высота rctSize соответствуют ширине и высоте клиентской части создаваемого окна (т.е. той части, где отображается Активный документ). Параметр lFlags в настоящее время не используется и должен быть равен 0. В параметрах pHwnd и pDisp возвращаются соответственно дескриптор созданного окна и интерфейс IDispatch объекта bstrProgID.

Создание окон в среде 1С:Предприятия 8

В 1С:Предприятии 8 эта возможность сохранена в сокращенном виде для совместимости с существующими компонентами. Для отображения нестандартной информации в окнах 1С:Предприятия 8 рекомендуется использовать формы с элементами управления ActiveX или же Активные документы. Ниже приведены описания методов интерфейса IExtWndsSupport.

GetAppMainFrame

Синтаксис:

Копировать в буфер обмена

HRESULT GetAppMainFrame(HWND *pHWnd)

Параметры:

<pHWnd> Тип: HWND*. Указатель на дескриптор окна

Возвращаемое значение:

• S_OK

Описание:

Возвращает дескриптор основного окна 1С:Предприятия.

GetAppMDIFrame

Синтаксис:

Копировать в буфер обмена

HRESULT GetAppMDIFrame(HWND *pHWnd)

Параметры:

<pHWnd> Тип: HWND*. Указатель на дескриптор окна

Возвращаемое значение:

• S_OK

Описание:

Возвращает дескриптор активного окна 1С:Предприятия.

CreateAddInWindow

Синтаксис:

Копировать в буфер обмена

HRESULT CreateAddInWindow(BSTR bstrProgID, BSTR bstrTitle, long lStyles, long lExStyles, RECT *rctSize, long lFlags, HWND *pHwnd, IDispatch **pDisp)

Возвращаемое значение:

Всегда возвращает E_FAIL.

Доступ к 1С:Предприятию через механизм OLE Automation

Версия технологии: 2.0

Переданный в методе Init указатель на IDispatch позволяет получить доступ к 1С:Предприятию через механизм OLE Automation. Из полученного указателя можно получить свойство AppDispatch, доступное только для чтения. Это свойство содержит указатель на IDispatch 1C:Предприятия (не путайте с переданным в Init).

Свойство AppDispatch становится доступно только после полной инициализации всей системы 1С:Предприятие, поэтому в момент загрузки внешней компоненты и вызова метода Init это свойство обеспечивает доступ не ко всем возможностям 1С:Предприятия.

Доступ к методам интерфейсов 1С:Предприятия через OLE Automation

Visual Basic имеет ограниченные возможности по работе с различными интерфейсами. Наиболее "естественным" механизмом для Visual Basic является работа с OLE Automation, для этого в VB используется тип Object, который представляет собой указатель на IDispatch. Поэтому 1С:Предприятие предоставляет возможность использовать механизм OLE Automation, передавая указатель на IDispatch в методе Init и обеспечивая вызовы методов вышеперечисленных интерфейсов через OLE Automation.

Методы и свойства, доступные через OLE Automation:

Версия технологии: 1.0

RegisterProfileAs(<ИмяСпискаПараметров>)
Read(<ИмяПеременной>,<СсылкаНаVARIANT>)
Write(<ИмяПеременной>,<СсылкаНаVARIANT>)
SetEventBufferDepth(<ДлинаОчередиСобытий>)
GetEventBufferDepth(<СсылкаНаДлинуОчереди>)
ClearEventBuffer()
ExternalEvent(<СтрокаИсточникСобытия>,<СтрокаНаименованиеСобытия>,<СтрокаПараметрыСобытия>)
AddError(<КодСообщения>,<СтрокаИсточникСообщения>,<СтрокаОписаниеСообщения>,<КодОшибки>)
SetStatusLine(<СтрокаСостояния>)
ResetStatusLine()

Версия технологии: 2.0 (дополнительно к 1.0)

свойство AppDispatch
GetAppMainFrame(<Указатель на дескриптор окна>)
GetAppMDIFrame(<Указатель на дескриптор окна>)
CreateAddInWindow(<ProgID>, <Заголовок окна>, <Стили окна>, <Доп. стили окна>, <Координата верхнего левого угла окна по горизонтали>, <Координата верхнего левого угла окна по вертикали>, <Ширина окна>, <Высота окна>, <Доп. флаги (всегда 0)>, <Указатель на дескриптор окна>, <Указатель на интерфейс IDispatch)

Глава 2. Примеры внешних компонент

В поставку настоящей методики входят примеры реализации внешних компонент в трех различных средах разработки: Microsoft Visual Basic, Microsoft Visual C++, Borland Delphi. Для работы с этими компонентами в поставку включены конфигурации для различных версий 1С:Предприятия, позволяющие протестировать функции компонент. Кроме примера в поставку включены шаблоны, позволяющие упростить создание компоненты "с нуля".

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

Структура каталогов

Каталог TEMPLATE – каталог, содержащий шаблоны для создания внешних компонент "с нуля". Каталоги DELPHI30 и DELPHI4+ содержат шаблоны для Borland Delphi 3.0 и 4.0-7.0 соответственно, каталог VB50+ - для Visual Basic 5.0-6.0, каталог VC50+ - для Visual C++ 5.0-7.0, каталог VB.NET - для Visual Basic .NET.

Каталоги V75, V77 и V80 имеют схожую структуру и содержат материалы, предназначенные для работы с 1С:Предприятием версий 7.5, 7.7 и 8 соответственно. В подкаталоге DB находится конфигурация 1С:Предприятия, в подкаталогах DELPHI, VB и VC – примеры внешних компонент, созданных в различных средах разработки. В указанных каталогах присутствуют подкаталогах SAMPLE и SAMPLE2, содержащие версии компонент 1.0 и 2.0 соответственно.

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

Описание конфигураций

Конфигурация для 1С:Предприятия 7.5

В конфигурации используется только глобальный модуль и отчет ПримерРаботыСКомпонентой. В глобальном модуле загружается внешняя компонента и создается объект "AddIn.AddInExtension":

Перем Компонент Экспорт;
ЗагрузитьВнешнююКомпоненту("Addin.dll");
Компонент = СоздатьОбъект("AddIn.AddInExtension");

После создания объекта можно использовать его свойства и методы в отчете ПримерРаботыСКомпонентой.

Этот отчет использует свойство объекта Включен при инициализации и обработке внешнего события, порождаемого компонентой при изменении этого свойства:

Форма отчета ПримерРаботыСКомпонентой:

Процедура ОбработкаВнешнегоСобытия(Источник,Событие,Данные)
Если (Источник = "Компонента") И (Событие = "Включение") Тогда
// Сигнал об изменении статуса компоненты
Если (Данные = "1") Тогда
Форма.ТекстСтатуса.Доступность(1);
Форма.ПоказатьТекст.Доступность(1);
Если (Компонент.ЕстьТаймер <> 0) Тогда
Форма.СтартТаймер.Доступность(1);
Форма.СтопТаймер.Доступность(1);
Иначе
Форма.СтартТаймер.Доступность(0);
Форма.СтопТаймер.Доступность(0);
КонецЕсли
Иначе
Форма.ТекстСтатуса.Доступность(0);
Форма.ПоказатьТекст.Доступность(0);
Форма.СтартТаймер.Доступность(0);
Форма.СтопТаймер.Доступность(0);
КонецЕсли
КонецЕсли;
КонецПроцедуры
Процедура ПриОткрытии()
// Проверка на включение компоненты
Если (Компонент.Включен <> 0) Тогда
Форма.ТекстСтатуса.Доступность(1);
ТекстСтатуса = "Этот текст появится в строке статуса";
Форма.ПоказатьТекст.Доступность(1);
// Проверка на присутствие таймера в компоненте
Если (Компонент.ЕстьТаймер <> 0) Тогда
Форма.СтартТаймер.Доступность(1);
Время = "Время";
Форма.СтопТаймер.Доступность(1);
Иначе
Форма.СтартТаймер.Доступность(0);
Форма.СтопТаймер.Доступность(0);
КонецЕсли
Иначе // Сделать элементы диалога недоступными
Форма.ТекстСтатуса.Доступность(0);
Форма.ПоказатьТекст.Доступность(0);
Форма.СтартТаймер.Доступность(0);
Форма.СтопТаймер.Доступность(0);
КонецЕсли
КонецПроцедуры

Для создания внешнего события откройте отчет и затем страницу параметров компоненты. Включите компоненту и нажмите кнопку "Применить" — элементы формы отчета должны стать доступными. При выключении компоненты элементы формы становятся недоступными.

Кнопки "Старт" и "Стоп" соответственно запускают и останавливают таймер. При этом в форме отображается текущее время. Это обрабатывается следующей частью процедурой ОбработкаВнешнегоСобытия:

Если (Источник = "Компонента") И (Событие = "Таймер") Тогда
// Сигнал об изменении времени
Время = Данные;
Форма.Обновить();
КонецЕсли

Конфигурация для 1С:Предприятия 7.7

В конфигурации используются только глобальный модуль и обработка ПримерРаботыСКомпонентой. В глобальном модуле загружается внешняя компонента и создается объект "AddIn.AddInVideo":

Перем БазовыйОбъект Экспорт;
ЗагрузитьВнешнююКомпоненту("AddIn.dll");
БазовыйОбъект = СоздатьОбъект("AddIn.AddInVideo");

После создания объекта можно использовать его свойства и методы в обработке ПримерРаботыСКомпонентой.

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

Примеры для Visual Basic и Visual C++ используют элемент управления ActiveX Microsoft Multimedia Control, входящий в поставку Visual Basic и Visual C++. Пример для Borland Delphi использует встроенный элемент управления TMediaControl, обеспечивающий те же функции, что и Multimedia Control.

Конфигурация для 1С:Предприятия 8

В конфигурации используется только модуль приложения и обработка ПримерРаботыСКомпонентой. В модуле основной формы обработки загружается внешняя компонента и создается объект "AddIn.AddInExtension":

ЗагрузитьВнешнююКомпоненту("Addin.dll");
Компонент = СоздатьОбъект("AddIn.AddInExtension");

После создания объекта можно использовать его свойства и методы.

Эта обработка использует свойство объекта Включен при инициализации и обработке внешнего события, порождаемого компонентой при изменении этого свойства:

Процедура УстановитьЭУ(ЭУДоступны)
Если ЭУДоступны Тогда
ЭлементыФормы.ТекстСтатуса.Доступность = Истина;
ЭлементыФормы.ПоказатьТекст.Доступность = Истина;
Если (Компонент.ЕстьТаймер <> 0) Тогда
ЭлементыФормы.СтартТаймер.Доступность = Истина;
ЭлементыФормы.СтопТаймер.Доступность = Истина;
Иначе
ЭлементыФормы.СтартТаймер.Доступность = Ложь;
ЭлементыФормы.СтопТаймер.Доступность = Ложь;
КонецЕсли
Иначе
ЭлементыФормы.ТекстСтатуса.Доступность = Ложь;
ЭлементыФормы.ПоказатьТекст.Доступность = Ложь;
ЭлементыФормы.СтартТаймер.Доступность = Ложь;
ЭлементыФормы.СтопТаймер.Доступность = Ложь;
КонецЕсли;
КомпонентаВключена = ЭУДоступны;
КонецПроцедуры
Процедура ВнешнееСобытие(Источник, Событие, Данные)
Если (Событие = "Включение") Тогда
// Сигнал об изменении статуса компоненты
УстановитьЭУ(?(Данные = "1", Истина, Ложь));
КонецЕсли;
Если (Событие = "Таймер") Тогда
// Сигнал об изменении времени
Время = Данные;
Обновить();
КонецЕсли
КонецПроцедуры
Процедура КомпонентаВключенаПриИзменении(Элемент)
Компонент.Включен = ?(КомпонентаВключена, 1, 0);
УстановитьЭУ(КомпонентаВключена);
КонецПроцедуры
Процедура ПриОткрытии()
ТекстСтатуса = "Этот текст появится в строке статуса";
// Проверка на присутствие таймера в компоненте
Если (Компонент.ЕстьТаймер <> 0) Тогда
Время = "Время";
КонецЕсли;
// Проверка на включение компоненты
КомпонентаВключена = ?(Компонент.Включен <> 0, Истина, Ложь);
УстановитьЭУ(КомпонентаВключена);
КонецПроцедуры

Для создания внешнего события откройте обработку и затем страницу параметров компоненты. Включите компоненту и нажмите кнопку "Применить" — элементы формы обработки должны стать доступными. При выключении компоненты элементы формы становятся недоступными.

Кнопки "Старт" и "Стоп" соответственно запускают и останавливают таймер. При этом в форме отображается текущее время. Это обрабатывается следующей частью процедурой ОбработкаВнешнегоСобытия:

Если (Событие = "Таймер") Тогда
// Сигнал об изменении времени
Время = Данные;
Обновить();
КонецЕсли

Ссылка "Открыть новый экземпляр формы" используется для демонстрации использования свойства AppDispatch – в данном примере, используя это свойство, внешняя компонента может открывает новый экземпляр формы обработки ПримерРаботыСКомпонентой.

Описание компонент

Компонента SAMPLE

Компонента реализует следующие свойства и методы:

Свойства

Включен (IsEnabled)

Использование: Чтение и запись.

Описание: Тип: Булево. Содержит состояние компоненты.

ЕстьТаймер (IsTimerPresent)

Использование: Чтение.

Описание: Тип: Булево. Определяет наличие у компоненты таймера.

Методы

Включить (Enable)

Синтаксис:Включить()

Описание: Включает объект компоненты.

Выключить (Disable)

Синтаксис: Выключить()

Описание: Выключает объект компоненты.

ПоказатьВСтрокеСтатуса (ShowInStatusLine)

Синтаксис: ПоказатьВСтрокеСтатуса(<Текст>)

Параметры: Текст. Текст, выводимый в строке статуса.

Описание: На 5 секунд выводит в строку статуса полученный текст.

ВключитьТаймер (StartTimer)

Синтаксис: ВключитьТаймер()

Описание: Включает таймер компоненты. Каждую секунду компонента посылает сообщение 1С:Предприятию с параметрами "Компонента", "Таймер" и строкой времени.

ВыключитьТаймер (StopTimer)

Синтаксис: ВыключитьТаймер()

Описание: Выключает таймер компоненты.

ОткрытьФорму (OpenForm)

Синтаксис: ОткрытьФорму()

Описание: Открывает новый экземпляр формы обработки ПримерРаботыСКомпонентой. Этот метод присутствует только в компоненте для 1С:Предприятия 8.

Для управления компонентой используется страница свойств с опцией включения компоненты. При нажатии кнопки "Применить" компонента посылает сообщение 1С:Предприятию с параметрами "Компонента", "Включение" и строкой "0" или "1" в зависимости от включения компоненты. При подключении и отключении компонента загружает и сохраняет состояние включения.

Страница свойств компоненты

В VB.NET отсутствует поддержка страниц свойств для элементов управления, поэтому в компоненте, разработанной на VB.NET, страница свойств компоненты не реализована.

Компонента SAMPLE2

Компонента позволяет проигрывать видеоклипы формата AVI в окне 1С:Предприятия 7.7.

Компонента реализует следующие свойства и методы:

Свойства

ФайлКлипа (FileName)

Использование:

Чтение и запись.

Описание:

Тип: Строка. Содержит полное имя файла с видеоклипом.

Методы

Показать (Show)

Синтаксис:

Показать()

Описание:

Открывает окно с клипом, переданным в свойство ФайлКлипа.

ОткрытьКлипИзФайла (OpenFromFile)

Синтаксис:

ОткрытьКлипИзФайла()

Описание:

Открывает окно с клипом, выбранным из файлов на диске.

ОткрытьКлипИзСправочника (OpenFromRef)

Синтаксис:

ОткрытьКлипИзСправочника()

Описание:

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

ОткрытьКлипИзФайла и ОткрытьКлипИзСправочника открытия окна используют внешнее событие, передавая в качестве одного из параметров имя выбранного файла. Метод ОткрытьКлипИзСправочника использует OLE Automation 1C:Предприятия для доступа к справочнику клипов "Клипы".

Microsoft Visual C++

Компонента SAMPLE

Пример в Visual C++ написан с использованием библиотеки ATL (Active Template Library), входящей в состав поставки VC++.

Определение интерфейсов 1С:Предприятия

Все интерфейсы 1С:Предприятия определены в файле AddIn.idl. Этот файл содержит определения интерфейсов на IDL — Interface Definition Language. При компиляции проекта этот файл обрабатывается утилитой MIDL, порождающей файлы с определениями интерфейсов для C++ (AddInTlb.h, AddIn_i.c) и библиотекой типов AddIn.tlb.

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

Заголовочный файл AddIn.h содержит определение объекта CAddIn, унаследованного от различных интерфейсов и базовых COM-объектов:

Классы CComObjectRoot и CComCoClass являются базовыми для COM-объектов в ATL. IInitDone и ILanguageExtender — интерфейсы объекта внешней компоненты. IPropertyPageImpl и CDialogImpl реализуют страницу свойств объекта.

Следут обратить внимание на то, что класс CAddIn реализует одновременно как объект внешней компоненты, так и объект страницы свойств. Но поскольку объект и страница свойств являются различными экземплярами класса CAddIn, для их связи используется интерфейс IPropertyLink, определенный именно для этой компоненты.

Реализация объекта внешней компоненты

Реализация класса CAddIn находится в файле AddIn.cpp. В реализации используются функции LoadProperties и SaveProperties, в которые выносится загрузка и сохранение параметров объекта компоненты; функция TermString, упрощающая реализацию расширения встроенного языка; и функции GetNParam и PutNParam, использующиеся в реализации методов CallAsProc и CallAsFunc.

Интерфейсы IInitDone и ILanguageExtender определены в соответствии с настоящим описанием. Реализации методов расширения находятся в методе ILanguageExtender::CallAsProc, так как ни один из методов не возвращает значения. Методы Включить и Выключить достаточно просты и не нуждаются в разборе. Методы работы с таймером используют системные функции SetTimer и KillTimer, реализация функции таймера находится в конце файла. Метод ПоказатьВСтрокеСтатуса более сложен: он использует в своей работе интерфейс IErrorLog:

if (m_iErrorLog)
{
	CString csErrorSource,csErrorDescription,csNull = "";

	EXCEPINFO eiInfo;
	eiInfo.wCode = ADDIN_E_VERY_IMPORTANT;
	eiInfo.scode = S_OK;
	csErrorSource.LoadString(IDS_ERROR_SOURCE);
	eiInfo.bstrSource = csErrorSource.AllocSysString();
	csErrorDescription.LoadString(IDS_ERROR_DESCRIPTION);
	eiInfo.bstrDescription = csErrorDescription.AllocSysString();

	m_iErrorLog->AddError(csNull.AllocSysString(),&eiInfo);
}

Если у объекта почему-либо отсутствует указатель на интерфейс IStatusLine, объект посылает информацию через интерфейс IErrorLog. Поля wCode и scode заполняются соответствующими кодами ошибок. Поля bstrSource и bstrDescription заполняются строками, описывающими соответственно источник ошибки и саму ошибку. Для работы с строками COM в VC++ удобно использовать CString и функцию AllocSysString, возвращающую BSTR.

Создание собственной компоненты

При разработке собственной компоненты можно использовать шаблон из данной методики или начать разработку компоненты "с нуля". В последнем случае необходимо:

1. Выбрать из меню File | New...
2. В закладке Projects выбрать ATL COM AppWizard (ATL Project для VC++ 7.0), задать имя проекта и его расположение.
3. Нажать OK.
4. Выбрать создание DLL и завершить создание объекта.

По расположению в файлах созданный проект будет практически аналогичен (с точностью до имен файлов) шаблону из данной методики. Необходимо лишь внести в IDL—файл определения интерфейсов 1С:Предприятия, отредактировать определение объекта внешней компоненты, внести строку с индексом 100 для автоматического создания объекта 1С:Предприятием при загрузке и запрограммировать функциональность компоненты.

Компонента SAMPLE2

Пример написан в Visual C++ с использованием библиотеки MFC, входящей в состав поставки VC++.

Структура проекта

Проект разбит на две части - часть ActDoc реализует Активный документ, часть AddIn реализует внешнюю компоненту для взаимодействия с 1С:Предприятием 7.7 и создания окна Активного документа. Внешняя компонента создана на основе шаблона, поэтому ее описание здесь не приводится.

Активный документ

Реализация Активного документа в Visual C++ с использованием MFC достаточно сложна, поэтому ниже описаны только некоторые детали, необходимые для понимания работы документа. Для детального разбора реализации Вам необходимо обратиться к соответствующей справочной литературе.

Для определения Активного документа используется несколько различных классов, основные из которых – класс CAddDocDoc, реализующий документ, и класс CAddDocView, реализующий визуальную часть документа. Эти классы определены в файлах AddDoc.h и AddDoc.cpp. Документ использует элемент Cmci, полученный импортированием ActiveX (см. пункт меню Project|Add To Project|Components and Controls…) и представляющий интерфейс к Microsoft Multimedia Control. Cmci создается и отображается в окне в методе OnInitialUpdate класса CAddDocView. При изменении размеров окна CAddDocView соответственно изменяет размеры Cmci. Для управления извне документ реализует два метода, доступных через OLE Automation: SetFileName и Play.

Создание собственной компоненты

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

1. Выбрать из меню File | New...
2. В закладке Projects выбрать MFC AppWizard (EXE), задать имя проекта и его расположение.
3. Нажать OK.
4. Выбрать необходимые параметры сервера, поддержку OLE Automation и ActiveX Controls (в данном примере miniserver с поддержкой OLE Automation и ActiveX Controls) и завершить создание объекта.

Далее можно добавить проект, содержащий реализацию внешней компоненты и при создании окна передавать в качестве ProgID идентификатор созданного MFC AppWizard Активного документа. В качестве добавляемого проекта можно использовать входящий в комплект поставки шаблон.

Microsoft Visual Basic 5.0 и 6.0 (Enterprise Edition)

Общая часть компонент

Определение интерфейсов 1С:Предприятия

В комплект поставки включена библиотека типов AddIn.tlb, на который должна быть установлена ссылка из проекта. Для установки ссылки нужно сделать следующее:

1. Открыть проект в Visual Basic.
2. Выбрать пункт Project | References...
3. Нажать кнопку Browse...
4. Выбрать файл AddIn.tlb и нажать кнопку Open.
5. Нажать ОК.

Возможно, что библиотека типов уже зарегистрирована на Вашем компьютере. Тогда в п.3 вместо нажатия Browse... выберите библиотеку V7 AddIn 1.0 Type Library в списке библиотек и включите опцию выбора.

Установление ссылки на библиотеку типов позволяет использовать наименования COM-интерфейсов в операторе Implements при реализации COM-объекта.

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

В реализации используются функции LoadProperties и SaveProperties, в которые выносится загрузка и сохранение параметров объекта компоненты; функция TermString, упрощающая реализацию расширения встроенного языка; функции GetNParam и PutNParam, используемые в Visual C++ и Borland Delphi, отсутствуют, так как в Visual Basic встроена работа с структурой SAFEARRAY.

В Visual Basic отсутствует доступ к ресурсам проекта, поэтому строка с номером 100 добавляется в виде скомпилированного файла ресурсов AddInStr.res. Этот файл можно получить, скомпилировав файл AddInStr.rc утилитой RC.EXE (эта утилита входит в поставку Visual Basic 5.0). Командная строка проста: RC AddInStr.rc. Файл AddInStr.rc — это обычный текстовый файл, который можно править любым текстовым редактором.

Компонента SAMPLE

Пример в Visual Basic (Enterprise Edition) использует новые возможности, появившиеся в версии 5.0, а именно: возможность создания ActiveX элементов и использование нестандартных интерфейсов. В реализации компоненты на Visual Basic 5.0 отсутствуют функции таймера.

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

Определение и реализация объекта компоненты находятся в файле AddInObj.ctl. В реализации на Visual Basic объект компоненты является ActiveX элементом, поэтому все необходимые интерфейсы невидимы для пользователя и все действия выполняются визуально. Например, для связи ActiveX элемента и страницы свойств используется свойство элемента PropertyPages, интерфейс ISpecifyPropertyPages объект реализует автоматически. Необходимо только добавить строки:

Implements IInitDone
Implements ILanguageExtender

для реализации объектом соответствующих интерфейсов. Определения интерфейсов будут автоматически взяты из библиотеки типов.

Следует обратить внимание на свойства InvisibleAtRuntime: True — это позволяет реализовать невидимый элемент, и Name: AddInObj — это вторая часть ProgID объекта компоненты. Первая часть ProgID — это свойство Name проекта, поэтому проект называется AddIn для автоматического создания объекта при использовании функции ЗагрузитьВнешнююКомпоненту.

Определение и реализация страницы свойств внешней компоненты

Определение и реализация страницы свойств находятся в файле PropPage.pag. Они достаточно просты и понятны без дополнительных объяснений. Можно лишь отметить, что в отличие от компонент, написанных на Visual C++ и Borland Delphi, обмен данными происходит не через дополнительный интерфейс, а через глобальные переменные, определенные в файле AddInMod.bas.

Создание собственной компоненты

При разработке собственной компоненты можно использовать шаблон из данной методики или начать разработку компоненты "с нуля". В последнем случае необходимо:

1. Выбрать из меню File | NewProject.
2. Выбрать ActiveX Control.
3. Внести оператор Implements в текст файла ActiveX элемента.

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

При необходимости добавить страницу свойств в проект:

1. Выбрать из меню Project| Add Property Page.
2. Установить свойство ActiveX элемента PropertyPages на созданную страницу.

Компонента SAMPLE2

Этот пример в Visual Basic (Enterprise Edition) использует возможности создания Active Document и использования нестандартных интерфейсов.

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

Определение и реализация объекта компоненты находятся в файле AddInDoc.dob. В реализации на Visual Basic внешняя компонента и Активный документ реализованы одним объектом, поэтому в этот файл добавлены строки:

Implements IInitDone
Implements ILanguageExtender

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

ProgID COM-объекта в этом примере складывается из двух частей: названия проекта и названия Активного документа, поэтому при создании окна 1С:Предприятия передается "AddIn.AddInDoc".

Создание собственной компоненты

При разработке собственной компоненты можно использовать шаблон из данной методики или начать разработку компоненты "с нуля". В последнем случае необходимо:

1. Выбрать из меню File | NewProject.
2. Выбрать ActiveX Document Dll.
3. Внести оператор Implements в текст файла ActiveX Document.

Visual Basic .NET

Пример в Visual Basic .NET использует возможности взаимодействия технологии .NET с COM (так называемый COM Interop). В реализации компоненты на Visual Basic .NET отсутствуют функции таймера.

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

Определение и реализация объекта компоненты находятся в файле AddInObj.vb. В реализации на Visual Basic .NET объект компоненты является COM-классом, реализующим интерфейсы внешней компоненты IInitDone и ILanguageExtender. Для определения этих интерфейсов в проекте присутствует ссылка на библиотеку типов (type library) AddInLib – по этой ссылке строится соответствующая Interop.AddInLib.dll, необходимая для взаимодействия с COM. В целом код объекта по сравнению с реализацией в Visual Basic 6.0 практически не изменен, за исключением следующих моментов:

• некоторые типы VB 6.0 заменены на соответствующие типы .NET (например Integer заменен на Long и Variant на Object);
• методы интерфейсов объявлены как Overridable Overloads, соответствие методам интерфейсов задается конструкцией Implements;
• после обнуления ссылок на объекты 1С:Предприятия выполняется процедура сборки "мусора" GC.Collect() и ожидание завершения этой процедуры GC.WaitForPendingFinalizers().

В среде Visual Basic .NET отсутствует поддержка создания страницы свойств, поэтому реализация страницы свойств отсутствует. Для включения/выключения объекта используется флажок КомпонентаВключена формы обработки ПримерРаботыСКомпонентой.

Включение стандартных Win32-ресурсов в проект Visual Basic .NET может выполняться только при компиляции проекта в командной строке (ключ /win32res), поэтому в поставку настоящего продукта включена готовая внешняя компонента с уже добавленной строкой с ID 100.

Создание собственной компоненты

При разработке собственной компоненты можно использовать шаблон из данной методики или начать разработку компоненты "с нуля". В последнем случае необходимо:

1. Зарегистрировать входящую в поставку библиотеку типов AddIn.tlb с помощью утилиты regtlib: regtlib addin.tlb. Утилита regtlib входит в состав Internet Explorer и различных сред разработки.
2. В Visual Basic .NET выбрать из меню пункт File | New | Project.
3. Из раздела Visual Basic Projects выбрать Empty Project. после создания изменить тип проекта (output type) на Class Library и пространство имен (root namespace) на AddIn.
4. В раздел проекта References добавить ссылку на библиотеку типов V7 AddIn 1.0 Type Library (эта библиотека находится в списке библиотек на закладке COM).
5. Из контекстного меню проекта выбрать Add | Add New Item… и в появившемся диалоге выбрать COM Class. Название файла соответствует названию класса и, таким образом, вместе с пространством имен формирует ProgId.
6. Внести в код созданного класса операторы Implements для необходимых интерфейсов и соответствующие этим интерфейсам определения и реализации методов.

Borland Delphi

Общая часть компонент

Определение интерфейсов 1С:Предприятия

Все интерфейсы 1С:Предприятия определены в модуле AddInLib.pas. Этот модуль импортируется директивой uses в модулях, использующих эти определения.

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

В реализации используются функции LoadProperties и SaveProperties, в которые вынесены загрузка и сохранение параметров объекта компоненты; функция TermString, упрощающая реализацию расширения встроенного языка; и функции GetNParam и PutNParam, использующиеся в реализации методов CallAsProc и CallAsFunc.

Компонента SAMPLE

Пример в Borland Delphi написан на стандартном Object Pascal и не использует никаких специальных свойств и библиотек.

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

И определение, и реализация объекта находятся в модуле AddInObj. Для привязки к странице свойств используется интерфейс ISpecifyPropertyPages и метод этого интерфейса GetPages. Для связи со страницей свойств и обмена данными используется интерфейс IPropertyLink. Главная деталь, на которую необходимо обратить внимание — создание "фабрики" объектов TComObjectFactory:

ComServer.SetServerName('AddIn'); TComObjectFactory.Create(ComServer,TAddInObject, CLSID_AddInObject, 'AddIn','V7 AddIn 1.0',ciSingleInstance);

Наименование сервера ComServer образует первую часть ProgID объекта. Так как 1С:Предприятие при создании объекта функцией ЗагрузитьВнешнююКомпоненту использует ProgID вида "AddIn.<Component>", то имени сервера должна быть присвоена строка "AddIn". Далее, в Delphi отсутствует доступ к таблице строк в ресурсах создаваемого COM-сервера, поэтому необходимо использовать имя создаваемой библиотеки в качестве второй части ProgID. Поскольку компонента компилируется в библиотеку с именем AddIn.dll, то в параметр ClassID передается строка "AddIn". Все вышеперечисленное относится лишь к использованию функции ЗагрузитьВнешнююКомпоненту, так как функция ПодключитьВнешнююКомпоненту получает ProgID как параметр.

Определение и реализация страницы свойств внешней компоненты

Определение и реализация страницы свойств располагаются в модуле PropPage.pas и форме PropPage.dfm. Класс TAddInPropPage унаследован от стандартного класса TPropertyPage и использует переопределение стандартных функций UpdatePropertyPage (вызывается при открытии страницы свойств) и UpdateObject (вызывается при нажатии кнопки "Применить" или "ОК").

Создание собственной компоненты

При разработке собственной компоненты можно использовать шаблон из данной методики или начать разработку компоненты "с нуля". В последнем случае необходимо:

1. Выбрать из меню File | New...
2. В закладке ActiveX выбрать ActiveX Library.
3. В свойствах проекта на закладке Linker выбрать опцию Generate Object files.

Специфическая для Borland Delphi деталь, относящаяся к проекту: при разработке компоненты в свойствах проекта на закладке Linker необходимо выбирать опцию Generate Object files. Это свойство требуется для правильной работы страницы свойств (если это свойство не установлено, 1С:Предприятие после завершения работы может остаться работать в фоновом режиме).

При необходимости добавить в проект страницу свойств:

1. Выбрать из меню File | New...
2. В закладке ActiveX выбрать Property Page.

Файл, аналогичный AddInObj, Delphi не создает, поэтому определение и реализацию объекта разработчику нужно написать самому.

Отличие в реализации для Delphi 4.0

При работе с объектами, унаследованными от TAutoObject, необходимо использовать TAutoObjectFactory, что в свою очередь требует использования в проекте библиотеки типов (Type Library). Однако ее подключение усложнило бы проект, поэтому TAddInObject унаследован от TComObject.

Для корректной работы страницы свойств в Delphi 4.0 требуется, чтобы объекты, чьи свойства отображаются на странице, имели интерфейс IDispatch (при наследовании от TAutoObject это требование выполнялось автоматически). Поэтому TAddInObject реализует также IDispatch, но методы IDispatch не реализованы.

Компонента SAMPLE2

Этот пример в Borland Delphi также написан на стандартном Object Pascal и не использует никаких специальных свойств и библиотек.

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

И определение, и реализация объекта находятся в модуле AddInVid. Страница свойств в этом примере не используется. Главная деталь, на которую необходимо обратить внимание — создание "фабрики" объектов TComObjectFactory:

TComObjectFactory.Create(ComServer, TAddInVideo, Class_AddInVideo, 'AddInVideo', '', ciMultiInstance, tmApartment);

При этом в регистрационную базу данных системы(Registry) заносится ProgID "AddIn.AddInVideo". Для создания объекта при загрузке внешней компоненты необходимо, чтобы строка с ID 100 содержала вторую часть ProgID созадваемого объекта. Для этого в проект директивой {$R AddInStr.RES} включен ресурсный файл AddInStr, содержащий строку AddInVideo и скомпилированный из AddInStr.rc компилятором ресурсов rc.exe.

При создании дополнительного окна в качестве Активного документа передается документ, реализованный в файле AddInDoc.pas. При успешном создании окна в параметре cntr находится указатель на интерфейс IDispatch, что позволяет управлять созданным документом.

Определение и реализация Активного документа

Определение и реализация Активного документа находятся в модуле AddInDoc. Этот модуль и соответствующая ему форма создаются средой при создании документа. Одновременно создается библиотека типов, содержащая описание интерфейсов документа. Для редактирования свойств документа рекомендуется пользоваться именно библиотекой типов, так как в этом случае все необходимые определения и реализации методов генерируются средой автоматически. В форму документа включен элемент TMediaControl, доступный в закладке System панели элементов управления.

Использование библиотеки типов (Type Library)

Библиотека типов создается средой при создании Активного документа. Состав библиотеки можно редактировать, выбрав пункт меню View|Type Library. В примере к библиотеке добавлены два метода Play и SetFileName.

Создание собственной компоненты

При разработке собственной компоненты можно использовать шаблон из данной методики или начать разработку компоненты "с нуля". В последнем случае необходимо:

1. Выбрать из меню File | New...
2. В закладке ActiveX выбрать ActiveX Library.
3. В свойствах проекта на закладке Linker выбрать опцию Generate Object files.

Специфическая для Borland Delphi деталь, относящаяся к проекту: при разработке компоненты в свойствах проекта на закладке Linker необходимо выбирать опцию Generate Object files. Это свойство требуется для правильной работы страницы свойств (если это свойство не установлено, 1С:Предприятие после завершения работы может остаться работать в фоновом режиме).

При необходимости добавить в проект Активный документ:

1. Выбрать из меню File | New...
2. В закладке ActiveX выбрать ActiveForm.

Файл AddInVid создан с использованием входящего в поставку шаблона.

Шаблоны

Шаблоны практически аналогичны примерам SAMPLE за исключением функциональности: оставлен только скелетный код и все необходимые детали реализаций компонент для удобства использования при разработке других компонент. Шаблоны работают согласно настоящему описанию и могут быть использованы при разработке компонент "с нуля". Расположение файлов шаблонов на дискете см. Структура каталогов.

Рекомендации по построению компоненты

При построении компоненты желательно следовать следующим рекомендациям:

• компонента должна быть InProc COM—сервером (DLL, OCX) для ускорения работы. Построение EXE — сервера проще в стадии отладки, но скорость и устойчивость работы ниже, чем у InProc сервера;
• если в разработке используется шаблон компоненты, то необходимо:
• изменять имена, использованные в шаблоне (например, "AddInExtension");
• не наследовать классы от классов шаблона, а переписывать их;
• если в компоненте используется флаг включения компоненты, то по умолчанию компоненту следует выключать. Тогда компоненту легко отключить — достаточно стереть соответствующие записи в регистрационной базе данных системы (Registry);
• использовать только латиницу в названиях ProgID объектов.
• некоторые комбинации стилей окна могут быть несовместимы со средой 1С:Предприятие в силу ограничений Windows, поэтому при создании нестандартных окон необходимо тщательно тестировать их работу.

Глава 3. Введение в COM

Эта часть описывает основы COM и не является полным руководством по COM (ActiveX) и OLE технологиям. Для более глубокого изучения COM Вам следует обратиться к документации по COM и OLE.

Интерфейсы в COM

Центральным понятием в COM является понятие "интерфейс". Под интерфейсом понимается некоторое множество функций, организованное по определенному стандарту. Стандарт COM определяет таблицу функций интерфейса, называемую vtable. Эта таблица имеет фиксированную структуру и включает в себя указатели на функции данного интерфейса, что позволяет вызывать функции интерфейса по ссылке на интерфейс.

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

• AddRef — увеличивает счетчик ссылок объекта на 1;
• Release — уменьшает счетчик ссылок объекта на 1;
• QueryInterface — запрашивает интерфейс у COM-объекта.

В COM используется большое количество различных интерфейсов, построенных по единому стандарту COM, с различными наборами функций. Каждому интерфейсу присвоен уникальный номер: GUID.

GUID (Globally Unique Identifier) — 16-байтное число, создаваемое по специальному алгоритму. Этот алгоритм гарантирует уникальность числа "в пространстве Вселенной за время ее существования". Обычно это число записывается в виде
{89ABCDEF-1234-5678-9ABC-DEF012345678}.

Уникальный номер интерфейса называют IID (Interface Identifier) для отличия от других идентификаторов.

Объекты COM

Каждый COM—объект реализует один или несколько интерфейсов для выполнения различных задач и обязательный интерфейс IUnknown. Для создания объекта и получения указателя на один из интерфейсов используются функции Win32: CoCreateInstanceEx, CoCreateInstanceFromFile, CoGetClassObject и т.д. Одним из параметров функций является CLSID (Class Identifier) - это GUID, используемый при создании объекта. При создании объекта система использует информацию, хранящуюся в регистрационной базе данных системы (Registry).

Эта информация организована следующим образом:

• под ключом HKEY_CLASSES_ROOT лежит ключ, описывающий ProgID (Programmatic Identifier) объекта. ProgID — это текстовая строка, например: Excel.Application. Под ключом ProgID находится ключ CLSID, значением которого является GUID объекта. Таким образом, ProgID — это строка, представляющая удобную для восприятия ссылку на CLSID. Преобразование ProgID в CLSID выполняется Win32 функцией CLSIDFromProgID;
• под ключом HKEY_CLASSES_ROOT\CLSID находится ключ с именем CLSID для объекта. Под этим ключом находятся ключи, описывающие создание объекта: InProcServer32 — объект создается из DLL, LocalServer32 — объект создается из приложения, ProgID— обратная ссылка на ProgID и т.д.

Другим параметром функций при создании объекта передается
IID — идентификатор необходимого интерфейса. Функции, создающие объект, возвращают указатель на запрошенный интерфейс. Указатель на этот интерфейс может быть использован для получения другого интерфейса вызовом QueryInterface.

Каждый объект поддерживает счетчик ссылок других объектов на себя. Этот счетчик изменяется вызовами AddRef и Release интерфейсов объекта. Если после очередного вызова Release счетчик ссылок достигает нуля, это означает, что ссылки на данный объект отсутствуют и он уничтожается. QueryInterface увеличивает счетчик ссылок автоматически.

OLE Automation

Технология OLE Automation основывается на одном из наиболее известных и часто используемых в OLE интерфейсов — интерфейсе IDispatch. Этот интерфейс позволяет читать и писать свойства OLE Automation объекта и вызывать его функции с произвольным списком параметров. OLE Automation объектом можно назвать любой OLE объект, реализующий IDispatch. Для вызова функции объекта необходимо определить ее номер, затем вызывать метод Invoke интерфейса IDispatch и ей в качестве параметров передать номер вызываемой функции и массив ее параметров. Следует отличать функции OLE Automation объекта от функций интерфейсов (в частности, IDispatch) — интерфейс имеет жесткий неизменяемый список функций, а OLE Automation объект — произвольных список свойств и функций. Наиболее широко этот интерфейс используется в языке Visual Basic, где определен тип Object — в действительности это указатель на IDispatch.

В IDispatch входят следующие функции:

• GetTypeInfo, GetTypeInfoCount — функции для работы с информацией о типах (за дополнительной информацией об этих функциях и работе с типами обращайтесь к рекомендованной литературе);
• GetIDsOfNames — позволяет получить номер функции объекта по ее имени;
• Invoke — вызов необходимой функции по номеру.

При передаче параметров функции используется структура VARIANT. Эта структура представляет собой объединение различных типов данных и может содержать практически любое значение, используемое на практике.