1С-Предприятие. Документация | Технология создания внешних компонент

Внешняя компонента -программный модуль, расширяющий функциональность 1С:Предприятия. Внешние компоненты являются OLE серверами и вследствие этого могут быть написаны с использованием произвольных инструментов разработки программ, поддерживающих создание OLE объектов.
Возможности внешней компоненты:
  • расширение встроенного языка 1С:Предприятия (добавление новых агрегатных объектов);
  • добавление страницы свойств в параметры 1С:Предприятия;
  • сохранение параметров внешней компоненты через механизмы сохранения параметров 1С:Предприятия;
  • создание дополнительных окон в окне 1С:Предприятия (версия 2.0);
  • доступ к функциям 1С:Предприятия через OLE Automation (версия 2.0);
  • вызов процедуры обработки событий, контролируемых внешней компонентой;
  • доступ к строке состояния 1С:Предприятия.
Внешние компоненты используются в 1С:Предприятии для расширения его возможностей при выполнении различных задач. В частности, в число таких задач входит вызов функции из библиотеки (DLL), использование различного торгового оборудования, нестандартное отображение данных и т.д. Все
внешние компоненты следуют единому стандарту, поэтому при работе можно использовать как уже существующие компоненты, так и разрабатывать новые. В данную поставку входят шаблоны и примеры для различных сред программирования, которые позволяют упростить разработку новых компонент.
Средства встроенного языка 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С:Предприятие и происходит только при отсутствии других выполняемых системой операций (проведении документов, построении отчетов и т.д.).
Разработка внешней компоненты Создание OLE-объекта внешней компоненты При загрузке внешней компоненты функцией ЗагрузитьВнешнююКомпоненту 1С:Предприятие определяет ProgID OLE-объекта компоненты следующим образом:
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.
Объект внешней компоненты обязан реализовать этот интерфейс. При его отсутствии компонента не будет загружена.
Страница свойств Для добавления страницы свойств объекта компоненты в диалог настройки параметров 1С:Предприятия используются интерфейсы IPropertyPage или ISpecifyPropertyPages (объект может реализовать любой из этих интерфейсов). Каждый объект может добавитьодну страницу свойств. Странице свойств при инициализации передается указатель на интерфейс Iunknown соответствующего объекта внешней компоненты. Интерфейсы  IPropertyPage, ISupplyPropertyPages являются стандартными для OLE, поэтому их описание Вы сможете найти в документации на OLE и книгах, приводимых в списке
литературы.
Расширение встроенного языка Для расширения встроенного языка компонента должна реализовать интерфейс ILanguageExtender . Этот интерфейс унаследован от IUnknown и предназначен для расширения встроенного языка 1С:Предприятия. Для использования этого расширения необходимо вызвать функцию СоздатьОбъект, передав ей строку вида AddIn._ИмяРасширения_, где _ИмяРасширения_ возвращается методом этого интерфейса  Затем можно использовать созданный объект, вызывая его методы и свойства.
В отличие от предыдущей версии версия 2.0 позволяет создавать несколько объектов одного типа AddIn._ИмяРасширения_, однако компонента должна явно указать поддержку версии 2.0 в методе GetInfo.  В противном случае допускается создание только одного объекта.
HRESULT RegisterExtensionAs(BSTR *pExtensionName): Параметры:
pExtensionName Наименование расширения встроенного языка 1С:Предприятия.
Возвращаемое значение:
S_OK
Описание:
В переменную pExtensionName помещается наименование расширения. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с OLEстроками (например, SysAllocString. 1С:Предприятие освобо ж дает эту память вызовом SysFreeString).
Свойства расширения
Первое свойство имеет порядковый номер 0.
HRESULT GetNProps(long *plProps) Параметры:
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.
HRESULT GetNMethods(long *plMethods) Получить количество методов расширения
Параметры:
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) .
HRESULT GetNParams(long lMethodNum, long *plMethParams) Получить количество параметров метода.
Параметры:
lMethodNum Порядковый номер метода
plMethParams Указатель на переменную, содержащую при возврате количество параметров
метода
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - метод с номером  в данном расширении отсутствует
Описание:
В переменную plMethParams помещается количество параметров метода с порядковым номером lMethodNum ; если свойство с таким номером отсутствует или не имеет параметров, в помещается 0. Память для переменной выделяется 1С:Предприятием .
HRESULT GetParamDefValue(long lMethodNum, long lParamNum,VARIANT *pvParamDefVal) Получить значение параметра метода по умолчанию.
Параметры:
lMethodNum Порядковый номер метода.
lParamNum Порядковый номер параметра.
pvParamDefVal Указатель на структуру VARIANT, содержащую при возврате значение параметра по умолчанию.
Возвращаемое значение:
S_OK - операция завершена успешно (вне зависимости от наличия у параметра значения по умолчанию)
S_FALSE - метод или параметр метода отсутствует
Описание:
В переменную pvParamDefVal помещается значение по умолчанию параметра lParamNum метода с порядковым номером lMethodNum . В pvParamDefVal помещается тип VT_EMPTY, если метод с таким номером отсутствует, не имеет параметра с номером или параметр не имеет значения по умолчанию. Память для переменной выделяется 1С:Предприятием .
HRESULT HasRetVal(long lMethodNum,BOOL *pboolHasRetVal) Получить флаг наличия возвращаемого значения.
Параметры:
lMethodNum Порядковый номер метода.
pboolHasRetVal Указатель на переменную, содержащую при возврате флаг наличия возвращаемого значения.
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - метод отсутствует
Описание:
В переменную pboolHasRetVal помещается флаг наличия возвращаемого значения у метода с порядковым номером lMethodNum : TRUE для методов с возвращаемым значением и FALSE в противном случае. Память для переменной выделяется 1С:Предприятием .
HRESULT CallAsProc(long lMethodNum, SAFEARRAY **pVars) Вызов метода без возвращаемого значения (процедуры).
Параметры:
lMethodNum Порядковый номер метода.
pVars Двойной указатель на массив структур VARIANT, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.
Возвращаемое значение:
S_OK - соответствующий метод вызван, ошибок не произошло.
E_FAIL - соответствующий метод вызван, произошла ошибка времени исполнения (runtime error). Исполнение модуля прекращается.
S_FALSE - отсутствует метод, соответствующий переданному lMethodNum.
Описание:
Выполняется метод с порядковым номером lMethodNum . Если метод возвращает E_FAIL, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров выделяется 1С:Предприятием.
HRESULT CallAsFunc(long lMethodNum, VARIANT *pRetValue, SAFEARRAY**pVars) Вызов метода с возвращаемым значением (функции).
Параметры:
lMethodNum Порядковый номер метода.
pRetValue Указатель на структуру VARIANT, при возврате содержащую возвращаемое значение.
pVars Двойной указатель на массив структур VARIANT, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.
     
