Внешние компоненты

[Vlad]

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

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

[Vlad]

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

[Vlad]

Сохранение параметров объекта компоненты
Для сохранения параметров объект внешней компоненты может использовать механизмы сохранения 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 .

[Vlad]

Информационные сообщения о работе объекта
Для сообщения пользователю информации о своей работе объект может использовать интерфейс 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 -

ADDIN_E_ATTENTION -

ADDIN_E_IMPORTANT -

ADDIN_E_VERY_IMPORTANT -

ADDIN_E_INFO -

ADDIN_E_FAIL -

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

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

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

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

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

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

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

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

[Vlad]

Внешние события
При возникновении асинхронного события (например, считывания штрих-кода) объект может использовать интерфейс 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 - при очищении очереди произошла ошибка

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

Описание:

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

[Vlad]

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

HRESULT SetStatusLine(BSTR bstrStatusText)
Установить текст строки состояния.

Параметры:

bstrStatusText  Текст строки состояния.


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

S_OK - текст отображен в строке состояния

E_FAIL - неизвестная ошибка

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

Описание:

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

HRESULT ResetStatusLine()
Установить текст строки состояния.

Параметры:

отсутствует

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

S_OK -строка состояния успешно переинициализирована

E_FAIL - неизвестная ошибка

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

Описание:

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

[Vlad]

Создание окон в среде 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.

[Vlad]

Доступ к 1С:Предприятию через механизм OLE Automation
Версия технологии: 2.0 и выше

Переданный в методе Init указатель на IDispatch позволяет получить доступ

к 1С:Предприятию через механизм OLE Automation. Из полученного указателя

можно получить свойство AppDispatch, доступное только для чтения. Это

свойство содержит указатель на IDispatch 1C:Предприятия (не путайте с

переданным в Init). При получении указателя его необходимо освободить

вызовом Release. Visual Basic и Borland Delphi позволяют делать это

автоматически.

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

[Vlad]

Доступ к методам интерфейсов 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)