Платформа 1С:Предприятие 8.3
09.01.2023

Технология создания внешних компонент

• Введение
• Структура каталогов комплекта поставки "Технологии внешних компонент"
• Создание компонент с использованием технологии Native API
  • Интерфейс компоненты
  • Интерфейс 1С:Предприятия
  • Соответствие типов tVariant и 1С:Предприятия
  • Особенности разработки компонент с использованием Native API
• Создание компонент, с использованием технологии COM
  • Инициализация и выгрузка компоненты
  • Расширение встроенного языка
  • Локализация
  • Использование типа COM VARIANT при обмене данными
    • Вызов функции компоненты
    • Возвращение значений из компоненты
    • Вызов метода объекта 1С:Предприятия из компоненты
  • COM-интерфейсы 1C:Предприятия
    • Сохранение параметров объекта компоненты
    • Информационные сообщения о работе объекта
    • Диалоговые сообщения
    • Информация о платформе
    • Внешние события
    • Работа со строкой состояния
  • Создание окон в среде "1С:Предприятия 8"
  • Доступ к "1С:Предприяти" через механизм OLE Automation
  • Методы и свойства, доступные через OLE Automation
  • Особенности разработки компонент с использованием COM
• Подготовка внешних компонент к работе с Веб-клиентом
  • Внешние компоненты для Internet Explorer
    • Создание адаптера для Internet Explorer
    • Создание установочного пакета для Internet Explorer
  • Внешние компоненты для Google Chrome и Mozilla Firefox
    • Создание адаптера для Google Chrome и Mozilla Firefox
    • Создание установочного пакета для Google Chrome и Mozilla Firefox
  • Внешние компоненты для Safari
    • Создание адаптера для Safari
    • Создание установочного пакета для Safari
• Подготовка внешних компонент для загрузки в конфигурацию
  • Описание файла MANIFEST.XML
    Описание файла IOS_MANIFEST_EXTENSIONS.XML
    Описание файла ANDROID_MANIFEST_EXTENSIONS.XML
    Описание файла WINDOWS_RT_MANIFEST_EXTENSIONS.XML
    Правила формирования имени внешней компоненты для мобильной платформы "1C:Предприятие"
  • Ограничения в работе внешних компонент
• Описание примеров
  • Примеры внешней компоненты "1С:Предприятие" для персонального компьютера
    Пример внешней компоненты для мобильной платформы "1С:Предприятие"

Введение

Система программ "1С:Предприятие" предназначена для решения самых разнообразных задач автоматизации деятельности организаций. Она обладает мощными средствами конфигурирования, которые позволяют штатными средствами настроить систему на особенности обработки информации в конкретной организации. В тоже время, "1С:Предприятие" является открытой системой. Для связи с другими программами могут использоваться встроенные средства загрузки-выгрузки информации в текстовом формате, в формате XML, система поддерживает стандарт интеграции программ OLE Automation, предоставляет доступ через web-сервисы. Однако для специальных задач интеграции может потребоваться более тесное взаимодействие между "1С:Предприятием" и другими программами.

Для решения таких задач разработана "Технология внешних компонент". Данная технология позволяет создавать программы, которые будут динамически подключаться и тесно взаимодействовать с системой "1С:Предприятие", расширяя ее возможности. Внешние компоненты позволяют решать широкий спектр специальных задач, в частности, задачи, связанные с использованием различного торгового оборудования совместно с "1С:Предприятием". Внешние компоненты могут быть подключены как к серверу приложения 1С:Предприятия, так и клиентским приложениям, в т.ч. и веб-клиенту.

В комплект поставки входит данное руководство и набор примеров реализации внешних компонент с помощью различных технологий.

В данном руководстве описана технология создания внешних компонент с использованием Native API и COM.

Структура каталогов комплекта поставки "Технологии внешних компонент"

Каталог include содержит набор включаемых заголовочных файлов для создания внешних компонент.

Каталог lib содержит статические библиотеки для построения расширений для браузеров Mozilla Firefox, Google Chrome, Safari и Internet Explorer.

Каталог example содержит примеры внешних компонент, разработанных с использованием COM и Native API. В этом же каталоге находятся примеры расширений для браузеров и для мобильной платформы.

Каталог template содержит шаблон для создания компоненты, разработанной по технологии Native API.

Каталог templateMobile содержит шаблон для создания компоненты, разработанной по технологии Native API для мобильной платформы.

Создание компонент c использованием технологии Native API

Эта технология позволяет создавать внешние компоненты, которые могут подключаться как в клиентском приложении, так и на сервере приложений "1С:Предприятие", в версиях для Windows, Linux, а также Windows Runtime,  Android и  iOS.

Для операционных систем Windows Runtime,  Android и  iOS использование пользовательского интерфейса запрещено.

Внешняя компонента реализует один или несколько объектов компоненты, которые могут использоваться в "1С:Предприятии". Каждый объект компоненты должен наследоваться от абстрактного класса IComponentBase (файл ComponentBase.h входит в комплект поставки) и реализовать все его методы.

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

GetClassNames

Синтаксис:

const WCHAR_T* GetClassNames() 

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

const WCHAR_T*

Описание:

Получение списка имен объектов компоненты.

GetClassObject

Синтаксис:

long GetClassObject(const WCHAR_T* clsName, IComponentBase** pIntf) 

Параметры:

• <clsName> Тип: const WCHAR_T*. Имя создаваемого объекта.
• <pIntf> Тип: IComponentBase**. Указатель на переменную, в которую нужно записать адрес вновь созданного объекта.

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

• long – не нулевое значение сигнализирует о успешном создании объекта

Описание:

Создание экземпляра объекта компоненты. Если объект не может быть создан или не найден объект с указанным именем – возвращается 0.

DestroyObject

Синтаксис:

long DestroyObject(IComponentBase** pIntf) 

Параметры:

• <pIntf> Тип: IComponentBase**. Указатель на объект компонеты.

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

• long – успешность выполнения

Описание:

Удаление экземпляра ранее созданного объекта. Компонента должна своими средствами удалить объект и освободить используемую им память. При успешном завершении возвращается 0, иначе – код ошибки (Runtime error).

SetPlatformCapabilities

Синтаксис:

AppCapabilities SetPlatformCapabilities(const AppCapabilities capabilities)

Параметры:

• <capabilities> Тип: перечисление AppCapabilities. Значения перечисления: eAppCapabilitiesInvalid = -1, eAppCapabilities1 = 1, eAppCapabilitiesLast = eAppCapabilities1,

Описание:

Устанавливает версию поддерживаемых платформой возможностей. Компонента должна вернуть версию, с которой она может работать. Если функция не реализована, то для компоненты не будут доступны возможности вывода сообщений, запроса информации о платформе.

GetAttachType

Синтаксис:

AttachType GetAttachType()

Параметры:

• Нет

Описание:

Компонента должна вернуть поддерживаемый тип подключения, с которым она может работать. Если функция не реализована, то компонента будут подключаться в зависимости от режима совместимости конфигурации.

Допустимые значения:

• eCanAttachNotIsolated = 1 - подключение к процессу платформы,
• eCanAttachIsolated = 2 - подключение к отдельному хост-процессу,
• eCanAttachAny = 3 - любое подключение.

Интерфейс компоненты

Init

Синтаксис:

bool Init(void* Interface) 

Параметры:

• <Interface> Тип: void*. Указатель на интерфейс 1С:Предприятия.

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

• bool – успешность выполнения

Описание:

При загрузке "1С:Предприятие" инициализирует объект компоненты, вызывая метод Init и передавая указатель на IAddInDefBase. Объект может сохранить этот указатель для дальнейшего использования. Объект должен возвратить true, если инициализация прошла успешно, и false при возникновении ошибки.

setMemManager

Синтаксис:

bool setMemManager(void* memManager) 

Параметры:

• <memManager> Тип: void*. Указатель на интерфейс менеджера памяти 1С:Предприятия.

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

• bool – успешность выполнения

Описание:

Установка менеджера памяти для компоненты. При вызове методов компоненты и передаче возвращаемых значений, которые не могут быть переданы полностью через стек, компонента должна выделять память с помощью функции AllocMemory, предоставляемую менеджером памяти. "1С:Предприятие" впоследствии освободит эту память с помощью функции FreeMemory.

ВАЖНО: нельзя выделять память для возврата значений с помощью new или malloc, т.к. это приведет к утечке памяти и к нестабильности работы программы.

GetInfo

Синтаксис:

long GetInfo(); 

Параметры: нет.

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

• long – версия компоненты

Описание:

"1С:Предприятие" вызывает этот метод для получения информации о компоненте. Например: версия 3.56 — число 3560.

Done

Синтаксис:

void Done(); 

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

Описание:

"1С:Предприятие" вызывает этот метод при завершении работы с объектом компоненты. Этот метод вызывается независимо от результата инициализации объекта (метод Init).

RegisterExtensionAs

Синтаксис:

bool RegisterExtensionAs(WCHAR_T** wsExtName) 

Параметры:

• <wsExtName> Тип: WCHAR_T**. Наименование расширения встроенного языка 1С:Предприятия.

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

• bool – успешность выполнения

Описание:

В переменную wsExtName помещается наименование расширения. Память для строки выделяется объектом компоненты функцией AllocMemory менеджера памяти. "1С:Предприятие" освобождает эту память вызовом FreeMemory.

GetNProps

Синтаксис:

long GetNProps() 

Параметры: нет.

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

• long — количество свойств

Описание:

Возвращает количество свойств данного расширения, 0 – при отсутствии свойств.

FindProp

Синтаксис:

long FindProp(const WCHAR_T* wsPropName); 

Параметры:

• <wsPropName> Тип: const WCHAR_T*. Наименование свойства.

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

• long - порядковый номер свойства.

Описание:

Возвращает порядковый номер свойства с именем pszPropName; -1, если свойство не найдено. Первое свойство имеет порядковый номер 0.

GetPropName

Синтаксис:

const WCHAR_T* GetPropName(long lPropNum, long lPropAlias) 

Параметры:

• <lPropNum> Тип: long. Порядковый номер свойства.
• <lPropAlias> Тип: long. Язык наименования:
  • 0 — английское наименование;
  • 1 — локальное наименование.

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

• const WCHAR_T*

Описание:

В возвращаемое значение помещается имя свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, возвращается NULL. Память для строки выделяется объектом компоненты функцией AllocMemory менеджера памяти. "1С:Предприятие" освобождает эту память вызовом FreeMemory.

GetPropVal

Синтаксис:

bool GetPropVal(const long lPropNum, tVariant* pvarPropVal) 

Параметры:

• <lPropNum> Тип: const long. Порядковый номер свойства.
• <pvarPropVal> Тип: tVariant*. Указатель на структуру tVariant, содержащую при возврате значение свойства.

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

• bool – успешность выполнения

Описание:

В переменную pvarPropVal помещается значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует или недоступно для чтения, должен иметь тип VTYPE_EMPTY. Если возвращаемое значение имеет тип строка, то компонента выделяет память для нее функцией AllocMemory. "1С:Предприятие" освободит эту память.

SetPropVal

Синтаксис:

bool SetPropVal(const long lPropNum, tVariant* pvarPropVal); 

Параметры:

• <lPropNum> Тип: const long. Порядковый номер свойства.
• <pvarPropVal> Тип: tVariant*. Структура tVariant, содержащая новое значение свойства.

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

• bool – успешность выполнения

Описание:

Переменная pvarPropVal содержит значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, недоступно для записи или тип переданного pvarPropVal не совместим, метод должен возвратить false.

IsPropReadable

Синтаксис:

bool IsPropReadable(const long lPropNum) 

Параметры:

• <lPropNum> Тип: const long. Порядковый номер свойства.

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

• bool

Описание:

Возвращается флаг возможности чтения свойства с порядковым номером lPropNum: false — свойство недоступно для чтения, true — свойство допускает чтение. Если свойство с таким номером отсутствует, метод должен возвращать false.

IsPropWritable

Синтаксис:

bool IsPropWritable(const long lPropNum) 

Параметры:

• <lPropNum> Тип: const long. Порядковый номер свойства.

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

• bool

Описание:

Возвращается флаг возможности записи свойства с порядковым номером lPropNum: false — свойство недоступно для записи, true — свойство допускает запись. Если свойство с таким номером отсутствует, метод должен возвращать false.

Первый метод имеет порядковый номер 0. Первый параметр метода имеет порядковый номер 0.

GetNMethods

Синтаксис:

long GetNMethods(); 

Параметры: нет

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

• long — количество методов.

Описание:

Возвращается количество методов данного расширения, 0 - при отсутствии методов.

FindMethod

Синтаксис:

long FindMethod(const WCHAR_T* wsMethodName); 

Параметры:

• <wsMethodName> Тип: const WCHAR_T*. Имя метода

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

• long — порядковый номер метода

Описание:

Возвращается порядковый номер метода с именем wsMethodName; -1 — при отсутствии метода.

GetMethodName

Синтаксис:

const WCHAR_T* GetMethodName(const long lMethodNum, const long lMethodAlias) 

Параметры:

• <lMethodNum> Тип: const long. Порядковый номер метода.
• <lMethodAlias> Тип: const long. Язык имени метода:
  • 0 — английское наименование;
  • 1 — локальное наименование.

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

• const WCHAR_T* - название метода

Описание:

Возвращается имя метода с порядковым номером; если свойство с таким номером отсутствует, возвращается NULL. Память для строки выделяется объектом компоненты функцией AllocMemory менеджера памяти. "1С:Предприятие" освобождает эту память вызовом FreeMemory.

GetNParams

Синтаксис:

long GetNParams(const long lMethodNum) 

Параметры:

• <lMethodNum> Тип: const long. Порядковый номер метода.

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

• long — количество параметров метода

Описание:

Возвращается количество параметров метода с порядковым номером lMethodNum; если метод с таким номером отсутствует или не имеет параметров, возвращается 0.

GetParamDefValue

Синтаксис:

bool GetParamDefValue(const long lMethodNum, const long lParamNum, tVariant* pvarParamDefValue) 

Параметры:

• <lMethodNum> Тип: const long. Порядковый номер метода.
• <lParamNum> Тип: const long. Порядковый номер параметра.
• <pvarParamDefValue> Тип: tVariant*. Указатель на структуру tVariant, содержащую при возврате значение параметра по умолчанию.

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

• bool — истина, если операция завершена успешно (вне зависимости от наличия у параметра значения по умолчанию)

Описание:

В переменную pvarParamDefValue помещается значение по умолчанию параметра с номером lParamNum метода с порядковым номером lMethodNum. В pvarParamDefValue помещается тип VTYPE_EMPTY, если метод с таким номером отсутствует, не имеет параметра с номером или параметр не имеет значения по умолчанию. В случае, если значение по умолчанию имеет тип VTYPE_PSTR, VTYPE_PWSTR или VTYPE_BLOB, компонента выделяет память функцией AllocMemory менеджера памяти, записывает туда данные и сохраняет этот адрес в соответствующем поле структуры. "1С:Предприятие" освободит эту память вызовом FreeMemory.

HasRetVal

Синтаксис:

bool HasRetVal(const long lMethodNum) 

Параметры:

• <lMethodNum> Тип: const long. Порядковый номер метода.

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

• bool

Описание:

Возвращается флаг наличия у метода с порядковым номером lMethodNum возвращаемого значения: true для методов с возвращаемым значением и false в противном случае.

CallAsProc

Синтаксис:

bool CallAsProc(const long lMethodNum, tVariant* paParams, const long lSizeArray) 

Параметры:

• <lMethodNum> Тип: const long. Порядковый номер метода.
• <paParams> Тип: tVariant* Указатель на массив структур tVariant, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.
• <lSizeArray> Тип: const long. Размер массива paParams.

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

• true – соответствующий метод вызван, ошибок не произошло.
• false – отсутствует метод или произошла ошибка времени исполнения (runtime error).

Описание:

Выполняется метод с порядковым номером lMethodNum. Если метод возвращает false, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров выделяется и освобождается "1С:Предприятием".

CallAsFunc

Синтаксис:

bool CallAsFunc(const long lMethodNum, tVariant* pvarRetValue, tVariant* paParams, const long lSizeArray) 

Параметры:

• <lMethodNum> Тип: const long. Порядковый номер метода.
• <pvarRetValue> Тип: tVariant*. Указатель на структуру tVariant, содержащую возвращаемое значение.
• <paParams> Тип: tVariant*. Указатель на массив структур tVariant, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.
• <lSizeArray> Тип: const long. Размер массива paParams.

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

• true – соответствующий метод вызван, ошибок не произошло.
• false – отсутствует метод или произошла ошибка времени исполнения (runtime error).

Описание:

Выполняется метод с порядковым номером lMethodNum. Если метод возвращает false, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров выделяется "1С:Предприятием". Если возвращаемое значение имеет тип строка или двоичные данные, компонента выделяет память функцией AllocMemory менеджера памяти, записывает туда данные и сохраняет этот адрес в соответствующем поле структуры. "1С:Предприятие" освободит эту память вызовом FreeMemory.

Локализация

SetLocale

Синтаксис:

void SetLocale(const WCHAR_T* wsLocale) 

Параметры:

• <wsLocale> Тип: const WCHAR_T*. Строка локализации в формате <language>_<REGION>. Например: для Linux – "ru_RU", для Windows - "rus_RUS".

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

• нет

Описание:

(Устаревший. Для использования с платформой до версии 8.3.21) "1С:Предприятие" вызывает этот метод для локализации компоненты в соответствии с используемым кодом локализации. Компонента  может настроить свое окружение для правильного вывода информации.

SetUserInterfaceLanguageCode

Синтаксис:

void SetUserInterfaceLanguageCode(const WCHAR_T* wsLanguageCode)

Параметры:

• <wsLanguageCode> Тип: const WCHAR_T*. Код языка в двухбуквенном формате. Например: "ru", "en".

Описание:

"1С:Предприятие" передает в компоненту код языка, используемый интерфейсом пользователя, в двухбуквенном формате.

Интерфейс 1С:Предприятия

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

AddError

Синтаксис:

bool AddError(unsigned short wcode, const WCHAR_T* source, const WCHAR_T* descr, long scode)

Параметры:

• <wcode> Тип: unsigned short. Код сообщения.
• <source> Тип: const WCHAR_T*. Источник ошибки.
• <descr> Тип: const WCHAR_T*. Сообщение ошибки.
• <scode> Тип: Код ошибки.

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

• bool

Описание:

Добавляет информационное сообщение при работе методов расширения языка. Если возвращаемое значение true – информация об ошибке успешно добавлена. Если scode имеет не нулевое значение – будет сгенерировано исключение, которое может быть перехвачено и обработано средствами встроенного языка "1С:Предприятия".

Возможные коды сообщений и поведение 1С:Предприятия подробно описаны в разделе "Информационные сообщения о работе объекта" для COM-компонент.

RegisterProfileAs

Синтаксис:

bool RegisterProfileAs(WCHAR_T* wsProfileName) 

Параметры:

• <wsProfileName> Тип: WCHAR_T*. Наименование списка параметров компоненты.

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

• bool

Описание:

Регистрирует список параметров компоненты с именем wsProfileName.

Read

Синтаксис:

bool Read(WCHAR_T* pszPropName, tVariant* pVal, long* pErrCode, WCHAR_T** errDescriptor) 

Параметры:

• <pszPropName> Тип: WCHAR_T*. Имя параметра
• <pVal> Тип: tVariant _t*. Указатель на возвращаемое значение параметра
• < pErrCode > Тип: long*. Указатель на переменную, куда будет помещен код ошибки, если возникнет.
• <errDescriptor> Тип: WCHAR_T**. Двойной указатель на переменную, куда будет помещено описание ошибки.

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

• bool

Описание:

Читает сохраненное значение параметра компоненты с именем pszPropName. В случае неудачи чтения, и ненулевого значения errDescriptor, "1С:Предприятие" выделит память и поместит описание ошибки. Компонента должна освободить память вызовом FreeMemory. Для возвращаемых данных типа строка, память также выделяется "1С:Предприятие"м и адрес сохраняется в соответствующем поле структуры tVariant. Компонента должна освободить ее вызовом FreeMemory.

Write

Синтаксис:

bool Write(WCHAR_T* pszPropName, tVariant* pVar) 

Параметры:

• <pszPropName> Тип: WCHAR_T*.  Имя параметра
• <pVar> Тип: tVariant _t*. Указатель на значение параметра

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

• bool

Описание:

Сохраняет значение параметра компоненты с именем pszPropName. В случае неудачи возвращается false.

SetEventBufferDepth

Синтаксис:

bool SetEventBufferDepth( long lDepth) 

Параметры:

• <lDepth> Тип: long. Длина очереди событий.

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

• bool. True – новый размер установлен.

Описание:

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

GetEventBufferDepth

Синтаксис:

long GetEventBufferDepth() 

Параметры: нет

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

• long - длина очереди событий.

Описание:

Возвращается размер очереди событий для данного объекта.

ExternalEvent

Синтаксис:

bool ExternalEvent(WCHAR_T* wsSource, WCHAR_T* wsMessage, WCHAR_T* wsData) 

Параметры:

• <wsSource> Тип: WCHAR_T*. Строка с наименованием источника события.
• <wsMessage> Тип: WCHAR_T*. Строка с наименованием события.
• <wsData> Тип: WCHAR_T*. Строка c параметрами события.

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

• true – событие помещено в очередь
• false – очередь переполнена, обработка событий недоступна или неизвестная ошибка.

Описание:

Помещает событие в очередь, записывая источник события, наименование и параметры события. При обработке события эти данные передаются процедуре ОбработкаВнешнегоСобытия. При вызове метода ExternalEvent дальнейшая обработка события происходит следующим образом: событие записывается в очередь событий (если очередь полностью занята, событие теряется), затем при отсутствии системных событий из очереди берется первое событие (если очередь не пуста) и запускается процесс обработки внешних событий. Этот процесс повторяется для всех объектов внешних компонент. Таким образом, обработка внешних событий синхронизируется с обработкой системных событий.

CleanEventBuffer

Синтаксис:

void CleanEventBuffer() 

Описание:

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

SetStatusLine

Синтаксис:

bool SetStatusLine(WCHAR_T* wsStatusLine) 

Параметры:

• <wsStatusLine> Тип: WCHAR_T*. Текст строки состояния.

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