Возвращаемое значение:
S_OK - соответствующий метод вызван, ошибок не произошло.
E_FAIL - соответствующий метод вызван, произошла ошибка времени исполнения (runtime error). Исполнение модуля прекращается.
S_FALSE - отсутствует метод, соответствующий переданному lMethodNum.
Описание:
Выполняется метод с порядковым номером lMethodNum . Если метод возвращает E_FAIL, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров и возвращаемого значения выделяется 1С:Предприятием.
Использование типа OLE VARIANT при обмене данными Вызов функции компоненты неопределенное значение соответствует VT_EMPTY;
целочисленное значение соответствует VT_I4 и помещается в lVal;
дробное значение соответствует VT_R8 и помещается в dblVal;
Следует учесть, что внутреннее представление может иметь точность,превосходящую точность типа double (около 15 цифр после запятой), поэтому при конвертации может происходить потеря точности.
значение даты соответствует VT_DATE и помещается в date;
строковое значение соответствует VT_BSTR и помещается в bstrVal;
значения перечисление, субконто, документ, алгоритм, календарь, счет соответствуют VT_DISPATCH и помещаются в pdispVal. Указатель на Idispatch освобождается непосредственно после возврата из функции компоненты вызовом Release. Для указателя на IDispatch выполняется AddRe f . При использовании объектов 1С:Предприятия в компоненте необходимо определить DISPIDы методов объекта (вызвав GetIDsOfNames) и затем вызвать Invoke;
значение OLE объекта соответствует VT_DISPATCH и помещается в pdispVal. Для указателя на IDispatch выполняется AddRef.
При конвертации OLE объекта в IDispatch проверяются ситуации взаимного вызова 1С:Предприятие-Компонента-1С:Предприятие и Компонента-1С:Предприятие-Компонента и все необходимые операции проводятся корректно.
Возвращение значений из компоненты VT_EMPTY соответствует неопределенному значению. При передаче в качестве параметра метода подставляется значение параметра по умолчанию;
значения типа VT_I2, VT_I4, VT_BOOL, VT_ERROR, VT_UI1 соответствуют целочисленному значению и находятся в lVa l;
значения типа VT_R4, VT_R8, VT_CY соответствуют дробному значению и находятся в dblVal;
значение типа VT_DATE соответствует значению даты и находится в date;
значение типа VT_BSTR соответствует строковому значению и находится в bstrVal;
значение типа VT_DISPATCH соответствует значению OLE объекта и находится в pdispVal.
Типы VT_DECIMAL, VT_VARIANT, VT_UNKNOWN и VT_ARRAY не поддерживаются.
При конвертации IDispatch в OLE объект проверяются ситуации взаимного вызова 1С:Предприятие-Компонента-1С:Предприятие и Компонента-1С:Предприятие-Компонента и все необходимые операции проводятся корректно.
Вызов метода объекта 1С:Предприятия из компоненты Для вызова метода объекта необходимо вызвать метод Invoke полученного ранее интерфейса IDispatch, передав ему все необходимые параметры, в том числе номер (DISPID) вызываемого метода объекта. Этот номер можно получить из метода GetIDsOfNames интерфейса IDispatch, передав ему название метода объекта.
Соответствие между параметрами метода объекта и массивом структур VARIANT прямое: первому параметру соответствует структура с индексом 0, второму параметру - структура с индексом 1 и т.д. При передаче параметров метода объекта следует учесть, что необходимо передавать значения всех параметров, включая значения параметров, подставляемые по умолчанию. Для подстановки значений по умолчанию достаточно присвоить тип VT_EMPTY соответствующей структуре VARIANT.
OLE интерфейсы 1C:Предприятия Все нижеприведенные интерфейсы могут быть получены вызовом QueryInterface переданного при инициализации объекта указателя на IDispatch. Их идентификаторы (IID) Вы можете найти в шаблонах, включенных в данную поставку.
Сохранение параметров объекта компоненты Для сохранения параметров объект внешней компоненты может использовать механизмы сохранения 1С:Предприятия через интерфейс IPropertyProfile. 
Этот интерфейс унаследован от интерфейса IPropertyBag , стандартного для OLE, и отличается единственным методом:
HRESULT RegisterProfileAs(BSTR bstrProfileName) Регистрация списка параметров компоненты.
Параметры:
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 .
Информационные сообщения о работе объекта Для сообщения пользователю информации о своей работе объект может использовать интерфейс IErrorLog, стандартный для OLE (описание метода AddError интерфейса IErrorLog приводится здесь исключительно для удобства работы). Возникающие сообщения обработываются как в течение работы
программы (при асинхронном помещении их в очередь), так и в следующих случаях: при возврате из метода инициализации Init ( см. стр. * ) и при возврате из метода расширения . Все сообщения помещаются в очередь и обрабатываются по порядку появления. Количество запоминаемых сообщений не ограничено.
HRESULT AddError(BSTR pszPropName, LPEXCEPINFO pExcepInfo) Добавить сообщение.
Параметры:
pszPropName В настоящей реализации параметр  pszPropName игнорируется.
pExcepInfo Указатель на структуру 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 - объект может использовать интерфейс IAsyncEvent для создания внешнего события в 1С:Предприятии. Интерфейс IAsyncEvent унаследован от IUnknown.
Все события помещаются в очередь и обрабатываются по порядку появления. Количество запоминаемых событий ограничено длиной очереди. При инициализации длина очереди устанавливается равной 1 и может быть изменена вызовами GetEventBufferDepth и SetEventBufferDepth .. Для каждого объекта
внешней компоненты поддерживается своя очередь событий. Обработка внешнего события производится процедурой ОбработкаВнешнегоСобытия.
HRESULT SetEventBufferDepth(long lDepth) Установить размер очереди событий.
Параметры:
lDepth Длина очереди сообщений.
Возвращаемое значение:
S_OK - размер очереди установлен успешно
E_FAIL - при установке размера очереди произошла ошибка
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Устанавливает размер очереди событий для данного объекта. Если текущее
количество событий в очереди больше устанавливаемой длины, последние
события обрезаются.
HRESULT GetEventBufferDepth(long *plDepth) Получить размер очереди событий.
Параметры:
plDepth Указатель на переменную, содержащую при возврате длину очереди сообщений.
Возвращаемое значение:
S_OK - размер очереди возвращен успешно
E_FAIL - при получении размера очереди произошла ошибка
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
В переменную plDepth помещается размер очереди событий для данного объекта.
HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData) Поместить событие в очередь.
Параметры:
BstrWho строка с наименованием источника сообщения.
BstrWhat строка с наименованием сообщения.
BstrData строка c параметрами сообщения.
Возвращаемое значение:
S_OK - событие помещено в очередь
E_FAIL - очередь переполнена или неизвестная ошибка
E_OUTOFMEMORY - отсутствие памяти
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Помещает событие в очередь, записывая источник события, наименование и параметры события. При обработке события эти данные передаются процедуре ОбработкаВнешнегоСобытия. При вызове метода ExternalEvent дальнейшая обработка события происходит следующим образом: событие записывается в очередь событий (если очередь полностью занята, событие теряется), затем при отсутствии системных событий из очереди берется первое событие (если очередь не пуста) и вызывается соответствующая функция ОбработкаВнешнегоСобытия. Этот процесс повторяется для всех объектов внешних компонент. Таким образом, обработка внешних событий синхронизируется с обработкой системных событий.
HRESULT CleanBuffer() Очищает очередь событий.
Параметры:
Отсутствуют
Возвращаемое значение:
S_OK - очередь успешно очищена
E_FAIL - при очищении очереди произошла ошибка
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Очищает очередь событий, удаляя все присутствующие в очереди события.
Работа с строкой состояния Для информирования пользователя о своем состоянии объект компоненты может использовать интерфейс IStatusLine. При вызове метода SetStatusLine переданный текст немедленно отображается в строке состояния. При вызове метода ResetStatusLine в строке состояния отображается  стандартный текст.
HRESULT SetStatusLine(BSTR bstrStatusText) Установить текст строки состояния.
Параметры:
bstrStatusText Текст строки состояния.
Возвращаемое значение:
S_OK - текст отображен в строке состояния
E_FAIL - неизвестная ошибка
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Устанавливает текст строки состояния.
HRESULT ResetStatusLine() Установить текст строки состояния.
Параметры:
отсутствует
Возвращаемое значение:
S_OK -строка состояния успешно переинициализирована
E_FAIL - неизвестная ошибка
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Инициализирует строку состояния.
Создание окон в среде 1С:Предприятия Версия технологии: 2.0 и выше
Внешние компоненты могут создавать свои окна для отображения различной информации, используя интерфейс IExtWndsSupport. Компонента может создавать три типа окон: модальные диалоги, немодальные диалоги и формы.
Модальные диалоги Модальные диалоги создаются самой компонентой, но при их создании необходимо в качестве родительского окна указать окно, возвращаемое методом GetAppMainFrame для того, чтобы диалог не воспринимался операционной системой как отдельная задача с кнопкой на полосе задач. Работа системы 1С:Предприятие приостанавливается до завершения работы с диалогом.
Немодальные диалоги Немодальные диалоги также создаются самой компонентой, но при их создании необходимо в качестве родительского окна указать окно, возвращаемое методом GetAppMDIFrame для того, чтобы диалог не воспринимался операционной системой как отдельная задача с кнопкой на полосе задач. Диалог не останавливает работу 1С:Предприятия и по сути аналогичен формам 1С:Предприятия. Однако следует учесть, что созданный диалог не входит в список открытых окон и не появляется на панели окон, поэтому использование таких диалогов не рекомендуется (вместо них можно использовать формы самого 1С:Предприятия или формы, созданные внешней компонентой).
Формы Формы создаются функцией CreateAddInWindow и аналогичны формам, созданным в 1С:Предприятии. При создании  окна внешняя компонента передает в качестве одного из параметров ProgID OLE-объекта, поддерживающего некоторый предопределенный набор интерфейсов, описанный в технологии Активных документов (Active Documents, см. документацию по OLE). Этот объект отображается в окне 1С:Предприятия и может управляться внешней компонентой через возвращаемый интерфейс IDispatch.
От объекта, отображаемого в окне 1С:Предприятия, не требуется следование технологии внешних компонент, необходимо лишь следование стандарту на Активные документы.
HRESULT GetAppMainFrame(HWND *pHWnd) Получить основное окно 1С:Предприятия.
Параметры:
pHWnd указатель на дескриптор окна
Возвращаемое значение:
S_OK
Описание:
Возвращает дескриптор основного окна 1С:Предприятия.
HRESULT GetAppMDIFrame(HWND *pHWnd) Получить окно 1С:Предприятия, являющееся родительским для форм 1С:Предприятия.
Параметры:
pHWnd указатель на дескриптор окна
Возвращаемое значение:
S_OK
Описание:
Возвращает дескриптор окна 1С:Предприятия, содержащего формы 1С:Предприятия.
HRESULT CreateAddInWindow(BSTR bstrProgID, BSTR bstrTitle, long lStyles,long lExStyles, RECT *rctSize, long lFlags, HWND *pHwnd, IDispatch   **pDisp) Создать окно 1С:Предприятия.
Параметры:
bstrProgID ProgID OLE-объекта, являющегося Активным документом
bstrWindowName Заголовок окна
lStyles Стили окна
lExStyles Дополнительные стили окна
rctSize Размеры окна
lFlags Дополнительные флаги
pHwnd Указатель на дескриптор окна
pDisp Указатель на интерфейс Idispatch созданного Активного документа.
Возвращаемое значение:
S _OK -окно успешно создано
E_FAIL -ошибка при создании окна
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Создает окно 1С:Предприятия с объектом bstrProgID . Окно имеет заголовок bstrWindowName и стили lStyles и lExStyles . При передаче 0 в качестве стилей используются стили окна по умолчанию. Размеры окна указываются следующим образом: верхний левый угол rctSize обозначает верхний левый
угол создаваемого окна в координатах экрана, ширина и высота rctSize соответствуют ширине и высотеклиентской части создаваемого окна (т.е. той части, где отображается Активный документ). Параметр lFlags  в настоящее время не используется и должен быть равен 0. В параметрах  pHwnd и pDisp возвращаются соответственно дескриптор созданного окна и интерфейс IDispatch объекта bstrProgID. Для указателя pDisp необходимо вызвать Release.
Доступ к 1С:Предприятию через механизм OLE Automation Версия технологии: 2.0 и выше
Переданный в методе Init указатель на IDispatch позволяет получить доступ
к 1С:Предприятию через механизм OLE Automation. Из полученного указателя
можно получить свойство AppDispatch, доступное только для чтения. Это
свойство содержит указатель на IDispatch 1C:Предприятия (не путайте с
переданным в Init). При получении указателя его необходимо освободить
вызовом Release. Visual Basic и Borland Delphi позволяют делать это
автоматически.
Свойство AppDispatch становится доступно только после полной инициализации всей системы 1С:Предприятие, поэтому в момент загрузки внешней компоненты и вызова метода Init это свойство недоступно.
Доступ к методам интерфейсов 1С:Предприятия через OLE Automation Visual Basic имеет ограниченные возможности по работе с различными интерфейсами. Наиболее естественным механизмом для Visual Basic является работа с OLE Automation, для этого в VB используется тип Object, который представляет собой указатель на IDispatch. Поэтому  1С:Предприятие предоставляет возможность использовать механизм OLE Automation, передавая указатель на IDispatch в методе Init и обеспечивая вызовы методов вышеперечисленных интерфейсов через OLE Automation.
Методы, доступные через OLE Automation:
RegisterProfileAs (ИмяСпискаПараметров)
Read (ИмяПеременной,СсылкаНаVARIANT)
Write (ИмяПеременной,СсылкаНаVARIANT)
SetEventBufferDepth (ДлинаОчередиСобытий)
GetEventBufferDepth (СсылкаНаДлинуОчереди)
ClearEventBuffer ()
ExternalEvent(СтрокаИсточникСобытия,СтрокаНаименованиеСобытия,СтрокаПараметрыСобытия)
AddError(КодСообщения,СтрокаИсточникСообщения,СтрокаОписаниеСообщения,КодОшибки)
SetStatusLine (СтрокаСостояния)
ResetStatusLine ()
Версия 2.0 и выше:
свойство AppDispatch
GetAppMainFrame (Указатель на дескриптор окна)
GetAppMDIFrame (Указатель на дескриптор окна)
CreateAddInWindow (ProgID, Заголовок окна, Стили окна, Доп. стили окна, Координата верхнего левого угла окна по горизонтали, Координата верхнего левого угла окна по вертикали, Ширина окна, Высота окна, Доп. флаги (всегда 0), Указатель на дескриптор окна,  Указатель на интерфейс IDispatch)

