Технология создания внешних компонент для "1С:Предприятие 8. Расширение для карманных компьютеров" позволяет расширить возможности "Расширения для карманных компьютеров" за счет использования внешних программ, реализующих те или иные возможности. Например, таким образом может быть организована работа с различным оборудованием, в частности, со сканерами штрих-кодов. При этом такие программы должны быть реализованы с соблюдением ряда требований, описанных ниже.
Встроенный язык "1С:Предприятие 8. Расширение для карманных компьютеров" включает методы и события для работы со внешними компонентами, описание которых приводится ниже.
ЗагрузитьВнешнююКомпоненту (LoadAddIn)
Метод глобального контекста. Загружает внешнюю компоненту, создает соответствующие COM-объекты и подключает их к платформе исполнения мобильных приложений.
Синтаксис:
ЗагрузитьВнешнююКомпоненту(<ИмяФайлаКомпоненты>)
Параметры:
<ИмяФайлаКомпоненты> Обязательный
Тип: строка. Имя файла внешней компоненты. <ИмяФайлаКомпоненты> должно иметь вид “Имя.Расширение”. Имя файла может содержать полный путь к нему. Если путь не указан, платформа исполнения мобильный приложений осуществляет поиск компоненты в следующей последовательности: каталог ИБ, каталог исполняемых файлов платформы, каталог ОС.
Возвращаемое значение:
Тип – число.
Код возврата от загрузки компоненты. 0 – означет нормальную загрузку, остальное – системные коды ошибки.
Описание:
Внешние компоненты загружаются функцией встроенного языка ЗагрузитьВнешнююКомпоненту. Файл внешней компоненты должен быть динамически загружаемой библиотекой (например, DLL или OCX), то есть работать как InProc сервер.
При загрузке внешней компоненты "1С:Предприятие 8. Расширение для карманных компьютеров" вызывает функцию DllRegisterServer, если она экспортирована из внешней компоненты. Это позволяет просто переносить компоненты между компьютерами без дополнительной регистрации их как COM-серверов. О создании COM-объекта внешней компоненты при загрузке - см. Разработка внешней компоненты.
ПодключитьВнешнююКомпоненту(AttachAddIn)
Создает COM-объекты внешней компоненты и подключает их к платформе исполнения мобильных приложений.
Синтаксис:
ПодключитьВнешнююКомпоненту(<ИмяОбъектаКомпоненты>)
Параметры:
<ИмяОбъектаКомпоненты> Обязательный
ProgID (Programmatic Identifier) объекта внешней компоненты. <ИмяОбъектаКомпоненты> должно соответствовать информации, находящейся в регистрационной базе данных системы (Registry).
Возвращаемое значение:
Тип – число.
Код возврата от загрузки компоненты. 0 – означет нормальную загрузку, остальное – системные коды ошибки.
Описание:
Внешние компоненты подключаются функцией встроенного языка ПодключитьВнешнююКомпоненту. Внешняя компонента может быть как динамически загружаемой библиотекой (например, DLL или OCX), так и приложением.
ОбработкаВнешнегоСобытия (ExternEventProcessing)
Предопределенная процедура встроенного языка. Вызывается при возникновении сообщения от внешней компоненты.
Синтаксис:
ОбработкаВнешнегоСобытия(<Источник>, <Событие>, <Данные>)
Параметры:
<Источник>
Тип: строка. Наименование источника сообщения.
<Событие>
Тип: строка. Наименование сообщения.
<Данные>
Тип: строка. Параметры сообщения.
Описание:
Процедура ОбработкаВнешнегоСобытия — предопределенная процедура обработки сообщений от внешних компонент.
Процедура может быть описана в модуле приложения. При получении сообщения будут вызваны обработчики внешнего события, определенные в модулях всех открытых на этот момент форм, включая цепочку всех открытых модально форм. После этого будет вызвана процедура ОбработкаВнешнегоСобытия, определенная в модуле приложения.
ВнешнееСобытие (ExternalEvent)
Процедура обработки внешнего события во встроенном языке. Вызывается при возникновении сообщения от внешней компоненты.
Синтаксис:
ВнешнееСобытие (<Источник>, <Событие>, <Данные>)
Параметры:
<Источник>
Тип: строка. Наименование источника сообщения.
<Событие>
Тип: строка. Наименование сообщения.
<Данные>
Тип: строка. Параметры сообщения.
Описание:
Процедура может быть описана в модуле любой формы. При получении сообщения от внешней компоненты будет вызвана процедура ВнешнееСобытие, определенная в модулях открытых на этот момент форм. После обработки внешнего события в формах будет вызвана предопределенная процедура ОбработкаВнешнегоСобытия, определенная в модуле приложения. Процедура ОбработкаВнешнегоСобытия в модуле приложения всегда вызывается последней.
При загрузке внешней компоненты функцией ЗагрузитьВнешнююКомпоненту "1С:Предприятие 8. Расширение для карманных компьютеров" определяет ProgID COM—объекта компоненты следующим образом:
При использовании функции ПодключитьВнешнююКомпоненту ProgID COM-объекта компоненты передается в качестве параметра функции и также может представляться строкой вида ProgID1| ProgID2|...|ProgIDX.
Инициализация и выгрузка компоненты
Для инициализации и выгрузки компоненты используется интерфейс IInitDone. Этот интерфейс наследован от IUnknown и предназначен для инициализации объекта и завершения работы с объектом.
Init
Синтаксис:
HRESULT Init(IDispatch *pBackConnection)
Параметры:
pBackConnection
Тип: IDispatch. Указатель на интерфейс платформы исполнения мобильных приложений.
Возвращаемое значение:
E_FAIL - при инициализации произошла ошибка
S_OK - инициализация прошла успешно
Описание:
При загрузке платформа инициализирует объект компоненты, вызывая метод Init и передавая указатель на IDispatch. Объект может сохранить этот указатель для дальнейшего использования. Все остальные интерфейсы объект может получить, вызвав метод QueryInterface переданного ему интерфейса IDispatch. Объект должен возвратить S_OK, если инициализация прошла успешно, и E_FAIL при возникновении ошибки.
Done
Синтаксис:
HRESULT Done(void)
Возвращаемое значение:
S_OK - объект завершил работу
Описание:
Платформа исполнения мобильных приложений вызывает этот метод при завершении работы с объектом компоненты. Объект должен возвратить S_OK. Этот метод вызывается независимо от результата инициализации объекта (метод Init).
GetInfo
Синтаксис:
HRESULT GetInfo(SAFEARRAY **pInfo)
Параметры:
PInfo
Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT. Память для массива выделяется платформой.
Возвращаемое значение:
S_OK - информация о компоненте возвращена
Описание:
Платформа вызывает этот метод для получения информации о компоненте. В текущей версии компонентной технологии в элемент с индексом 0 необходимо записать версию поддерживаемой компонентной технологии в формате V_I4 — целого числа, при этом старший номер версии записывается в тысячные разряды, младший номер версии — в единицы. Например: версия 3.56 — число 3560. В настоящее время все объекты внешних компонент могут поддерживать версию 1.0 (соответствует числу 1000). Память для pInfo выделяется платформой. Метод должен возвращать S_OK.
Объект внешней компоненты обязан реализовать этот интерфейс. При его отсутствии компонента не будет загружена.
Для расширения встроенного языка компонента должна реализовать интерфейс ILanguageExtender. Этот интерфейс унаследован от IUnknown и предназначен для расширения встроенного языка "1С:Предприятие 8. Расширение для карманных компьютеров". Для использования этого расширения необходимо вызвать функцию Новый, передав ей строку вида “AddIn.<ИмяРасширения>”, где <ИмяРасширения> возвращается методом этого интерфейса Затем можно использовать созданный объект, вызывая его методы и свойства.
--------------------------------------------------------------------------------
RegisterExtensionAs
Синтаксис:
HRESULT RegisterExtensionAs(BSTR *pExtensionName)
Параметры:
PExtensionName
Тип: BSTR*. Наименование расширения встроенного языка "1С:Предприятие 8. Расширение для карманных компьютеров".
Возвращаемое значение:
S_OK
Описание:
В переменную pExtensionName помещается наименование расширения (вторая часть имени объекта). Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. Платформа освобождает эту память вызовом SysFreeString).
--------------------------------------------------------------------------------
Первое свойство имеет порядковый номер 0.
--------------------------------------------------------------------------------
GetNProps
Синтаксис:
HRESULT GetNProps(long *plProps)
Параметры:
PlProps
Тип: long*. Указатель на переменную, содержащую при возврате количество свойств расширения.
Возвращаемое значение:
S_OK
Описание:
Возвращает количество свойств данного расширения, 0 – при отсутствии свойств. Память для переменной plProps выделяется платформой.
FindProp
Синтаксис:
HRESULT FindProp(BSTR pszPropName,long*plPropNum)
Параметры:
pszPropName
Тип: BSTR. Наименование свойства.
plPropNum
Тип: long*. Указатель на переменную, содержащую при возврате порядковый номер свойства.
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - свойство с именем pszPropName в данном расширении отсутствует
Описание:
Возвращает порядковый номер свойства с именем pszPropName; -1, если свойство не найдено. Память для переменной plPropNum выделяется платформой.
GetPropName
Синтаксис:
HRESULT GetPropName(long lPropNum,long lAliasNum,BSTR *pPropName)
Параметры:
LPropNum
Тип: long. Порядковый номер свойства.
LAliasNum
Тип: long. Язык наименования:
0 — английское наименование;
1 — локальное наименование.
PPropName
Тип: BSTR*. Указатель на строку, содержащую при возврате наименование свойства.
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - свойство с номером lPropNum в данном расширении отсутствует
Описание:
В переменную pPropName помещается имя свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, в pPropName помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. Платформа освобождает эту память вызовом SysFreeString).
GetPropVal
Синтаксис:
HRESULT GetPropVal(long lPropNum,VARIANT *pvPropVal)
Параметры:
LPropNum
Тип: long. Порядковый номер свойства.
PvPropVal
Тип: VARIANT*. Указатель на структуру VARIANT, содержащую при возврате значение свойства.
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - свойство с номером lPropNum в данном расширении отсутствует или недоступно для чтения.
Описание:
В переменную pvPropVal помещается значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует или недоступно для чтения, должен иметь тип VT_EMPTY.
SetPropVal
Синтаксис:
HRESULT SetPropVal(long lPropNum, VARIANT *pvPropVal)
Параметры:
LPropNum
Тип: long. Порядковый номер свойства.
PvPropVal
Тип: VARIANT*. Структура VARIANT, содержащая новое значение свойства.
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - свойство с номером lPropNum в данном расширении отсутствует или недоступно для записи.
Описание:
Переменная pvPropVal содержит значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, недоступно для чтения или тип переданного pvPropVal не приводится к необходимому, метод должен возвратить S_FALSE.
IsPropReadable
Синтаксис:
HRESULT IsPropReadable(long lPropNum, BOOL *pboolPropReadable)
Параметры:
LPropNum
Тип: long. Порядковый номер свойства.
PboolPropReadable
Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг возможности чтения свойства.
Возвращаемое значение:
S_OK - операция завершена успешно.
S_FALSE - свойство с номером lPropNum в данном расширении отсутствует.
Описание:
В переменную pboolPropReadable помещается флаг возможности чтения свойства с порядковым номером lPropNum: FALSE(0) — свойство недоступно для чтения, TRUE(1) — свойство допускает чтение. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.
IsPropWritable
Синтаксис:
HRESULT IsPropWritable(long lPropNum, BOOL *pboolPropWritable)
Параметры:
LPropNum
Тип: long. Порядковый номер свойства.
PboolPropWritable
Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг возможности записи свойства.
Возвращаемое значение:
S_OK - операция завершена успешно.
S_FALSE - свойство с номером в данном расширении отсутствует.
Описание:
В переменную pboolPropWritable помещается флаг возможности записи свойства с порядковым номером lPropNum: FALSE(0) — свойство недоступно для записи, TRUE(1) — свойство допускает запись. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.
--------------------------------------------------------------------------------
Первый метод имеет порядковый номер 0. Первый параметр метода имеет порядковый номер 0.
--------------------------------------------------------------------------------
GetNMethods
Синтаксис:
HRESULT GetNMethods(long *plMethods)
Параметры:
PlMethods
Тип: long*. Указатель на переменную, содержащую при возврате количество методов расширения языка.
Возвращаемое значение:
S_OK
Описание:
В переменную plMethods помещается количество методов данного расширения, 0 - при отсутствии методов.
FindMethod
Синтаксис:
HRESULT FindMethod(BSTR bstrMethodName,long *plMethNum)
Параметры:
BstrMethodName
Тип: BSTR. Имя метода
PlMethNum
Тип: long*. Указатель на переменную, содержащую при возврате порядковый номер метода с именем methodName.
Возвращаемое значение:
S_OK
Описание:
В переменную plMethNum помещается порядковый номер метода с именем bstrMethodName; -1 — при отсутствии метода.
GetMethodName
Синтаксис:
HRESULT GetMethodName(long lMethodNum, long lAliasNum, BSTR *pbstrMethName)
Параметры:
LMethodNum
Тип: long. Порядковый номер метода.
LAliasNum
Тип: long. Язык имени метода:
0 — английское наименование;
1 — локальное наименование.
PbstrMethName
Тип: BSTR*. Указатель на строку, содержащую при возврате имя метода.
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - метод с номером в данном расширении отсутствует
Описание:
В переменную помещается имя свойства с порядковым номером; если свойство с таким номером отсутствует, в помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. Платформа освобождает эту память вызовом SysFreeString).
GetNParams
Синтаксис:
HRESULT GetNParams(long lMethodNum, long *plMethParams)
Параметры:
LMethodNum
Тип: long. Порядковый номер метода.
PlMethParams
Тип: long*. Указатель на переменную, содержащую при возврате количество параметров метода.
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - метод с номером в данном расширении отсутствует
Описание:
В переменную plMethParams помещается количество параметров метода с порядковым номером lMethodNum; если свойство с таким номером отсутствует или не имеет параметров, в помещается 0. Память для переменной выделяется платформой.
GetParamDefValue
Синтаксис:
HRESULT GetParamDefValue(long lMethodNum, long lParamNum, VARIANT *pvParamDefVal)
Параметры:
LMethodNum
Тип: long. Порядковый номер метода.
LParamNum
Тип: long. Порядковый номер параметра.
PvParamDefVal
Тип: VARIANT*. Указатель на структуру VARIANT, содержащую при возврате значение параметра по умолчанию.
Возвращаемое значение:
S_OK - операция завершена успешно (вне зависимости от наличия у параметра значения по умолчанию)
S_FALSE - метод или параметр метода отсутствует
Описание:
В переменную pvParamDefVal помещается значение по умолчанию параметра lParamNum метода с порядковым номером lMethodNum. В pvParamDefVal помещается тип VT_EMPTY, если метод с таким номером отсутствует, не имеет параметра с номером или параметр не имеет значения по умолчанию. Память для переменной выделяется платформой.
HasRetVal
Синтаксис:
HRESULT HasRetVal(long lMethodNum,BOOL *pboolHasRetVal)
Параметры:
LMethodNum
Тип: long. Порядковый номер метода.
PboolHasRetVal
Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг наличия возвращаемого значения.
Возвращаемое значение:
S_OK - операция завершена успешно
S_FALSE - метод отсутствует
Описание:
В переменную pboolHasRetVal помещается флаг наличия возвращаемого значения у метода с порядковым номером lMethodNum: TRUE для методов с возвращаемым значением и FALSE в противном случае. Память для переменной выделяется платформой.
CallAsProc
Синтаксис:
HRESULT CallAsProc(long lMethodNum, SAFEARRAY **pVars)
Параметры:
LMethodNum
Тип: long. Порядковый номер метода.
PVars
Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.
Возвращаемое значение:
S_OK - соответствующий метод вызван, ошибок не произошло.
E_FAIL - соответствующий метод вызван, произошла ошибка времени исполнения (runtime error). Исполнение модуля прекращается.
S_FALSE – отсутствует метод, соответствующий переданному lMethodNum.
Описание:
Выполняется метод с порядковым номером lMethodNum. Если метод возвращает E_FAIL, возникает ошибка времени выполнения и выполнение модуля. Память для массива параметров выделяется платформой.
CallAsFunc
Синтаксис:
HRESULT CallAsFunc(long lMethodNum, VARIANT *pRetValue, SAFEARRAY **pVars)
Параметры:
LMethodNum
Тип: long. Порядковый номер метода.
PRetValue
Тип: VARIANT*. Указатель на структуру VARIANT, при возврате содержащую возвращаемое значение.
PVars
Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.
Возвращаемое значение:
S_OK - соответствующий метод вызван, ошибок не произошло.
E_FAIL - соответствующий метод вызван, произошла ошибка времени исполнения (runtime error). Исполнение модуля прекращается.
S_FALSE – отсутствует метод, соответствующий переданному lMethodNum.
Описание:
Выполняется метод с порядковым номером lMethodNum. Если метод возвращает E_FAIL, возникает ошибка времени выполнения и выполнение модуля прекращается. Память для массива параметров и возвращаемого значения выделяется платформой.
Вызов функции компоненты
Соответствие между типами "1С:Предприятие 8. Расширение для карманных компьютеров" и COM:
Возвращение значений из компоненты
Соответствие между типами "1С:Предприятие 8. Расширение для карманных компьютеров" и COM:
При возникновении асинхронного события (например, считывания штрих-кода) объект может использовать интерфейс IAsyncEvent для создания внешнего события. Интерфейс IAsyncEvent унаследован от IUnknown. Все события помещаются в очередь и обрабатываются по порядку появления. Количество запоминаемых событий ограничено длиной очереди. При инициализации длина очереди устанавливается равной 1 и может быть изменена вызовами GetEventBufferDepth и SetEventBufferDepth. Для каждого объекта внешней компоненты поддерживается своя очередь событий. Обработка внешнего события производится предопределенной процедурой ОбработкаВнешнегоСобытия и обработчиками внешних событий в модулях форм.
SetEventBufferDepth
Синтаксис:
HRESULT SetEventBufferDepth(long lDepth)
Параметры:
lDepth
Тип: long. Длина очереди сообщений.
Возвращаемое значение:
S_OK - размер очереди установлен успешно
E_FAIL - при установке размера очереди произошла ошибка
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Устанавливает размер очереди событий для данного объекта. Если текущее количество событий в очереди больше устанавливаемой длины, последние события обрезаются.
GetEventBufferDepth
Синтаксис:
HRESULT GetEventBufferDepth(long *plDepth)
Параметры:
plDepth
Тип: long*. Указатель на переменную, содержащую при возврате длину очереди сообщений.
Возвращаемое значение:
S_OK - размер очереди возвращен успешно
E_FAIL - при получении размера очереди произошла ошибка
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
В переменную plDepth помещается размер очереди событий для данного объекта.
ExternalEvent
Синтаксис:
HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData)
Параметры:
BstrWho
Тип: BSTR. Строка с наименованием источника сообщения.
BstrWhat
Тип: BSTR. Строка с наименованием сообщения.
BstrData
Тип: BSTR. Строка c параметрами сообщения.
Возвращаемое значение:
S_OK – событие помещено в очередь
E_FAIL – очередь переполнена или неизвестная ошибка
E_OUTOFMEMORY – отсутствие памяти
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Помещает событие в очередь, записывая источник события, наименование и параметры события. При обработке события эти данные передаются процедуре ОбработкаВнешнегоСобытия . При вызове метода ExternalEvent дальнейшая обработка события происходит следующим образом: событие записывается в очередь событий (если очередь полностью занята, событие теряется), затем при отсутствии системных событий из очереди берется первое событие (если очередь не пуста) и запускается процесс обработки внешних событий. Этот процесс повторяется для всех объектов внешних компонент. Таким образом, обработка внешних событий синхронизируется с обработкой системных событий.
CleanBuffer
Синтаксис:
HRESULT CleanBuffer()
Возвращаемое значение:
S_OK — очередь успешно очищена
E_FAIL – при очищении очереди произошла ошибка
Возможны другие коды возврата, сигнализирующие об ошибке.
Описание:
Очищает очередь событий, удаляя все присутствующие в очереди события.