• true — текст отображен в строке состояния
• false – функция недоступна или неизвестная ошибка.

Описание:

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

ResetStatusLine

Синтаксис:

void ResetStatusLine() 

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

Нет

Описание:

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

GetInterface

Синтаксис:

IInterface* GetInterface(Interfaces iface)

Параметры:

• <iface> Тип: Interfaces. Значение перечисления Interfaces: eIMsgBox, eIPlatformInfo

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

• Iinterface* - указатель на запрашиваемый интерфейс.

Описание:

Запрашивает интерфейс платформы. Если запрашиваемый интерфейс поддерживается платформой, будет возвращен указатель на интерфейс. Иначе — 0.

Confirm

Синтаксис:

bool Confirm(const WCHAR_T* queryText, tVariant* retVal)

Параметры:

• <queryText> Тип: WCHAR_T*. Текст вопроса.
• <retVal> Тип: tVariant*. Возвращаемое значение диалога. Тип VTYPE_BOOL. Значение true соответствует кнопке ОК, false – Отмена.

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

• bool — истина, если диалог отображен.

Описание:

Выводит диалог с текстом, заданным параметром queryText, и кнопками ОК и Отмена.

Alert

Синтаксис:

bool Alert(const WCHAR_T* text)

Параметры:

• <text> Тип: WCHAR_T*. Текст сообщения.

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

• bool — истина, если диалог отображен.

Описание:

Выводит простой диалог уведомления с текстом, заданным параметром text и кнопкой ОК.

GetPlatformInfo

Синтаксис:

AppInfo* GetPlatformInfo()

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

• AppInfo* - указатель на структуру с полями: AppVersion — Тип: WCHAR_T*, версия приложения, Application — Тип: перечисление, тип подключившего компоненту приложения, UserAgentInformation — Тип: WCHAR_T*, информация о браузере (только для веб-клиента)

Описание:

Запрашивает информацию о платформе. При подключении компоненты в веб-клиенте версии платформы ниже 8.3.3, будет заполнено только поле Application структуры AppInfo.

GetAttachedInfo

Синтаксис:

AttachedType GetAttachedInfo()

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

• AttachedType - тип подключения компоненты к платформе:
  • eAttachedIsolated = 0 - подключена изолированно,
  • eAttachedNotIsolated = 1 - подключена не изолированно.

Описание:

Запрашивает информацию о типе подключения компоненты.

Соответствие типов tVariant и 1С:Предприятия

Соответствие между типами 1С:Предприятия и COM:

• VTYPE_EMPTY соответствует неопределенному значению. При передаче в качестве параметра метода подставляется значение параметра по умолчанию;
• значения типа VTYPE_I2, VTYPE_I4, VTYPE_ERROR, VTYPE_UI1 соответствуют целочисленному значению и находятся в lVal;
• значения типа VTYPE_BOOL, соответствуют булевому значению и находятся в bVal;
• значения типа VTYPE_R4, VTYPE_R8, VTYPE_CY соответствуют дробному значению и находятся в dblVal;
• значение типа VTYPE_DATE соответствует значению даты и находится в date;
• значение типа VTYPE_TM соответствует значению даты и находится в struct tm tmVal;
• значение типа VTYPE_PSTR соответствует строковому значению (char*) и находится в pstrVal с указанием длины в strLen;
• значение типа VTYPE_PWSTR соответствует строковому значению (WCHAR_T*) и находится в pwstrVal с указанием длины в wstrLen;
• значение типа VTYPE_BLOB соответствует двоичным данным и находится в pstrVal с указанием длины в strLen;

Типы VTYPE_INTERFACE, VTYPE_VARIANT не поддерживаются.

Примечание:
Числовые значения, переданные в качестве параметров из веб-клиента, могут приходить с любым числовым типом.

Тип VTYPE_BLOB не поддерживается в веб-клиенте.

Особенности разработки компонент с использованием Native API

Компонента с использованием этой технологии является платформозависимой. Поэтому разработчик должен строить вариант компоненты как для платформ x86 и x86-64, так и для ARM64, и Эльбрус-8С. В процессе использования, разработчик конфигурации определит тип платформы и загрузит нужный вариант компоненты.

Компонента должна поддерживать работу на всех ОС из списка поддерживаемых операционных систем. Сборку компоненты для ОС Linux рекомендуется производить на самой старшей версии из списка поддерживаемых ОС Linux.

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

"1С:Предприятие" работает со строками в формате Unicode (WCHAR_T) с размером символа 2 байта. Размерность совпадает со встроенным типом wchar_t для ОС Windows, но может отличаться для остальных ОС, где, например, размер wchar_t, может составлять 4 байта. Разработчик компоненты должен самостоятельно выполнять преобразование символьных данных этого типа.

Если внешняя компонента использует дополнительные модули, это нужно указывать в документации к компоненте. Используемые не системные run-time библиотеки должны быть статически включены в компоненту (если позволяет лицензия на run-time библиотеку), так как на компьютере, где будет использоваться компонента, их может не оказаться или они могут быть другой версии. Так же в компоненту для Windows нужно включать манифест.

При возникновении исключительных ситуаций, они должны быть перехвачены и обработаны в компоненте, а информация о них передана в "1С:Предприятие" с помощью метода AddError.

В случае использования компоненты на сервере приложений 1С:Предприятия, внешние события не обрабатываются. Также не будут обрабатываться методы работы со строкой статуса и сохранения параметров.

Компонента может возвращать любые двоичные данные, например – сформированное изображение штрих-кода. Для этого данные помещаются в поле pstrVal структуры tVariant, в strLen – размер данных, а тип устанавливается в VTYPE_BLOB. "1С:Предприятие" использует для них тип ДвоичныеДанные.

Значение даты передается во внешнюю компоненту в виде структуры tm и указанием типа VTYPE_TM. Компонента может вернуть значение даты как в struct tm, так и в типе DATE Windows, указав тип VTYPE_DATE. "1С:Предприятие" обработает его корректно.

Возвращаемые значения типа VTYPE_ARRAY и VTYPE_BYREF не поддерживаются.

Настройки Web-публикации для мобильной платформы "1С:Предприятие"

Во время настройки Web-публикации следует провести следующее действие. В настройках http-сервера необходимо добавить типы MIME для следующих расширений:

• .so
• .apk
• .dylib
• .a

Тип MIME: application/octet-stream

ОС Windows Runtime

Для разработки под ОС Windows Runtime  требуется установленная минимум Windows 8.1 с MS Visual Studio 2017 (пакет Windows Phone SDK).

Результатом разработки компоненты должна быть группа динамических библиотек *.dll для мобильных и планшетов всех поддерживаемых процессоров.

Примеры проектов внешней компоненты находятся в каталоге \example\NativeAPIMobile\WinRT_Proj\.

Отладка внешней компоненты проводится с помощью проектов, находящихся в поставке mobile.zip\Windows\vcproj.zip:

• store – проект MS Visual Studio для мобильных приложений;
• store_client - проект MS Visual Studio для мобильных клиентов.

Перед применением в директорию appx\ необходимо скопировать содержимое соответствующего архива поставки 1cem-XXXXX.appx.

Далее, добавив исходные коды внешней компоненты, для отладки можно использовать стандартные средства MS Visual Studio.

Для Windows Runtime не реализована возможность загрузки динамических библиотек из Web-публикации.

ОС Android

Разработка под ОС Android поддерживает написание кода на языке программирования c++, так и использование технологии Java Native Interface.

Результатом разработки компоненты под ОС Android должна быть группа динамических библиотек *.so для всех поддерживаемых процессоров. В случае использования кода Java, также должен присутствовать файл *.apk. Файл *.apk не является отдельным приложением и не предназначен для самостоятельного запуска. Впоследствии он включается в состав собранного мобильного приложения.

Пример проекта находится в каталоге \example\NativeAPIMobile\Android_Proj\.

Для отладки внешней компоненты следует использовать возможность загрузки динамических библиотек из Web-публикации. Это происходит автоматически после обновления конфигурации (с вложенными библиотеками) на устройстве с Web-публикации на компьютере разработчика.

ОС iOS

Специфика разработки приложений под iOS не позволяет использование несистемных динамических библиотек для публикации в AppStore. В связи с этим разработчик внешней компоненты должен использовать их только для разработки и отладки.

Результатом разработки компоненты под ОС iOS должен быть файл динамической библиотеки *.dylib для целей тестирования, подписанный сертификатом разработчика и бинарный файл для статической линковки *.a для сборщика приложения.

Отладка внешней компоненты проводится с помощью проекта, находящегося в поставке mobile.zip\iOS\prjios.zip.

Далее, добавив исходные коды внешней компоненты, для отладки можно использовать стандартные средства Xcode.

Для отладки внешней компоненты также можно использовать возможность загрузки динамических библиотек из Web-публикации. Это происходит автоматически после обновления конфигурации (с вложенными библиотеками) на устройстве с Web-публикации на компьютере разработчика.

Начиная с версии ОС iOS 10.0, стала недоступна возможность использования динамических библиотек из Web-публикации. В этом случае, для целей тестирования следует использовать бинарный файл статической библиотеки *.a.

Подпись сертификатом разработчика

Подпись сертификатом разработчика выполняется с помощью утилиты codesign следующей командой:

codesign -s <наименование сертификата> <имя файла библиотеки>

Например,

codesign -s "iPhone Developer" /Users/Somebody/Documents/addin/iOS_Proj/Build/com_1c_StepCounter.dylib

Статическая библиотека

Статическая библиотека *.a предназначена для сборки конечного приложения путем влинковки внешней компоненты в платформу.

Для исключения конфликта имен, код внешней компоненты должен находится в собственном уникальном пространстве имен. Наименование пространства имен должно соответствовать имени внешней компоненты или включать его как составляющую.

Регистрация компоненты производится статически при загрузке приложения. Соответствующий код можно увидеть в примере.

#if defined(__APPLE__) && !defined(BUILD_DYNAMIC_LIBRARY)

namespace COM_1C_STEP_COUNTER
{  
    static LPCVOID addin_exports[] =
    {
        "GetClassObject", (LPCVOID)GetClassObject,
        "DestroyObject", (LPCVOID)DestroyObject,
        "GetClassNames", (LPCVOID)GetClassNames,
        "SetPlatformCapabilities", (LPCVOID)SetPlatformCapabilities,
        NULL
    };
    DECLARE_DLL((const char*)g_kComponentNames, addin_exports);
}

#endif //__APPLE__ && !BUILD_DYNAMIC_LIBRARY

Пример проекта находится в каталоге \example\NativeAPIMobile\iOS_Proj\.

Создание компонент с использованием технологии COM

Технология внешних компонент с использованием COM может также применяться в "1С:Предприятии" более ранних версий (7.7, 8.0 и 8.1).

Создание компонент под Windows Runtime, Android и iOS, с использованием данной технологии, невозможно.

При загрузке внешней компоненты функцией ЗагрузитьВнешнююКомпоненту или ПодключитьВнешнююКомпоненту(<МестонахожденияКомпоненты>, <ИмяМетки>,  ТипВнешнейКомпоненты.COM) "1С:Предприятие" определяет ProgID COM—объекта компоненты следующим образом:

• ProgID имеет вид <Vendor>.<Component>;
• в качестве первой части (<Vendor>) используется строка "AddIn";
• в качестве второй части (<Component>) используется строка с ID 100 из таблицы строк компоненты. Строка может иметь вид "Name1|Name2|...|NameN", и в этом случае будут созданы все объекты с ProgID вида "AddIn.NameX". Если такая строка отсутствует, то используется имя файла внешней компоненты без расширения.

При использовании функции ПодключитьВнешнююКомпоненту(<ИмяОбъектаКомпоненты>) ProgID COM-объекта компоненты передается в качестве параметра функции и также может представляться строкой вида ProgID1| ProgID2|...|ProgIDX.

Инициализация и выгрузка компоненты

Для инициализации и выгрузки компоненты используется интерфейс IInitDone. Этот интерфейс наследован от IUnknown и предназначен для инициализации объекта и завершения работы с объектом.

Init

Синтаксис:

HRESULT Init(IDispatch *pBackConnection) 

Параметры:

• <pBackConnection> Тип: IDispatch. Указатель на интерфейс 1С:Предприятия.

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

• E_FAIL - при инициализации произошла ошибка.
• S_OK - инициализация прошла успешно.

Описание:

При загрузке "1С:Предприятие" инициализирует объект компоненты, вызывая метод Init и передавая указатель на IDispatch. Объект может сохранить этот указатель для дальнейшего использования. Все остальные интерфейсы 1С:Предприятия объект может получить, вызвав метод QueryInterface переданного ему интерфейса IDispatch. Объект должен возвратить S_OK, если инициализация прошла успешно, и E_FAIL при возникновении ошибки. Данный метод может использовать интерфейс IerrorLog для вывода информации об ошибках. При этом инициализация считается неудачной, если одна из переданных структур EXCEPINFO имеет поле scode, не равное S_OK. Все переданные в IErrorLog данные обрабатываются при возврате из данного метода. В момент вызова этого метода свойство AppDispatch не определено.

Done

Синтаксис:

HRESULT Done(void) 

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

• S_OK - объект завершил работу.
• E_FAIL - произошла ошибка.

Описание:

"1С:Предприятие" вызывает этот метод при завершении работы с объектом компоненты. Объект должен возвратить S_OK. Этот метод вызывается независимо от результата инициализации объекта (метод Init).

GetInfo

Синтаксис:

HRESULT GetInfo(SAFEARRAY** pInfo) 

Параметры:

• <PInfo> Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT. Память для массива выделяется "1С:Предприятием".

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

• S_OK - информация о компоненте возвращена.
• E_FAIL - произошла ошибка.

Описание:

"1С:Предприятие" вызывает этот метод для получения информации о компоненте. В текущей версии 2.0 компонентной технологии в элемент с индексом 0 необходимо записать версию поддерживаемой компонентной технологии в формате V_I4 — целого числа, при этом старший номер версии записывается в тысячные разряды, младший номер версии — в единицы. Например: версия 3.56 — число 3560. В настоящее время все объекты внешних компонент могут поддерживать версию 1.0 (соответствует числу 1000) или 2.0 (соответствует 2000). Память для pInfo выделяется "1С:Предприятием". Метод должен возвращать S_OK.

Объект внешней компоненты обязан реализовать этот интерфейс. При его отсутствии компонента не будет загружена.

Расширение встроенного языка

Для расширения встроенного языка компонента должна реализовать интерфейс ILanguageExtender. Этот интерфейс унаследован от IUnknown и предназначен для расширения встроенного языка 1С:Предприятия. Для использования этого расширения необходимо вызвать функцию СоздатьОбъект (Новый в "1С:Предприятии 8"), передав ей строку вида "AddIn.<ИмяРасширения>", где <ИмяРасширения> возвращается методом этого интерфейса. Затем можно использовать созданный объект, вызывая его методы и свойства.

Версия 2.0 позволяет создавать несколько объектов одного типа "AddIn.<ИмяРасширения>", однако компонента должна явно указать поддержку версии 2.0 в методе GetInfo. В противном случае допускается создание только одного объекта.

RegisterExtensionAs

Синтаксис:

HRESULT RegisterExtensionAs(BSTR *pExtensionName) 

Параметры:

• <pExtensionName> Тип: BSTR*. Наименование расширения встроенного языка 1С:Предприятия.

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

• S_OK - операция завершена успешно.
• E_FAIL - произошла ошибка.

Описание:

В переменную pExtensionName помещается наименование расширения. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. "1С:Предприятие" освобождает эту память вызовом SysFreeString).

GetNProps

Синтаксис:

HRESULT GetNProps(long* plProps) 

Параметры:

• <plProps> Тип: long*. Указатель на переменную, содержащую при возврате количество свойств расширения.

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

• S_OK - операция завершена успешно.
• E_FAIL - произошла ошибка.

Описание:

Возвращает количество свойств данного расширения, 0 – при отсутствии свойств. Память для переменной plProps выделяется "1С:Предприятием".

FindProp

Синтаксис:

HRESULT FindProp(BSTR pszPropName,long* plPropNum) 

Параметры:

• <pszPropName> Тип: BSTR. Наименование свойства.
• <plPropNum> Тип: long*. Указатель на переменную, содержащую при возврате порядковый номер свойства.

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

• S_OK - операция завершена успешно.
• S_FALSE - свойство с именем pszPropName в данном расширении отсутствует.

Описание:

Возвращает порядковый номер свойства с именем pszPropName; -1, если свойство не найдено. Первое свойство имеет порядковый номер 0. Память для переменной plPropNum выделяется ""1С:Предприятием".

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. "1С:Предприятие" освобождает эту память вызовом 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 - свойство с номером lPropNum в данном расширении отсутствует.

Описание:

В переменную pboolPropWritable помещается флаг возможности записи свойства с порядковым номером lPropNum: FALSE(0) — свойство недоступно для записи, TRUE(1) — свойство допускает запись. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.

Первый метод имеет порядковый номер 0. Первый параметр метода имеет порядковый номер 0.

GetNMethods

Синтаксис:

HRESULT GetNMethods(long* plMethods) 

Параметры:

• <plMethods> Тип: long*. Указатель на переменную, содержащую при возврате количество методов расширения языка.

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

• S_OK - операция завершена успешно.
• E_FAIL - произошла ошибка.

Описание:

В переменную plMethods помещается количество методов данного расширения, 0 - при отсутствии методов.

FindMethod

Синтаксис:

HRESULT FindMethod(BSTR bstrMethodName, long* plMethNum) 

Параметры:

• <bstrMethodName> Тип: BSTR. Имя метода.
• <plMethNum> Тип: long*. Указатель на переменную, содержащую при возврате порядковый номер метода с именем methodName.

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

• S_OK - операция завершена успешно.
• E_FAIL - произошла ошибка.

Описание:

В переменную plMethNum помещается порядковый номер метода с именем bstrMethodName; -1 — при отсутствии метода.

GetMethodName

Синтаксис:

HRESULT GetMethodName(long lMethodNum, long lAliasNum, BSTR* pbstrMethName) 

Параметры:

• <lMethodNum> Тип: long. Порядковый номер метода.
• <lAliasNum> Тип: long. Язык имени метода: 0 — английское наименование, 1 — локальное наименование.
• <pbstrMethName> Тип: BSTR*. Указатель на строку, содержащую при возврате имя метода.

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

• S_OK - операция завершена успешно.
• S_FALSE - метод с номером lMethodNum в данном расширении отсутствует.

Описание:

В переменную pbstrMethName помещается имя метода с порядковым номером; если свойство с таким номером отсутствует, в помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. "1С:Предприятие" освобождает эту память вызовом SysFreeString).

GetNParams

Синтаксис:

HRESULT GetNParams(long lMethodNum, long* plMethParams) 

Параметры:

• <lMethodNum> Тип: long. Порядковый номер метода.
• <plMethParams> Тип: long*. Указатель на переменную, содержащую при возврате количество параметров метода.

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

• S_OK - операция завершена успешно.
• S_FALSE - метод с номером lMethodNum в данном расширении отсутствует.

Описание:

В переменную plMethParams помещается количество параметров метода с порядковым номером lMethodNum; если метод с таким номером отсутствует или не имеет параметров, в помещается 0. Память для переменной выделяется "1С:Предприятие"м.

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, если метод с таким номером отсутствует, не имеет параметра с номером или параметр не имеет значения по умолчанию. Память для переменной выделяется "1С:Предприятием".

HasRetVal

Синтаксис:

HRESULT HasRetVal(long lMethodNum,BOOL* pboolHasRetVal) 

Параметры:

• <lMethodNum> Тип: long. Порядковый номер метода.
• <pboolHasRetVal> Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг наличия возвращаемого значения.

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

• S_OK - операция завершена успешно.
• S_FALSE - метод отсутствует.

Описание:

В переменную pboolHasRetVal помещается флаг наличия возвращаемого значения у метода с порядковым номером lMethodNum: TRUE для методов с возвращаемым значением и FALSE в противном случае. Память для переменной выделяется "1С:Предприятие"м.

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, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров выделяется "1С:Предприятие"м.

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С:Предприятия прекращается. Память для массива выделяется "1С:Предприятие"м.

Локализация

SetLocale

Синтаксис:

HRESULT SetLocale(BSTR bstrLocale) 

Параметры:

• <bstrLocale> Тип: BSTR. Строка локализации в формате <language>-<REGION>. Например: для России – "ru-RU".

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

• S_OK - операция завершена успешно.
• E_FAIL - произошла ошибка.

Описание:

(Устаревший. Для использования с платформой до версии 8.3.21) "1С:Предприятие" вызывает этот метод для локализации компоненты в соответствии с используемым кодом локализации. Компонента  может настроить свое окружение для правильного вывода информации.

SetUserInterfaceLanguageCode

Синтаксис:

HRESULT SetUserInterfaceLanguageCode(BSTR wsLanguageCode) 

Параметры:

• <wsLanguageCode> Тип: BSTR. Строка с двухбуквенным кодом языка. Например: для России – "ru".

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

• S_OK - операция завершена успешно.
• E_FAIL - произошла ошибка.

Описание:

"1С:Предприятие" передает в компоненту код языка, используемый интерфейсом пользователя, в двухбуквенном формате.

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

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

Соответствие между типами 1С:Предприятия и COM:

• неопределенное значение соответствует VT_EMPTY;
• целочисленное значение соответствует VT_I4 и помещается в lVal;
• дробное значение соответствует VT_R8 и помещается в dblVal;

Следует учесть, что внутреннее представление может иметь точность, превосходящую точность типа double (около 15 цифр после запятой), поэтому при конвертации может происходить потеря точности.

• значение даты соответствует VT_DATE и помещается в date;
• строковое значение соответствует VT_BSTR и помещается в bstrVal;
• объекты соответствуют VT_DISPATCH и помещаются в pdispVal. При использовании объектов 1С:Предприятия в компоненте необходимо определить DISPIDы методов объекта (вызвав GetIDsOfNames) и затем вызвать Invoke;

При конвертации COM-объекта в IDispatch проверяются ситуации взаимного вызова ""1С:Предприятие"->Компонента->"1С:Предприятие"" и "Компонента->"1С:Предприятие"->Компонента" и все необходимые операции проводятся корректно.

Возвращение значений из компоненты

