Описание технологии создания и использования внешних компонент для "1С:Предприятие 8. Расширение для карманных компьютеров"

 

Общее описание технологии создания и использования внешних компонент

Технология создания внешних компонент для "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)

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

Синтаксис:

ВнешнееСобытие (<Источник>, <Событие>, <Данные>)

Параметры:

<Источник>

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

<Событие>

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

<Данные>

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

Описание:

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

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

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

При загрузке внешней компоненты функцией ЗагрузитьВнешнююКомпоненту "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, возникает ошибка времени выполнения и выполнение модуля прекращается. Память для массива параметров и возвращаемого значения выделяется платформой.

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

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

Соответствие между типами "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 – при очищении очереди произошла ошибка

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

Описание:

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