1С: Предприятие 5, 7, 0: Технология создания внешних компонент (Версия 0)

Введение

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

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

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

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

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

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

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

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

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

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

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

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

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

Во второй части разбираются примеры построения внешних компонент в различных средах разработки. Используются следующие программные продукты: 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С:Предприятия (добавление новых агрегатных объектов);
  
• 
  добавление страницы свойств в параметры 1С:Предприятия;
  
• 
  сохранение параметров внешней компоненты через механизмы сохранения параметров 1С:Предприятия;
  
• 
  создание дополнительных окон в окне 1С:Предприятия (версия 2.0, только для 1С:Предприятия 7.7);
  
• 
  доступ к функциям 1С:Предприятия через OLE Automation (версия 2.0);
  
• 
  вызов процедуры обработки событий, контролируемых внешней компонентой;
  
• 
  доступ к строке состояния 1С:Предприятия.
  

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

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

Синтаксис:

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

Параметры:

      Обязательный

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

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

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

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

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

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

Описание:

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

 

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

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

Синтаксис:

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

Параметры:

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

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

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

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

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

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

Описание:

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

 

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

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

Синтаксис:

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

Параметры:

Описание:

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

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

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

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

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

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

 

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

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

Синтаксис:

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

Параметры:

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

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

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

Описание:

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

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

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

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

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

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

Синтаксис:

HRESULT Init(IDispatch *pBackConnection)

Параметры:

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

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

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

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

Синтаксис:

HRESULT Done(void)

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

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

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

Синтаксис:

HRESULT GetInfo(SAFEARRAY **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.

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

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

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

Версия 2.0 позволяет создавать несколько объектов одного типа “AddIn.”, однако компонента должна явно указать поддержку версии 2.0 в методе GetInfo. В противном случае допускается создание только одного объекта.

Синтаксис:

HRESULT RegisterExtensionAs(BSTR *pExtensionName)

Параметры:

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

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

• 
  S_OK
  

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

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

 

GetNProps

Синтаксис:

HRESULT GetNProps(long *plProps)

Параметры:

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

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

• 
  S_OK
  

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

Синтаксис:

HRESULT FindProp(BSTR pszPropName,long*plPropNum)

Параметры:

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

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

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

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

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

Синтаксис:

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

Параметры:

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

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

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

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

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

Синтаксис:

HRESULT GetPropVal(long lPropNum,VARIANT *pvPropVal)

Параметры:

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

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

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

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

Синтаксис:

HRESULT SetPropVal(long lPropNum, VARIANT *pvPropVal)

Параметры:

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

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

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

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

Синтаксис:

HRESULT IsPropReadable(long lPropNum, BOOL *pboolPropReadable)

Параметры:

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

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

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

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

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

Синтаксис:

HRESULT IsPropWritable(long lPropNum, BOOL *pboolPropWritable)

Параметры:

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

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

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

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

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

GetNMethods

Синтаксис:

HRESULT GetNMethods(long *plMethods)

Параметры:

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

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

• 
  S_OK
  

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

Синтаксис:

HRESULT FindMethod(BSTR bstrMethodName,long *plMethNum)

Параметры:

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

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

• 
  S_OK
  

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

Синтаксис:

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

Параметры:

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

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

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

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

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

Синтаксис:

HRESULT GetNParams(long lMethodNum, long *plMethParams)

Параметры:

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

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

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

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

Синтаксис:

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

Параметры:

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

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

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

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

Синтаксис:

HRESULT HasRetVal(long lMethodNum,BOOL *pboolHasRetVal)

Параметры:

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

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

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

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

Синтаксис:

HRESULT CallAsProc(long lMethodNum, SAFEARRAY **pVars)

Параметры:

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

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

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

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

Синтаксис:

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

Параметры:

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

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

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

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

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

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

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

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

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

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

• 
  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.0);
  
• 
  значение типа VT_DISPATCH соответствует значению объекта и находится в pdispVal.
  

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

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

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

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

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

Синтаксис:

HRESULT RegisterProfileAs(BSTR bstrProfileName)

Параметры:

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

• 
  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.0 – в профиле, соответствующем сочетанию “компьютер – ИБ - пользователь”.

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

Синтаксис:

HRESULT AddError(BSTR pszPropName, LPEXCEPINFO pExcepInfo)

Параметры:

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

Тип: 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.0)

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

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

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

:(Код cообщения = ),

где , и см. выше.

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

Синтаксис:

HRESULT SetEventBufferDepth(long lDepth)

Параметры:

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

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

Описание:

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

GetEventBufferDepth

Синтаксис:

HRESULT GetEventBufferDepth(long *plDepth)

Параметры:

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

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

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

Описание:

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

ExternalEvent

Синтаксис:

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

Параметры:

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

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

Описание:

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

CleanBuffer

Синтаксис:

HRESULT CleanBuffer()

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

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

Описание:

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

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

Синтаксис:

HRESULT SetStatusLine(BSTR bstrStatusText)

Параметры:

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

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

Описание:

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

ResetStatusLine

Синтаксис:

HRESULT ResetStatusLine()

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

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

Описание:

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

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

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

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

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

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

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

GetAppMainFrame

Синтаксис:

HRESULT GetAppMainFrame(HWND *pHWnd)

Параметры:

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

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

• 
  S_OK
  

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

Синтаксис:

HRESULT GetAppMDIFrame(HWND *pHWnd)

Параметры:

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

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

• 
  S_OK
  

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

Синтаксис:

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

Параметры:

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

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

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

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

Описание:

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

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

Синтаксис:

HRESULT GetAppMainFrame(HWND *pHWnd)

Параметры:

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

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

• 
  S_OK
  

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

Синтаксис:

HRESULT GetAppMDIFrame(HWND *pHWnd)

Параметры:

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

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

• 
  S_OK
  

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

Синтаксис:

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

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

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

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

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

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

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

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

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

Read(,)

Write(,)

SetEventBufferDepth()

GetEventBufferDepth()

ClearEventBuffer()

ExternalEvent(,,)

AddError(,,,)

SetStatusLine()

ResetStatusLine()

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

GetAppMainFrame()

GetAppMDIFrame()

CreateAddInWindow(