Соответствие между типами 1С:Предприятия и COM:

• VT_EMPTY соответствует неопределенному значению. При передаче в качестве параметра метода подставляется значение параметра по умолчанию;
• значения типа VT_I2, VT_I4, VT_BOOL, VT_ERROR, VT_UI1 соответствуют целочисленному значению и находятся в lVal;
• значения типа VT_R4, VT_R8, VT_CY соответствуют дробному значению и находятся в dblVal;
• значение типа VT_DATE соответствует значению даты и находится в date;
• значение типа VT_BSTR соответствует строковому значению и находится в bstrVal;
• значение типа VT_ARRAY соответствует массиву и находится в parray (только для "1С:Предприятия 8");
• значение типа VT_DISPATCH соответствует значению объекта и находится в pdispVal.

Типы VT_DECIMAL, VT_VARIANT и VT_UNKNOWN не поддерживаются.

При конвертации IDispatch в COM-объект проверяются ситуации взаимного вызова ""1С:Предприятие"->Компонента->"1С:Предприятие"" и "Компонента->"1С:Предприятие"->Компонента" и все необходимые операции проводятся корректно.

Вызов метода объекта 1С:Предприятия из компоненты

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

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

COM-интерфейсы 1C:Предприятия

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

Сохранение параметров объекта компоненты

Для сохранения параметров объект внешней компоненты может использовать механизмы сохранения 1С:Предприятия через интерфейс IPropertyProfile. Этот интерфейс унаследован от интерфейса IPropertyBag, стандартного для COM, и отличается единственным методом:

RegisterProfileAs

Синтаксис:

HRESULT RegisterProfileAs(BSTR bstrProfileName) 

Параметры:

• <bstrProfileName> Тип: BSTR. Наименование списка параметров компоненты.

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

• 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, при работе с "1С:Предприятием" 8 – в профиле, соответствующем сочетанию "компьютер – ИБ - пользователь".

Информационные сообщения о работе объекта

Для сообщения пользователю информации о своей работе объект может использовать интерфейс IErrorLog, стандартный для COM (описание метода AddError интерфейса IErrorLog приводится здесь исключительно для удобства работы). Возникающие сообщения отрабатываются как в течение работы программы (при асинхронном помещении их в очередь), так и в следующих случаях: при возврате из метода инициализации Init и при возврате из метода расширения. Все сообщения помещаются в очередь и обрабатываются по порядку появления. Количество запоминаемых сообщений не ограничено.

AddError

Синтаксис:

HRESULT AddError(BSTR pszPropName, LPEXCEPINFO pExcepInfo)

Параметры:

• <pszPropName> Тип: BSTR. В настоящей реализации параметр pszPropName игнорируется.
• <pExcepInfo> Тип: LPEXCEPINFO. Указатель на структуру 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 — иконка "i";
• ADDIN_E_FAIL — иконка "err" (для "1С:Предприятия" версий 7.5 и 7.7) или "!!!" (для "1С:Предприятия" версии 8)

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

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

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

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

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

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

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

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

Диалоговые сообщения

Для диалога с пользователем, объект может использовать интерфейс IMsgBox, стандартный для COM Интерфейс IMsgBox унаследован от IUnknown Не доступен на сервере и во внешнем соединении.

Confirm

Синтаксис:

HRESULT Confirm(const BSTR queryText, VARIANT* retVal); 

Параметры:

• <queryText> Тип: BSTR. Текст вопроса.
• <retVal> Тип: VARIANT. Возвращаемое значение диалога. Тип VT_BOOL. Значение TRUE соответствует кнопке ОК, FALSE – Отмена.

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

• S_OK — Диалог показан успешно.
• E_FAIL – Показ диалогов не поддерживается

Описание:

Выводит диалог с текстом, заданным параметром queryText, и кнопками ОК и Отмена.

Alert

Синтаксис:

HRESULT Alert(BSTR text)

Параметры:

• <queryText> Тип: BSTR. Текст сообщения.

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

• S_OK — Диалог показан успешно.
• E_FAIL – Показ диалогов не поддерживается

Описание:

Выводит простой диалог с кнопкой ОК.

Информация о платформе

Для получения информации о подключившем объект приложении, может использовать интерфейс IPlatformInfo, стандартный для COM Интерфейс IPlatformInfo унаследован от IUnknown

GetPlatformInfo

Синтаксис:

HRESULT GetPlatformInfo(AppInfo** info)

Параметры:

• <info>Тип AppInfo** - указатель на структуру с полями: AppVersion — Тип: BSTR, версия приложения, Application — Тип: перечисление, тип подключившего компоненту приложения, UserAgentInformation — Тип: BSTR, информация о браузере (только для веб-клиента)

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

• S_OK — выполнено успешно.
• E_FAIL - произошла ошибка.

Описание:

Запрашивает информацию о платформе. При подключении компоненты в веб-клиенте старой версии платформы, будет заполнено только поле Application структуры AppInfo.

GetAttachedInfo

Синтаксис:

HRESULT GetAttachedInfo(AttachedType** type)

Параметры:

• <type>Тип AttachedType** - тип подключения компоненты к платформе:
  • eAttachedIsolated = 0 - подключена изолированно,
  • eAttachedNotIsolated = 1 - подключена не изолированно.

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

• S_OK — выполнено успешно.
• E_FAIL - произошла ошибка.

Описание:

Запрашивает информацию о типе подключения компоненты.

Внешние события

При возникновении асинхронного события (например, считывания штрих-кода) объект может использовать интерфейс IAsyncEvent для создания внешнего события в "1С:Предприятии". Интерфейс IAsyncEvent унаследован от IUnknown. Все события помещаются в очередь и обрабатываются по порядку появления. Количество запоминаемых событий ограничено длиной очереди. При инициализации длина очереди устанавливается равной 1 и может быть изменена вызовом SetEventBufferDepth, а текущий размер очереди получен с помощью метода GetEventBufferDepth и. Для каждого объекта внешней компоненты поддерживается своя очередь событий. Обработка внешнего события производится предопределенной процедурой ОбработкаВнешнегоСобытия и обработчиками внешних событий в модулях форм.

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 – при очищении очереди произошла ошибка.

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

Описание:

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

Работа со строкой состояния

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

SetStatusLine

Синтаксис:

HRESULT SetStatusLine(BSTR bstrStatusText) 

Параметры:

• <bstrStatusText> Тип: BSTR. Текст строки состояния.

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

• S_OK — текст отображен в строке состояния.
• E_FAIL – неизвестная ошибка

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

Описание:

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

ResetStatusLine

Синтаксис:

HRESULT ResetStatusLine() 

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

• S_OK — строка состояния успешно переинициализирована.
• E_FAIL – неизвестная ошибка.

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

Описание:

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

Создание окон в среде "1С:Предприятия 8"

Внешние компоненты могут создавать свои окна для отображения различной информации, используя интерфейс IExtWndsSupport. Компонента может создавать два типа окон: модальные диалоги, немодальные диалоги.

Модальные диалоги

Модальные диалоги создаются самой компонентой, но при их создании необходимо в качестве родительского окна указать окно, возвращаемое методом GetAppMainFrame для того, чтобы диалог не воспринимался операционной системой как отдельная задача с кнопкой на полосе задач. Работа системы "1С:Предприятие" приостанавливается до завершения работы с диалогом.

Немодальные диалоги

Немодальные диалоги также создаются самой компонентой, но при их создании необходимо в качестве родительского окна указать окно, возвращаемое методом GetAppMDIFrame для того, чтобы диалог не воспринимался операционной системой как отдельная задача с кнопкой на полосе задач. Диалог не останавливает работу 1С:Предприятия и по сути аналогичен формам 1С:Предприятия. Однако следует учесть, что созданный диалог не входит в список открытых окон и не появляется на панели окон, поэтому использование таких диалогов не рекомендуется (вместо них можно использовать формы самого 1С:Предприятия).

В "1С:Предприятии 8" возможность создания окон сохранена в сокращенном виде для совместимости с существующими компонентами. Для отображения нестандартной информации в окнах "1С:Предприятия 8" рекомендуется использовать формы с элементами управления ActiveX или же Активные документы. Ниже приведены описания методов интерфейса IExtWndsSupport. Возможность работы с окнами отсутствует в Веб-клиенте.

GetAppMainFrame

Синтаксис:

HRESULT GetAppMainFrame(HWND* pHWnd) 

Параметры:

• <pHWnd> Тип: HWND*. Указатель на дескриптор окна

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

• S_OK - операция завершена успешно.
• E_FAIL - произошла ошибка.

Описание:

Возвращает дескриптор основного окна 1С:Предприятия.

GetAppMDIFrame

Синтаксис:

HRESULT GetAppMDIFrame(HWND* pHWnd) 

Параметры:

• <pHWnd> Тип: HWND*. Указатель на дескриптор окна

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

• S_OK - успешно.
• E_FAIL - произошла ошибка.

Описание:

Возвращает дескриптор активного окна 1С:Предприятия.

Доступ к "1С:Предприятию" через механизм OLE Automation

Версия технологии: 2.0

Переданный в методе Init указатель на IDispatch позволяет получить доступ к "1С:Предприятию" через механизм OLE Automation. Из полученного указателя можно получить свойство AppDispatch, доступное только для чтения. Это свойство содержит указатель на IDispatch 1C:Предприятия (не путайте с переданным в Init). При подключении компоненты к Веб-клиенту, свойство AppDispatch будет недоступно. Это надо учитывать при разработке компонент.

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

Доступ к методам интерфейсов 1С:Предприятия через OLE Automation

Visual Basic имеет ограниченные возможности по работе с различными интерфейсами. Наиболее "естественным" механизмом для Visual Basic является работа с OLE Automation, для этого в VB используется тип Object, который представляет собой указатель на IDispatch. Поэтому "1С:Предприятие" предоставляет возможность использовать механизм OLE Automation, передавая указатель на IDispatch в методе Init и обеспечивая вызовы методов вышеперечисленных интерфейсов через OLE Automation.

Методы и свойства, доступные через OLE Automation

Версия технологии: 1.0

RegisterProfileAs(<ИмяСпискаПараметров>)

Read(<ИмяПеременной>,<СсылкаНаVARIANT>)

Write(<ИмяПеременной>,<СсылкаНаVARIANT>)

SetEventBufferDepth(<ДлинаОчередиСобытий>)

GetEventBufferDepth(<СсылкаНаДлинуОчереди>)

ClearEventBuffer()

ExternalEvent(<СтрокаИсточникСобытия>,<СтрокаНаименованиеСобытия>,<СтрокаПараметрыСобытия>)

AddError(<КодСообщения>,<СтрокаИсточникСообщения>,<СтрокаОписаниеСообщения>,<КодОшибки>)

SetStatusLine(<СтрокаСостояния>)

ResetStatusLine()

Версия технологии: 2.0 (дополнительно к 1.0)

Внимание! Перечисленные ниже методы и свойства недоступны при работе с Веб-клиентом)

• свойство AppDispatch
• GetAppMainFrame(<Указатель на дескриптор окна>)
• GetAppMDIFrame(<Указатель на дескриптор окна>)

Особенности разработки компонент с использованием COM

