| 
|
1С-Предприятие. Документация | Технология создания внешних компонент
Внешняя компонента -программный модуль, расширяющий функциональность 1С:Предприятия. Внешние компоненты являются OLE серверами и вследствие этого могут быть написаны с использованием произвольных инструментов разработки программ, поддерживающих создание OLE объектов.Возможности внешней компоненты:
- расширение встроенного языка 1С:Предприятия (добавление новых агрегатных объектов);
- добавление страницы свойств в параметры 1С:Предприятия;
- сохранение параметров внешней компоненты через механизмы сохранения параметров 1С:Предприятия;
- создание дополнительных окон в окне 1С:Предприятия (версия 2.0);
- доступ к функциям 1С:Предприятия через OLE Automation (версия 2.0);
- вызов процедуры обработки событий, контролируемых внешней компонентой;
- доступ к строке состояния 1С:Предприятия.
внешние компоненты следуют единому стандарту, поэтому при работе можно использовать как уже существующие компоненты, так и разрабатывать новые. В данную поставку входят шаблоны и примеры для различных сред программирования, которые позволяют упростить разработку новых компонент.
Средства встроенного языка 1С:Предприятия, предназначенные для работы с внешними компонентами. ЗагрузитьВнешнююКомпоненту Загружает внешнюю компоненту, создает соответствующие OLE объекты и подключает их к 1С:Предприятию .
Синтаксис:
ЗагрузитьВнешнююКомпоненту ( ИмяФайлаКомпоненты)
Англоязычный синоним:
LoadAddIn
Параметры:
| ИмяФайлаКомпоненты |
имя файла внешней компоненты. ИмяФайлаКомпоненты
иметь вид Имя.Расширение и не должно содержатьпуть. Файл
компоненты ищется последовательно в каталоге пользователя, в каталоге
информационной базы, и в каталоге c исполняемым файлом 1С:Предприятия.
|
0 - при загрузке компоненты произошла ошибка
1 - компонента успешно загружена
Описание:
Внешние компоненты загружаются функцией встроенного языкаЗагрузитьВнешнююКомпоненту. Файл внешней компоненты должен быть динамически загружаемой библиотекой (например, DLL или OCX), то есть работать как InProc сервер. При загрузке внешней компоненты 1С:Предприятие вызывает функцию, если она экспортирована из внешней компоненты. Это позволяет просто переносить компоненты между компьютерами без дополнительной регистрации их как OLE серверов. При возникновении ошибок при загрузке 1С:Предприятие выдает информацию об ошибке в окно сообщений.
О создании OLE объекта внешней компоненты при загрузке - см. Разработка внешней компоненты, стр. * .
ПодключитьВнешнююКомпоненту Создает OLE объекты внешней компоненты и подключает их к 1С:Предприятию.
Синтаксис:
ПодключитьВнешнююКомпоненту ( ИмяОбъектаКомпоненты)
Англоязычный синоним:
AttachAddIn
Параметры:
| ИмяОбъектаКомпоненты |
ProgID (Programmatic Id
entifier) объекта внешней компоненты. ИмяОбъектаКомпоненты должно
соответствовать информации, находящейся в регистрационной базе данных
системы (Registry). |
0 - при подключении компоненты произошла ошибка
1 - компонента успешно подключена
Описание:
Внешние компоненты подключаются функцией встроенного языка ПодключитьВнешнююКомпоненту . Внешняя компонента может быть как динамически загружаемой библиотекой (например, DLL или OCX), так и приложением. При возникновении ошибок при подключении 1С:Предприятие выдает информацию об ошибке в окно сообщений.
ОбработкаВнешнегоСобытия Предопределенная процедура встроенного языка. Вызывается при возникновении сообщения от внешней компоненты.
Синтаксис:
ОбработкаВнешнегоСобытия( Источник, Событие, Данные )
Англоязычный синоним:
ExternEventProcessing
Параметры:
| Источник |
строка
с наименованием источника сообщения. |
| Событие |
строка
с наименованием сообщения. |
| Данные |
строка
с параметрами сообщения. |
отсутствует
Описание:
Процедура ОбработкаВнешнегоСобытия - предопределенная процедура обработки сообщений от внешних компонент.
Процедура может быть описана в любом модуле системы 1С:Предприятие. При получении сообщения будет вызвана процедура ОбработкаВнешнегоСобытия, определенная в модуле активной на этот момент формы. Если в этом модуле процедура ОбработкаВнешнегоСобытия не определена, то будет вызвана процедура ОбработкаВнешнегоСобытия , определенная в глобальном модуле. Если в глобальном модуле процедура ОбработкаВнешнегоСобытия отсутствует, будет выдано сообщение об отсутствии процедуры ОбработкаВнешнегоСобытия . Процедура ОбработкаВнешнегоСобытия в глобальном модуле не ызывается,
если событие обработано в модуле активной формы.
|
Вызов
этой процедуры синхронизирован с обработкой сообщений системой 1С:Предприятие
и происходит только при отсутствии других выполняемых системой операций
(проведении документов, построении отчетов и т.д.). |
ProgID имеет вид Vendor.Component;
в качестве первой части (Vendor) используется строка AddIn;
в качестве второй части (Component) используется строка с ID 100 из таблицы строк компоненты. Cтрока может иметь вид Name1|Name2|...|NameN, и в этом случае будут созданы все объекты с ProgID вида AddIn.NameX. Если такая строка отсутствует, то используется имя файла внешней компоненты без расширения.
При использовании функции ПодключитьВнешнююКомпоненту ProgID OLE-объекта компоненты передается в качестве параметра функции и также может представляться строкой вида ProgID1| ProgID2|...|ProgIDX.
Инициализация и выгрузка компоненты Для инициализации и выгрузки компоненты используется интерфейс IInitDone. Этот интерфейс наследован от IUnknown и предназначен для инициализации объекта и завершения работы с объектом.
HRESULT Init(IDispatch *pBackConnection) Параметры:
| pBackConnection |
указатель
на интерфейс 1С:Предприятия. |
E_FAIL - при инициализации произошла ошибка
S_OK - инициализация прошла успешно
Описание:
При загрузке 1С:Предприятие инициализирует объект компоненты, вызывая метод Init и передавая указатель на IDispatch. Объект не должен вызывать Release этого интерфейса, но может сохранить этот указатель для дальнейшего использования. Все остальные интерфейсы 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) Параметры:
| pInfo |
Двойной
указатель на массив структур VARIANT . Память для массива выделяется 1С:Предприятием. |
S_OK - информация о компоненте возвращена
Описание:
1С:Предприятие вызывает этот метод для получения информации о компоненте. В текущей версии 2.0 компонентной технологии в элемент с индексом 0 необходимо записать версию поддерживаемой компонентной технологии в формате V_I4 - целого числа, при этом старший номер версии записывается в тысячные разряды, младший номер версии - в единицы. Например: версия 3.56 - число 3560. В настоящее время все объекты внешних компонент могут поддерживать версию 1.0 (соответствует числу 1000) или 2.0 (соответствует 2000). Память для pInfo выделяется 1С:Предприятием. Метод должен возвращать S_OK.
|
Объект
внешней компоненты обязан реализовать этот интерфейс. При его отсутствии
компонента не будет загружена. |
литературы.
Расширение встроенного языка Для расширения встроенного языка компонента должна реализовать интерфейс ILanguageExtender . Этот интерфейс унаследован от IUnknown и предназначен для расширения встроенного языка 1С:Предприятия. Для использования этого расширения необходимо вызвать функцию СоздатьОбъект, передав ей строку вида AddIn._ИмяРасширения_, где _ИмяРасширения_ возвращается методом этого интерфейса Затем можно использовать созданный объект, вызывая его методы и свойства.
|
В отличие от предыдущей версии версия 2.0
позволяет создавать несколько объектов одного типа AddIn._ИмяРасширения_,
однако компонента должна явно указать поддержку версии 2.0 в методе GetInfo.
В противном случае допускается создание только одного объекта. |
| pExtensionName |
Наименование
расширения встроенного языка 1С:Предприятия. |
S_OK
Описание:
В переменную pExtensionName помещается наименование расширения. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с OLEстроками (например, SysAllocString. 1С:Предприятие освобо ж дает эту память вызовом SysFreeString).
Свойства расширения
|
Первое
свойство имеет порядковый номер 0. |
|
plProps |
Указатель
на переменную, содержащую при возврате количество свойств расширения. |
S_OK
Описание:
Возвращает количество свойств данного расширения, 0 - при отсутствии свойств. Память для переменной plProps выделяется 1С:Предприятием.
HRESULT FindProp(BSTR pszPropName,long*plPropNum) Параметры:
| pszPropName |
Наименование
свойства. |
| plPropNum |
Указатель
на переменную, содержащую при возврате порядковый номер свойства. |
S_OK - операция завершена успешно
S_FALSE - свойство с именем pszPropName в данном расширении отсутствует
Описание:
Возвращает порядковый номер свойства с именем pszPropName; -1, если свойство не найдено. Память для переменной plPropNum выделяется 1С:Предприятием.
HRESULT GetPropName(long lPropNum,long lAliasNum,BSTR *pPropName) Получить имя свойства по порядковому номеру
Параметры:
| lPropNum |
Порядковый
номер свойства. |
| lAliasNum |
Язык
наименования: 0 - английское наименование; 1 - локальное наименование. |
| pPropName |
Указатель
на строку, содержащую при возврате наименование свойства. |
S_OK - операция завершена успешно
S_FALSE - свойство с номером lPropNum в данном расширении отсутствует
Описание:
В переменную pPropName помещается имя свойства с порядковым номером lPropNum ; если свойство с таким номером отсутствует, в pPropName помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с OLEстроками (например,
SysAllocString. 1С:Предприятие освобо ж дает эту память вызовом SysFreeString ) .
HRESULT GetPropVal(long lPropNum,VARIANT *pvPropVal) Получить значение свойства по его порядковому номеру.
Параметры:
| lPropNum |
Порядковый
номер свойства. |
| pvPropVal |
Указатель
на структуру VARIANT, содержащую при возврате значение свойства. |
S_OK - операция завершена успешно
S_FALSE - свойство с номером lPropNum в данном расширении отсутствует или недоступно для чтения.
Описание:
В переменную pvPropVal помещается значение свойства с порядковым номером lPropNum ; если свойство с таким номером отсутствует или недоступно для чтения, должен иметь тип VT_EMPTY.
HRESULT SetPropVal(long lPropNum, VARIANT *pvPropVal) Присвоить свойству новое значение.
Параметры:
| lPropNum |
Порядковый
номер свойства. |
| pvPropVal |
Структура
VARIANT, содержащая новое значение свойства. |
S_OK - операция завершена успешно
S_FALSE - свойство с номером lPropNum в данном расширении отсутствует или недоступно для записи.
Описание:
Переменная pvPropVal содержит значение свойства с порядковым номером lPropNum ; если свойство с таким номером отсутствует, недоступно для чтения или тип переданного pvPropVal не приводится к необходимому, метод должен возвратить S_FALSE.
HRESULT IsPropReadable(long lPropNum, BOOL *pboolPropReadable) Получить флаг доступности свойства для чтения.
Параметры:
| lPropNum |
Порядковый
номер свойства. |
| pboolPropReadable |
Указатель
на переменную, содержащую при возврате флаг возможности чтения свойства. |
S_OK - операция завершена успешно.
S_FALSE - свойство с номером lPropNum в данном расширении отсутствует.
Описание:
В переменную pboolPropReadable помещается флаг возможности чтения свойства с порядковым номером lPropNum : FALSE(0) - свойство недоступно для чтения, TRUE(1) - свойство допускает чтение. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.
HRESULT IsPropWritable(long lPropNum, BOOL *pboolPropWritable) Получить флаг доступности свойства для записи.
Параметры:
| lPropNum |
Порядковый
номер свойства. |
| pboolPropWritable |
Указатель
на переменную, содержащую при возврате флаг возможности записи свойства. |
S_OK - операция завершена успешно.
S_FALSE - свойство с номером в данном расширении отсутствует.
Описание:
В переменную pboolPropWritable помещается флаг возможности записи свойства с порядковым номером lPropNum : FALSE(0) - свойство недоступно для записи, TRUE(1) - свойство допускает запись. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.
Методы расширения
|
Первый метод имеет порядковый номер
0. Первый параметр метода имеет порядковый номер 0. |
Параметры:
| plMethods |
Указатель
на переменную, содержащую при возврате количество методов расширения языка. |
S_OK
Описание:
В переменную plMethods помещается количество методов данного расширения, 0 - при отсутствии методов.
HRESULT FindMethod(BSTR bstrMethodName,long *plMethNum) Найти порядковый номер метода по его имени.
Параметры:
| bstrMethodName | Имя
метода |
| plMethNum |
Указатель
на переменную, содержащую при возврате порядковый номер метода с именем
methodName. |
S_OK
Описание:
В переменную plMethNum помещается порядковый номер метода с именем bstrMethodName ; -1 - при отсутствии метода.
HRESULT GetMethodName(long lMethodNum, long lAliasNum,BSTR *pbstrMethName) Получить имя метода по его порядковому номеру.
Параметры:
| lMethodNum |
Порядковый
номер метода |
| lAliasNum |
Язык
имени метода: 0 - английское наименование; 1 - локальное наименование. |
| pbstrMethName |
Указатель
на строку, содержащую при возврате имя метода |
S_OK - операция завершена успешно
S_FALSE - метод с номером в данном расширении отсутствует
Описание:
В переменную помещается имя свойства с порядковым номером; если свойство с таким номером отсутствует, в помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с OLEстроками (например, SysAllocString. 1С:Предприятие освобо ждает эту память вызовом SysFreeString) .