Введение в OLE

В стандарте COM определен один интерфейс, называемый IUnknown, от которого наследуются все остальные OLE интерфейсы (т.е. все интерфейсы содержат функции IUnknown). В IUnknown входят три функции:
AddRef - увеличивает счетчик ссылок объекта на 1 (см.стр. * );
Release - уменьшает счетчик ссылок объекта на 1 (см.стр. * );
QueryInterface - запрашивает интерфейс у OLE объекта.
В OLE используется большое количество различных интерфейсов, построенных по единому стандарту COM, с различными наборами функций. Каждому интерфейсу присвоен уникальный номер: GUID.
GUID (Globally Unique Id entifier) - 16-байтное число, создаваемое по специальному алгоритму. Этот алгоритм гарантирует уникальность числа в пространстве Вселенной за время ее существования. Обычно это число     записывается в виде   {89ABCDEF-1234- 5678-9ABC-DEF012345678}. 
Уникальный номер интерфейса называют IID (Interface Id entifier) для отличения от других идентификаторов.
Объекты OLE Каждый OLE-объект реализует один или несколько интерфейсов для выполнения различных задач и обязательный интерфейс IUnknown. Для создания объекта и получения указателя на один из интерфейсов используются функции Win32: CoCreateInstanceEx, CoCreateInstanceFromFile, CoGetClassObject и т.д.
Одним из параметров функций является CLSID (Class Id entifier) - это GUID, используемый при создании объекта. При создании объекта система использует информацию, хранящуюся в регистрационной базе данных системы (Registry).
Это текстовая строка, например: 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. Эта структура представляет собой объединение различных типов данных и может содержать практически любое значение, используемое на практике.
    Active Documents Этот стандарт позволяет разрабатывать приложения, предназначенные для работы с документами разных видов. Активные документы составляют  с главным окном приложения общее меню и систему панелей инструментов, поэтому их можно интегрировать в общем окне. Примером приложения, использующего Активные документы, является Microsoft Binder из состава Microsoft Office. Для создания Активных документов в различных средах программирования чаще всего используются Мастера (Wizards), так как структура Активного документа достаточно сложна и его создание с нуля затруднительно.
    Литература
    • Kraig Brockschmidt Inside OLE (2nd edition)
    • Дэвид Чеппел Технологии ActiveX и OLE
    • Дейл Роджерсон Основы COM
    • Лоуренс Харрис Освой самостоятельно программирование OLE за 21 день
    Также можно рекомендовать различные книги по использованным в данной методике средствам программирования (например, серии ... для чайников или Microsoft Press Running ...), так как в них часто приводится необходимая информация, сопровождаемая практическими примерами.
    

        Бухгалтерия: Автоматизация - Система 1С