Компоненты, разработанные с использованием технологии COM, могут быть изначально не установлены на компьютере пользователя. Метод ПодключитьВнешнююКомпоненту(<МестонахожденияКомпоненты>, <ИмяМетки>, ТипВнешнейКомпоненты.COM), получает из информационной базы файл внешней компоненты, если последняя находится там, и вызывает функцию регистрации объектов компоненты DllInstall. Если регистрация "для пользователя" завершилась неудачно, то вызывается функция DllRegisterServer. Если пользователь ограничен в правах, то регистрация и подключение внешней компоненты может закончится неудачей. Разработчик должен предусмотреть возможность регистрации компоненты для пользователя, под его текущими правами. Если внешняя компонента имеет свой инсталлятор, то она должна регистрироваться для компьютера.

Подготовка внешних компонент к работе с Веб-клиентом

Взаимодействие внешних компонент с Веб-клиентом осуществляется при помощи расширений. В примерах приведены проекты для построения расширений для Firefox и Google Chrome, Internet Explorer, Safari. В целях безопасности, каждое расширение может работать только с одной компонентой, заданной на этапе компиляции. Каждое расширение состоит из собственно внешней компоненты и адаптера браузера. Внешней компонентой может быть уже созданная компонента по технологии COM.

Для ОС Windows, Mac OS X, все исполняемые файлы, входящие в установочный пакет, и сам установочный пакет, должны быть подписаны цифровой подписью разработчика. Установочные пакеты ОС Windows должны подписываться двойной подписью (sha1 и sha256), кроме пакетов msi, согласно рекомендации Microsoft.

Скриптовый язык программирования браузеров является однопоточным. В связи с этим следует избегать обратных вызовов из не основного потока в компоненте. В других потоках будут работать только методы ExternalEvent, SetStatusLine, ResetStatusLine. Следует учитывать эти особенности при разработке внешней компоненты.

Библиотеки для браузеров для ОС Windows используют компилятор от Visual Studio 2017 с поддержкой Windows XP.

Для Mozilla Firefox и Google Chrome, начиная с версии платформы 8.3.6, используется один адаптер.

Внешние компоненты для Internet Explorer

Создание адаптера для Internet Explorer

За основу при создании расширения разработчик может взять проект AddInIE из каталога example. В idl-файле нужно изменить название библиотеки (например: library MyComponentIELib) и uuid coclass'ов и библиотеки. Все изменения, которые должен сделать разработчик в этом файле, помечены комментарием "//change". Uuid интерфейсов и их имена изменять не нужно. Желательно переименовать название проекта (например: MyComponentIE). В файле config.cpp - изменить название включаемого файла "AddInIE_i.h" на сгенерированное средой разработки по файлу idl, и изменить значения текстовых переменных на имена coclass’ов библиотеки (например: " MyComponentIE.AddInServiceEx"). Переменной LIBID_AddInWebLib – присвоить значение LIBID Вашей библиотеки. Также в переменной nameFileComponent указать имя внешней компоненты (например: AddInNative.dll), а в nameFilePrj – имя выходного файла проекта расширения (например: MyComponentIE.dll). Расширение для Internet Explorer является COM-объектом, поэтому разработчик должен учитывать Особенности разработки компонент с использованием COM.

Создание установочного пакета для Internet Explorer

Начиная с версии 1С:Предприятия 8.3.12, установочный пакет для Internet Explorer для Windows создается в формате EXE. В каталоге example\AddInIESetup содержится проект NSIS, собирающий пакет установки для примера компоненты. Для сборки проекта, должен быть установлен NSIS. Для каждой компоненты, следует установить свои значения в файле AddInIESetup.nsh. Если предполагается использование компоненты с более ранними версиями 1С:Предприятия, то разработчик должен собирать установочный пакет в виде cab-файла. Скрипт построения cab-файла приведен в example\PackageIE\buildcab.bat.

Внешние компоненты для Google Chrome и Mozilla Firefox

Создание адаптера для Google Chrome и Mozilla Firefox

Адаптер внешней компоненты для Chrome представляет консольное приложение. Адаптер, при установке, регистрирует в браузере одно или несколько уникальных имен расширений. Рекомендуется начинать имя расширения с "com." и включать в него номер версии компоненты, например "com.YourCompanyName.YouAddInName.1". В случае, если выпускается новая версия компоненты, номер версии в имени следует увеличить, в противном случае веб-клиент будет продолжать пользоваться старой версией компоненты.

Предположим, что в конфигурации используется компонента, у которой имя - "com.YourCompanyName.YouAddInName.3". Разработчик компоненты выпускает новую версию компоненты. Для включения ее в конфигурацию нужно пересобрать адаптеры для Chrome, изменив в них имя на "com.YourCompanyName.YouAddInName.4". Затем пересобрать установочные пакеты и включить их в архив, загружаемый в конфигурацию. Также, нужно изменить файл манифеста архива, изменив в нем имя на com.YourCompanyName.YouAddInName.4. После чего загрузить архив в конфигурацию. Что происходит при запуске веб-клиента с новой конфигурацией на машине, на которой ранее была установлена предыдущая версия компоненты? Веб-клиент получает из конфигурации информацию о том, что имя компоненты - "com.YourCompanyName.YouAddInName.4". Такое имя расширения в браузере не зарегистрировано, поэтому старая версия компоненты использована не будет. Чтобы начать использование компоненты пользователь должен выполнить ее установку. Старая версия компоненты при этом не удаляется и остается доступной для использования с более ранними конфигурациями.

За основу при создании расширения разработчик может взять проект AddInChrome из каталога example. В файле config.cpp нужно изменить значения переменных nameFilePrj, nameFileComponent. nameFilePrj должно содержать имя файла адаптера (например, AddInChrWin32.exe), nameFileComponent - имя файла внешней компоненты (например, AddInNative.dll).

В адаптерах использована библиотека jsoncpp (лицензия).

Создание установочного пакета для Google Chrome

Установочный пакет для Chrome для Windows создается в формате EXE.

В состав установочного пакета должны входить:

• файл внешней компоненты
• файл адаптера внешней компоненты
• файл манифеста (в формате json)

Файл манифеста должен иметь вид:

{
"name": "com.YourCompanyName.YouAddInName",
"description": "Description of add-in for Chrome and Firefox",
"path": "AddInChr.exe",
"type": "stdio",
"allowed_origins": [
"chrome-extension://pbhelknnhilelbnhfpcjlcabhmfangik/"
]
}

В файле манифеста следует изменить:

Остальные атрибуты менять нельзя.

Во время установки пакет должен скопировать файлы на диск компьютера и зарегистрировать расширение как плагин браузера в системном реестре. В реестре нужно создать ветку HKCU\Software\Google\Chrome\NativeMessagingHosts\com.YourCompanyName.YouAddInName (вместо YourCompanyName и YouAddInName подставьте свои значения), в которой создать параметр по умолчанию строкового типа, который указывает полный путь к файлу манифеста. Содержимое атрибута 'name' манифеста должно совпадать с наименованием ветки реестра.

Пакет должен быть подписан цифровой подписью разработчика (SHA1+SHA256).

В папке example\AddInChromeSetup содержится проект NSIS, собирающий пакет установки для примера компоненты. Для сборки проекта, должен быть установлен NSIS. Для каждой компоненты, следует установить свои значения в файле AddInChromeSetup.nsh.

Установочный пакет для Chrome и Firefox под Linux создается в формате самораспаковывающегося архива. Архив содержит бинарные модули внешней компоненты, адаптера, а также файл манифеста. Для сборки архива, можно воспользоваться утилитой makeself. Скрипт из архива должен скопировать манифест в каталог ~/.config/google-chrome/NativeMessagingHosts/, а исполняемые файлы — в другое место.

Этот же пакет используется и для установки компоненты для браузеров Яндекс.Браузер, Microsoft Edge, Chromium-Gost.

Внешние компоненты для Safari

Создание адаптера для Safari

Адаптер внешней компоненты для Safari представляет собой NPAPI-плагин. NPAPI-плагин регистрирует в браузере один или несколько MIME media type, которые он обслуживает. При создании новой компоненты разработчик должен выбрать для нее MIME media type, который будет служить ее уникальным идентификатором. Рекомендуется начинать MIME media type с application/ и включать в него номер версии компоненты, например application/my-component-1. При выборе MIME media type нужно позаботиться об отсутствии конфликтов с зарегистрированными MIME media type. В случае, если выпускается новая версия компоненты, номер версии в MIME media type следует увеличить, в противном случае веб-клиент будет продолжать пользоваться старой версией компоненты.

Предположим, что в конфигурации используется компонента, у которой MIME media type - application/my-component-3. Разработчик компоненты выпускает новую версию компоненты. Для включения ее в конфигурацию нужно пересобрать адаптеры для Safari, изменив в них MIME media type на application/my-component-4. Затем пересобрать установочные пакеты и включить их в архив, загружаемый в конфигурацию. Также, нужно изменить файл манифеста архива, изменив в нем MIME media type на application/my-component-4. После чего загрузить архив в конфигурацию. Что происходит при запуске веб-клиента с новой конфигурацией на машине, на которой ранее была установлена предыдущая версия компоненты? Веб-клиент получает из конфигурации информацию о том, что MIME media type компоненты - application/my-component-4. Такой MIME media type в браузере не зарегистрирован, поэтому старая версия компоненты использована не будет. Чтобы начать использование компоненты пользователь должен выполнить ее установку. Старая версия компоненты при этом не удаляется и остается доступной для использования с более ранними конфигурациями.

За основу при создании расширения разработчик может взять проект AddInNPAPI из каталога example. В файле AddInNPAPI.cpp нужно изменить значения переменных nameFilePrj, nameFileComponent и mimeType. nameFilePrj должно содержать имя файла адаптера (например, AddInNPAPI.dyn), nameFileComponent - имя файла внешней компоненты (например, AddInNative.dyn). mimeType содержит MIME media type компоненты.

Адаптер для Safari под Mac OS X не требует сборки, он поставляется в собранном виде в папке lib (1CEAdnWebNPAPISafOSX.bundle). Внешнюю компоненту под Mac OS также нужно собрать в виде bundle. Рекомендуется собирать 32/64-bit Universal модуль, содержащий по крайней мере i386 и x86_64 архитектуры. В папке example/NativeAPI/MacBuild содержится проект XCode, собирающий пример компоненты под Mac OS.

Создание установочного пакета для Safari

Под Mac OS X пакет создается при помощи программы PackageMaker в формате PKG. Пакет должен быть подписан цифровой подписью разработчика (если не предполагается установка компоненты на версии Mac OS X 10.4 Tiger и более ранние).

Для создания пакета нужно выполнить следующие действия:

1. Скопировать из папки lib 1CEAdnWebNPAPISafOSX.bundle в другую папку. Переименовывать, сохраняя расширение .bundle.

2. Найти в содержимом bundle файл Info.plist, открыть его для редактирования. В файле нужно изменить MIME media type на используемый для Вашей компоненты, а также изменить описание расширения и другие параметры.

3. Внутри папки Contents создать папку PlugIns. В эту папку скопировать bundle собранной под Mac OS внешней компоненты. Полученный bundle адаптера с компонентой внутри должен устанавливаться в папку /Library/Internet Plug-Ins.

4. Собрать установочный пакет. Для этого следует использовать утилиту PackageMaker, входящую в состав XCode. При установке пакет должен только скопировать bundle в папку /Library/Internet Plug-Ins.

Подготовка внешних компонент для загрузки в конфигурацию

Внешние компоненты могут быть упакованы в ZIP-архив. Для работы с веб-клиентом, тонким клиентом и для мобильной платформы – это обязательное условие.

В "1C:Предприятие" для персонального компьютера в него должны войти:

• собственно компоненты для ОС Windows (x86, x86_64), GNU/Linux (x86, x86_64, ARM64, E2K), MacOS (x86_64),
• созданные расширения для Internet Explorer (x86, x86_64), Mozilla Firefox и Google Chrome (Windows x86 и x86_64, GNU/Linux x86, x86_64, ARM64, E2K, MacOS x86_64).

Для мобильной платформы "1C:Предприятие" в него должны войти компоненты для ОС Windows Runtime (x86, x86_64, ARM), ОС Android (x86, x86_64, ARM, ARM64, а также файл *.apk для кода Java - опционально) и ОС iOS (ARM и ARM64, объединенные в единый универсальный файл). Для ОС iOS требуется наличие как динамической библиотеки, так и статической. В составе архива включается файл MANIFEST.XML с описанием содержимого. Для мобильной платформы "1C:Предприятие" могут также опционально присутствовать следующие файлы:

• IOS_MANIFEST_EXTENSIONS.XML (ОС iOS) для описания разрешения использования дополнительных подсистем (framework), если они необходимы;
• ANDROID_MANIFEST_EXTENSIONS.XML (ОС Android) для описания изменений в AndroidManifest.xml, если они необходимы;
• WINDOWS_RT_MANIFEST_EXTENSIONS.XML (ОС Windows Runtime) для описания изменений в AppxManifest.xml, если они необходимы.

В "1С:Предприятие" для персонального компьютера загрузка архивов внешних компонент в конфигурацию осуществляется в макеты с типом "Внешняя компонента" или "Двоичные данные".

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

Описание файла MANIFEST.XML

<?xml version="1.0" encoding="UTF-8" ?>
<bundle xmlns="http://v8.1c.ru/8.2/addin/bundle" name="YouComponentName">
<component os="Windows" path="AddIn_ChrWindows_x86.exe" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="i386" client="Firefox" clientVersion="40.*" />
<component os="Windows" path="AddIn_ChrWindows_x86_64.exe" type="plugin" object="com.YourCompanyName.YouExtensionName.1" arch="x86_64" client="Firefox" clientVersion="40.*" />
<component os="Linux" path="AddIn_ChrLinux_x86.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="i386" client="Firefox" clientVersion="40.*" />
<component os="Linux" path="AddIn_ChrLinux_x86_64.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="x86_64" client="Firefox" clientVersion="40.*" />

<component os="Linux" path="AddIn_ChrLinux_ARM64.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="ARM64" client="Firefox" clientVersion="40.*" />

<component os="Linux" path="AddIn_ChrLinux_E2KV4-8C.sh" type="plugin"
object="com.YourCompanyName.YouAddInName.1" arch="E2K" client="Firefox"
clientVersion="40.*" />
<component os="Windows" path="Addin_IEWindows_x86.exe" type="plugin" object="MyComponentIE.AddInServiceEx" arch="i386" client="MSIE" />
<component os="Windows" path="AddIn_IEWindows_x86_64.exe" type="plugin" object="MyComponentIE.AddInServiceEx" arch="x86_64" client="MSIE" />
<component os="Windows" path="AddIn_ChrWindows_x86.exe" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="i386" client="Chrome" />
<component os="Windows" path="AddIn_ChrWindows_x86_64.exe" type="plugin" object="com.YourCompanyName.YouExtensionName.1" arch="x86_64" client="Chrome" />
<component os="Linux" path="AddIn_ChrLinux_x86.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="i386" client="Chrome" />
<component os="Linux" path="AddIn_ChrLinux_x86_64.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="x86_64" client="Chrome" />

<component os="Linux" path="AddIn_ChrLinux_ARM64.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="ARM64" client="Chrome" />

<component os="Linux" path="AddIn_ChrLinux_E2KV4-8C.sh" type="plugin"
object="com.YourCompanyName.YouAddInName.1" arch="E2K" client="Chrome" />
  <component os="MacOS" path="AddIn_ChrMacOS_x86_64.pkg" type="plugin" object="com.YourCompanyName.YouExtensionName.1" arch="x86_64" client="Chrome" />

<component os="Windows" path="AddIn_ChrWindows_x86.exe" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="i386" client="AnyChromiumBased" />
<component os="Windows" path="AddIn_ChrWindows_x86_64.exe" type="plugin" object="com.YourCompanyName.YouExtensionName.1" arch="x86_64" client="AnyChromiumBased" />
<component os="Linux" path="AddIn_ChrLinux_x86.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="i386" client="AnyChromiumBased" />
<component os="Linux" path="AddIn_ChrLinux_x86_64.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="x86_64" client="AnyChromiumBased" />

<component os="Linux" path="AddIn_ChrLinux_ARM64.sh" type="plugin" object="com.YourCompanyName.YouAddInName.1" arch="ARM64" client="AnyChromiumBased" />
  <component os="MacOS" path="AddIn_ChrMacOS_x86_64.pkg" type="plugin" object="com.YourCompanyName.YouExtensionName.1" arch="x86_64" client="AnyChromiumBased" />

<component os="Linux" path="AddIn_ChrLinux_E2KV4-8C.sh" type="plugin"
object="com.YourCompanyName.YouAddInName.1" arch="E2K" client="AnyChromiumBased"
/>
<component os="Windows" path="AddInNative_Win32.dll" type="native" arch="i386" />
<component os="Windows" path="AddInNative_Win64.dll" type="native" arch="x86_64" />
<component os="Linux" path="AddInNative_Lin32.so" type="native" arch="i386" />
<component os="Linux" path="AddInNative_Lin64.so" type="native" arch="x86_64" />

<component os="Linux" path="AddInNative_LinARM64.so" type="native" arch="ARM64" />

<component os="Linux" path="AddInNative_LinE2KV4-8C.so" type="native"
arch="E2K" />
<component os="MacOS" path="AddInNative_MacOS64.dylib" type="native" arch="x86_64" />
<component os="iOS" path="AddInNative_iOS.dylib" type="native" arch="Universal" buildType="developer" />
<component os="iOS" path="AddInNative_iOS.a" type="native" arch="Universal" buildType="release" />
<component os="Android" path="libAddInNative_Android_i386.so" type="native" arch="i386" codeType="c++" />
<component os="Android" path="AddInNative_Android.apk" type="native" arch="i386" codeType="java" />
<component os="Android" path="libAddInNative_Android_x64.so" type="native" arch="x86_64" codeType="c++" />
<component os="Android" path="AddInNative_Android.apk" type="native" arch="x86_64" codeType="java" />
<component os="Android" path="libAddInNative_Android_ARM.so" type="native" arch="ARM" codeType="c++" />
<component os="Android" path="AddInNative_Android.apk" type="native" arch="ARM" codeType="java" />
<component os="Android" path="libAddInNative_Android_ARM64.so" type="native" arch="ARM64" codeType="c++" />
<component os="Android" path="AddInNative_Android.apk" type="native" arch="ARM64" codeType="java" />
<component os="WindowsRuntime" path="AddInNative_WinRT_ARM.dll" type="native" arch="ARM" />
<component os="WindowsRuntime" path="AddInNative_WinRT_x64.dll" type="native" arch="x86_64" />
<component os="WindowsRuntime" path="AddInNative_WinRT_Win32.dll" type="native" arch="i386" />
</bundle>,

Где:

• Name – имя внешней компоненты (требуется только для мобильной версии платформы); должно быть уникальным, сформированным по правилам описанным в разделе "Правила формирования имени внешней компоненты";
• Os – операционная система (Windows, Linux, MacOS, WindowsRuntime, Android, iOS);
• Path – название файла в архиве;
• Type – тип компоненты (plugin – расширение для браузера, native – Native-компонента, com – COM-компонента). Для внешней компоненты мобильной платформы доступно только значение native;
• Object – название объекта, который будет создаваться браузером;
• Arch – для какой архитектуры процессора должна использоваться компонента:
  • i386 – 32-х разрядный процессор,
  • x86_64 – 64-х разрядный процессор,
  • ARM – 32-х разрядный процессор с архитектурой ARM;
  • ARM64 – 64-х разрядный процессор с архитектурой ARM;
  • E2K – 64-х разрядный процессор с архитектурой Эльбрус-8С;
  • Universal – универсальный бинарный файл для операционной системы iOS, содержащий исполняемый код для ARM и ARM64;
• Client – используется для Веб-клиента: указывает для какого браузера компонента (MSIE – Internet Explorer, Firefox - Mozilla Firefox, YandexBrowser - Яндекс.Браузер, Edge - Microsoft Edge, Chrome - Google Chrome, ChromiumGost - Chromium-Gost, AnyChromiumBased - все браузеры, построенные на основе исходных текстов браузера Chromium. Для совместимости с более ранними версиями платформы, рекомендуется добавить отдельную запись для браузера Chrome.);
• clientVersion – версия браузера. Обязательна для браузера Mozilla Firefox;
• buildType – тип целевого приложения (developer – приложение, загружающее файл предназначено для разработчика; release – для публикуемой версии приложения). Параметр применяется для ОС iOS;
• codeType – язык программирования библиотеки (c++ - библиотека написана на c++; java – библиотека написана по технологии Java Native Interface). Параметр применяется для ОС Android.

Соответствие версий clientVersion, указанных в манифесте и версий браузера Mozilla Firefox:

При изменении внешних компонент (новый релиз, исправление ошибок и т.д.) новую версию нужно добавлять к имени файла. Например: AddInNative_1_1.so. Это правило не распространяется на расширения для браузеров. Для них должно быть изменено название object.

Обратите внимание, что записи для Google Chrome и Mozilla Firefox ссылаются на один и тот же установочный пакет.

Описание файлов IOS_MANIFEST_EXTENSIONS.XML

Файл IOS_MANIFEST_EXTENSIONS.XML используется сборщиком только для ОС iOS. Файл необязателен. Предназначен для внесения дополнительных изменений в мобильное приложение:

• позволяет включить использование собираемому приложению необходимых для внешней компоненты подсистем (framework);
• позволяет включить в Info.plist дополнительные пары ключ/значение.

Формат рассмотрим на примере:

<?xml version="1.0" encoding="UTF-8"?>
<root>

	<!-- Секция подключения framework-ов -->
	<Additions>
        
		<framework name="System/Library/Frameworks/CoreMotion.framework"/>
		<framework name="usr/lib/libgll.dylib"/>
		
	</Additions>

	<!-- Секция добавления значений в Info.plist -->
	<Info_plist>
		<key>CFLanguage</key>
		<dict>
			<key>CFListLanguage</key>
			<array>
				<string>en</string>
				<string>ru</string>
				<string>fr</string>
			</array>
		</dict>
	</Info_plist>
</root>

После стандартного заголовка XML следует тег <root>.

Разрешается добавлять информацию только в теги <Additions> и <Info_plist>. Теги могут быть в любой очередности.

Теги <framework> в атрибуте name="…" указывают сборщику полный путь и наименование подсистемы.

Все содержимое тега (тегов) <Info_plist> без анализа и изменений вносится сборщиком в корневой тег <dict></dict> файла Info.plist.

Описание файла ANDROID_MANIFEST_EXTENSIONS.XML

Файл ANDROID_MANIFEST_EXTENSIONS.XML используется сборщиком только для ОС Android. Предназначен для внесения изменений в манифесте AndroidManifest.xml, например добавления прав, необходимых для внешней компоненты к определенным компонентам или функциональности данного приложения. Файл необязателен и его отсутствие расценивается сборщиком как отсутствие дополнительных изменений в AndroidManifest.xml.

Формат рассмотрим на примере:

<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:android="http://schemas.android.com/apk/res/android">

<!--uses-permission android:name="android.permission.WAKE_LOCK"/-->

<uses-permission android:name="%application.package%.permission.MAPS_RECEIVE"/>

<target xpath="/manifest">

	<uses-feature
	
		android:name="android.hardware.sensor.accelerometer
	
		android:required="true"/>

</target>

</root>

После стандартного заголовка XML следует тег <root> с фиксированным атрибутом. Тег <root> аналогичен тегу <manifest> в файлах AndroidManifest.xml.

Строки внутри тега <root> добавляются в тег <manifest> манифеста Android без изменения и анализа, за исключением тегов <target>.

Все что находится в тегах <target> вставится в указанную в атрибуте xpath="…" часть AndroidManifest.xml.

Есть возможность локализовать влияние строк на конкретные пакеты указав "%application.package%. ...".

Разрешается добавлять информацию только в тег <manifest> и </manifest/application> (файлов AndroidManifest.xml).

Описание атрибутов для uses-permission, uses-feature и т.п. можно найти в документации разработчика Android.

Не рекомендуется добавлять в теги uses-permission атрибуты, указывающие максимальную версию SDK. Это может привести к конфликтам в случае сборки приложений с несколькими внешними компонентами.

Описание файла WINDOWS_RT_MANIFEST_EXTENSIONS.XML

Файл WINDOWS_RT_MANIFEST_EXTENSIONS.XML используется сборщиком для ОС Windows Runtime. Предназначен для внесения изменений в манифесте AppxManifest.xml, например добавления прав, необходимых для внешней компоненты к определенным компонентам или функциональности данного приложения. Файл необязателен и его отсутствие расценивается сборщиком как отсутствие дополнительных изменений в настройках разрешений.

Формат рассмотрим на примере:

<?xml version="1.0" encoding="UTF-8"?>
<root>

<Additions>

  	<target xpath="/Package/Capabilities/Capability[@Name='musicLibrary']"/>

  	<target xpath="/Package/Capabilities/DeviceCapability[@Name='proximity']"/>

</Additions>

</root>

После стандартного заголовка XML следует тег <root>.

Разрешается добавлять информацию только в тег <Additions>.

Теги <target> в атрибуте xpath="…" указывают сборщику пункт назначения параметров "Name='XXXXX'" в файле AppxManifest.xml.

Описание тегов <Capability> и <DeviceCapability> можно найти в документации разработчика для Windows.

Правила формирования имени внешней компоненты для мобильной платформы "1C:Предприятие"

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

Имя внешней компоненты должно состоять из латинских букв и/или цифр и не может включать пробелы. Разрешается также использования знака подчеркивания (_). Первым символом может быть только буква или символ подчеркивания (_). Имя компоненты чувствительно к регистру клавиатуры.

Если программа создается в организации, у которой есть свой интернет-сайт, и доменное имя такого сайта, например, 1c.com, то имя внешней компоненты должно начинаться с этих же слов, выписанных в обратном порядке: com_1c. Точки заменяются на знак подчеркивания (_). Далее через (_) следует имя самой внешней компоненты.

Если имя сайта противоречит требованиям к имени внешней компоненты, то можно предпринять следующие шаги:

• если в имени стоит запрещенный символ, например тире, то его можно заменить знаком подчеркивания;
• если имя совпадает с зарезервированным словом, то можно в конце добавить знак подчеркивания;
• если имя начинается с цифры, можно вначале добавить знак подчеркивания.

Ограничения в работе внешних компонент

Разработчик должен учитывать, что внешняя компонента может быть подключена как в оконном приложении (тонкий клиент, толстый клиент), так и в консольном (например: на сервере 1С:Предприятия или в веб-клиенте), где может отсутствовать главное окно и оконная система, очередь сообщений, таймеры, использующие очередь сообщений, нет возможности поставить локальный хук, например, на клавиатуру. В этом случае, разработчик компоненты должен самостоятельно позаботиться о создании необходимого окружения для корректной работы внешней компоненты

В случае использования технологии внешних компонент в мобильной платформе запрещен вызов методов

• bool ADDIN_API Confirm(const WCHAR_T* queryText, tVariant* retVal);
• bool ADDIN_API Alert(const WCHAR_T* text);

из системного потока, т.к. показ модальных окон в таком случае может вызвать "зависание" приложения.

Для Windows Runtime не реализована возможность загрузки динамических библиотек из Web-публикации.

Для iOS возможность загрузки динамических библиотек из Web-публикации разрешена со стороны ОС только до версии iOS 9.3.5 включительно.

Описание примеров

В поставку настоящей методики входят примеры реализации внешних компонент, разработанных с использованием технологий Native API и СОМ, расширений для Mozilla Firefox, Google Chrome и Internet Explorer. Кроме примера в поставку включен шаблон, позволяющий упростить создание компоненты "с нуля".

Реализации компонент максимально приближены друг к другу (одинаковые идентификаторы, названия и т.д.), что упрощает процесс освоения и разбора различных реализаций.

В связи со спецификой использования, пример для мобильной платформы отличается от остальных. В нем реализуется упрощенный шагомер. Располагается в каталоге \example\NativeAPIMobile\.

Для полной сборки примеров для персонального компьютера, разработчику понадобится CMake, версии не ниже 3.6, NSIS для сборки инсталляторов для ОС Windows, makeself для сборки инсталляторов для ОС GNU/Linux.

Компоненты реализуют следующие свойства и методы:

Примеры внешней компоненты "1С:Предприятие" для персонального компьютера

Свойства

Включен (IsEnabled)

Использование: Чтение и запись.

Описание: Тип: Булево. Содержит состояние компоненты.

ЕстьТаймер (IsTimerPresent)

Использование: Чтение.

Описание: Тип: Булево. Определяет наличие у компоненты таймера.

Методы

Включить (Enable)

Синтаксис:

Включить()

Описание:

Включает объект компоненты.

Выключить (Disable)

Синтаксис:

Выключить()

Описание:

Выключает объект компоненты.

ПоказатьВСтрокеСтатуса (ShowInStatusLine)

Синтаксис:

ПоказатьВСтрокеСтатуса(<Текст>)

Параметры:

• Текст. Текст, выводимый в строке статуса.

Описание:

На 5 секунд выводит в строку статуса полученный текст.

ВключитьТаймер (StartTimer)

Синтаксис:

ВключитьТаймер()

Описание:

Включает таймер компоненты. Каждую секунду компонента посылает сообщение "1С:Предприятию" с параметрами "Component", "Timer" и строкой счетчика системных часов.

ВыключитьТаймер (StopTimer)

Синтаксис:

ВыключитьТаймер()

Описание:

Выключает таймер компоненты.

Кроме того, компонента, разработанная с использованием Native API, дополнительно реализует метод

ЗагрузитьКартинку(LoadPicture)

Синтаксис:

ЗагрузитьКартинку (<ИмяФайла>)

Параметры:

• ИмяФайла. Имя файла с изображением.

Описание:

Загружает изображение из указанного файла и передает его в "1С:Предприятие".

ПоказатьСообщение

Синтаксис:

ПоказатьСообщение ()

Параметры:

Нет

Описание:

Выводит сообщение о версии платформы.

Пример внешней компоненты для мобильной платформы "1С:Предприятие"

Свойства

Включен (IsEnabled)

Использование: Чтение.

Описание: Тип: Булево. Содержит состояние компоненты.

Методы

Включить (Enable)

Синтаксис:

Включить()

Описание:

Включает объект компоненты. При этом запускается отсчет шагомера и отслеживание типа движения с акселерометрами.

При изменении количество шагов компонента генерирует событие 1С:Предприятию с параметрами "StepCounter", "OnChange", "_".

Выключить (Disable)

Синтаксис:

Выключить()

Описание:

Выключает объект компоненты. При этом количество шагов обнуляется, значение типа движения и акселерометры не отслеживаются.

ПолучитьКоличествоШагов (GetStepCount)

Синтаксис:

ПолучитьКоличествоШагов()

Тип:

Целочисленное значение.

Описание:

Возвращает текущее вычисленное значение шагов оператора с момента крайнего вызова метода Включить().

ПолучитьТипДвижения (GetMovementType)

Синтаксис:

ПолучитьТипДвижения()

Тип:

Целочисленное значение.

Описание:

Возвращает индекс текущего типа движения

0 - неопределено,

1 – неподвижно,

2 - прогулка,

3 - бег,

4 - автомобиль,

5 - велосипед.

ПолучитьУгловоеПоложениеУстройства (GetDeviceOrientation)

Синтаксис:

ПолучитьУгловоеПоложениеУстройства (<Плоскость>)

Параметры:

Плоскость. Плоскость декартовой системы координат запрашиваемых данных. (0 – плоскость XOY; 1 – плоскость XOZ; 2 – плоскость YOZ)

Тип:

Вещественное значение.

Описание:

Возвращает текущие значения углового положения устройства по плоскостям земной системы координат в радианах.

ПоказатьУгловоеПоложениеУстройства (ShowDeviceOrientation)

Синтаксис:

ПоказатьУгловоеПоложениеУстройства()

Описание:

Выводит сообщение с информацией о текущих значениях углового положения устройства по плоскостям земной системы координат в радианах.

ПолучитьОписаниеПоследнейОшибки (GetDescriptionLastError)

Синтаксис:

ПолучитьОписаниеПоследнейОшибки()

Описание:

Возвращает текст последней ошибки, произошедшей во внешней компоненте.

События

ОбработкаВнешнегоСобытия (ExternEventProcessing)

Синтаксис:

Процедура ОбработкаВнешнегоСобытия (Источник, Событие, Данные)
    
	Если Источник = "StepCounter" И Событие = "OnChange" Тогда

            . . .

   КонецЕсли

КонецПроцедуры

Примечание: <Данные> - для приведенного примера равно "_".

Описание:

Возникает при посылке внешней компонентой сообщения об изменении количества шагов.

Средства разработки

В качестве средств разработки можно применять:

• Microsoft Visual C++,
• Delphi,
• C++ Builder,
• Xcode,
• Eclipse,
• gcc,
• CMake.

Примеры создания внешних компонент находятся в каталоге \1CIts\EXE\VNCOMPS

Примеры для работы с "1С:Предприятием 8.3" располагаются в подкаталоге VNCOMP83.

ВЫ МОЖЕТЕ ПРЯМО СЕЙЧАС СКОПИРОВАТЬ ПРИМЕРЫ ВНЕШНИХ КОМПОНЕНТ
НА ЖЕСТКИЙ ДИСК ВАШЕГО КОМПЬЮТЕРА

Копировать