Технологія створення зовнішніх компонентів

Вступ

Структура каталогів

Створення компонентів із використанням технології Native API

GetClassNames

GetClassObject

DestroyObject

SetPlatformCapabilities

Init

setMemManager

GetInfo

Done

RegisterExtensionAs

GetNProps

FindProp

GetPropName

GetPropVal

SetPropVal

IsPropReadable

IsPropWritable

GetNMethods

FindMethod

GetMethodName

GetNParams

GetParamDefValue

HasRetVal

CallAsProc

CallAsFunc

SetLocale

Інтерфейс "1С:Підприємства"

AddError

RegisterProfileAs

Read

Write

SetEventBufferDepth

GetEventBufferDepth

ExternalEvent

CleanEventBuffer

SetStatusLine

ResetStatusLine

GetInterface

Confirm

Alert

Синтаксис

GetPlatformInfo

Відповідність типів tVariant і "1С:Підприємства"

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

Створення компонентів із використанням технології COM

Ініціалізація та вивантаження компоненти

Init

Done

GetInfo

Розширення вбудованої мови

RegisterExtensionAs

GetNProps

FindProp

GetPropName

GetPropVal

SetPropVal

IsPropReadable

IsPropWritable

GetNMethods

FindMethod

GetMethodName

GetNParams

GetParamDefValue

HasRetVal

CallAsProc

CallAsFunc

Локалізація

Використання типу COM VARIANT під час обміну даними

COM-інтерфейси "1C:Підприємства"

RegisterProfileAs

AddError

Confirm

Alert

Опис:

Інформація про платформу

GetPlatformInfo

SetEventBufferDepth

GetEventBufferDepth

ExternalEvent

CleanBuffer

SetStatusLine

ResetStatusLine

Створення вікон у середовищі "1С:Підприємства 8"

GetAppMainFrame

GetAppMDIFrame

Доступ до "1С:Підприємства" через механізм OLE Automation

Методи та властивості, доступні через OLE Automation:

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

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

Зовнішні компоненти для Mozilla Firefox

Зовнішні компоненти для Internet Explorer

Зовнішні компоненти для Google Chrome

Зовнішні компоненти для Safari

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

Опис прикладів

Вимкнути (Disable)

ПоказатиУРядкуСтану (ShowInStatusLine)

УвімкнутиТаймер (StartTimer)

ВимкнутиТаймер (StopTimer)

ЗавантажитиКартинку(LoadPicture)

Засоби розробки та приклади

 

• Вступ
• Структура каталогів
• Створення компонентів із використанням технології Native API
  • Інтерфейс компоненти
  • Інтерфейс "1С:Підприємства"
  • Відповідність типів tVariant і "1С:Підприємства"
  • Особливості розробки компонентів із використанням Native API
• Створення компонентів із використанням технології COM
  • Ініціалізація та вивантаження компоненти
  • Розширення вбудованої мови
  • Локалізація
  • Використання типу COM VARIANT під час обміну даними
    • Виклик функції компоненти
    • Повернення значень із компоненти
    • Виклик методу об'єкта "1С:Підприємства" з компоненти
  • COM-інтерфейси "1C:Підприємства"
    • Збереження параметрів об'єкта компоненти
    • Інформаційні повідомлення про роботу об'єкта
    • Зовнішні події
    • Робота з рядком стану
  • Створення вікон у середовищі "1С:Підприємства 8"
  • Доступ до "1С:Підприємства" через механізм OLE Automation
  • Методи та властивості, доступні через OLE Automation
  • Особливості розробки компонентів із використанням COM
• Підготовка зовнішніх компонентів до роботи з Веб-клієнтом
  • Зовнішні компоненти для Mozilla Firefox
    • Створення адаптера для Mozilla Firefox
    • Створення інсталяційного пакета
  • Зовнішні компоненти для Internet Explorer
    • Створення адаптера для Internet Explorer
    • Створення інсталяційного пакета
  • Зовнішні компоненти для Google Chrome
    • Створення адаптера для Google Chrome
    • Створення інсталяційного пакета
  • Зовнішні компоненти для Safari
    • Створення адаптера для Safari
    • Створення інсталяційного пакета
  • Підготовка зовнішніх компонентів для завантаження в конфігурацію
  • Опис прикладів
    • Властивості
    • Методи
  • Засоби розробки та приклади

Вступ

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

Для розв'язання таких завдань розроблено технологію зовнішніх компонентів. Ця технологія дає змогу створювати програми, які динамічно підключатимуться й тісно взаємодіятимуть із системою "1С:Підприємство 8", розширюючи її можливості. Зовнішні компоненти дають змогу розв'язувати широкий спектр спеціальних завдань, зокрема завдання, пов'язані з використанням різного торговельного обладнання спільно з "1С:Підприємством 8". Зовнішні компоненти можуть бути підключені як до сервера застосунків "1С:Підприємства", так і до клієнтських застосунків, зокрема й веб-клієнта.

До комплекту постачання входять цей посібник і набір прикладів реалізації зовнішніх компонентів за допомогою різних технологій.

У цьому посібнику описано технологію створення зовнішніх компонентів із використанням Native API та COM.

Структура каталогів

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

Каталог lib містить статичні бібліотеки для побудови розширень для браузерів Firefox та Internet Explorer.

Каталог example містить приклади зовнішніх компонентів, розроблених із використанням COM і Native API. У цьому ж каталозі знаходяться приклади розширень для браузерів.

Каталог template містить шаблон для створення компоненти, розробленої за технологією Native API.

Створення компонентів із використанням технології Native API

Ця технологія дає змогу створювати зовнішні компоненти, які можуть підключатися як у клієнтському застосунку, так і на сервері "1С:Підприємства", зокрема й у версії для Linux.

Кожен об'єкт компоненти має успадковуватися від абстрактного класу IComponentBase (файл ComponentBase.h входить до комплекту постачання) і реалізувати всі його методи.

Зовнішня компонента, розроблена за цією технологією, має експортувати з бібліотеки три функції:

GetClassNames

Опис:

Отримання списку імен об'єктів компоненти.

Синтаксис:

const WCHAR_T* _cdecl GetClassNames()

Повертане значення:

Масив зі списком імен об'єктів компоненти.

GetClassObject

Опис:

Створення екземпляра об'єкта компоненти.

Синтаксис:

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

Параметри:

clsName

Тип: const WCHAR_T* . Ім'я створюваного об'єкта.

pIntf

Тип: IComponentBase**. Вказівник на змінну, до якої потрібно записати адресу щойно створеного об'єкта.

Повертане значення:

• 0 — якщо об'єкт не може бути створений або не знайдено об'єкт із зазначеним ім'ям;
• ненульове значення сигналізує про успішне створення об'єкта.

DestroyObject

Опис:

Видалення екземпляра раніше створеного об'єкта. Компонента має власними засобами видалити об'єкт і звільнити використовувану ним пам'ять.

Синтаксис:

long _cdecl DestroyObject(IComponentBase** pIntf)

Параметри:

Interface

Тип: IComponentBase**. Вказівник на об'єкт компоненти.

Повертане значення:

• 0 — за успішного завершення;
• код помилки (Runtime error) – у разі помилки.

SetPlatformCapabilities

Опис:

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

Синтаксис:

AppCapabilities SetPlatformCapabilities(const AppCapabilities capabilities)

Параметри:

< capabilities>

Тип: перелік AppCapabilities. Значення переліку: eAppCapabilitiesInvalid = -1, eAppCapabilities1 = 1, eAppCapabilitiesLast = eAppCapabilities1,

Інтерфейс компоненти

У цьому розділі наведено опис інтерфейсів, які можуть бути реалізовані в компоненті.

Init

Опис:

Під час завантаження "1С:Підприємство" ініціалізує об'єкт компоненти, викликаючи метод Init і передаючи вказівник на IAddInDefBase. Об'єкт може зберегти цей вказівник для подальшого використання.

Синтаксис:

bool _stdcall Init(void* Interface);

Параметри:

Interface

Тип: void* . Вказівник на інтерфейс "1С:Підприємства".

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

setMemManager

Опис:

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

Увага! Не можна виділяти пам'ять для повернення значень за допомогою new або malloc(), оскільки це призведе до витоку пам'яті та нестабільності роботи програми.

Синтаксис:

bool _stdcall setMemManager(void* memManager);

Параметри:

mem

Тип: void* . Вказівник на інтерфейс менеджера пам'яті "1С:Підприємство 8".

Повертане значення:

• true – успішне завершення,
• false – виявлено помилки.

GetInfo

Опис:

"1С:Підприємство 8" викликає цей метод для отримання інформації про компоненту. Наприклад: версія 3.56 — число 3560.

Синтаксис:

long _stdcall GetInfo();

Повертане значення:

Версія компоненти

Done

Опис:

"1С:Підприємство 8" викликає цей метод у разі завершення роботи з об'єктом компоненти. Цей метод викликається незалежно від результату ініціалізації об'єкта (метод Init).

Синтаксис:

void _stdcall Done();

Повертане значення:

Немає.

RegisterExtensionAs

Опис:

До змінної wsExtName поміщається найменування розширення. Пам'ять для рядка виділяється об'єктом компоненти функцією AllocMemory менеджера пам'яті. "1С:Підприємство 8" звільняє цю пам'ять викликом FreeMemory.

Перша властивість має порядковий номер 0.

Синтаксис:

bool _stdcall RegisterExtensionAs(WCHAR_T** wsExtName);

Параметри:

wsExtName

Тип: WCHAR_T** . Найменування розширення вбудованої мови "1С:Підприємства".

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

GetNProps

Опис:

Повертає кількість властивостей цього розширення.

Синтаксис:

long _stdcall GetNProps();

Повертане значення:

long – кількість властивостей розширення або 0, якщо їх немає.

FindProp

Опис:

Повертає порядковий номер властивості за переданим ім'ям властивості.

Синтаксис:

long _stdcall FindProp(const WCHAR_T* wsPropName);

Параметри:

wsPropName

Тип: const WCHAR_T*. Найменування властивості.

Повертане значення:

• порядковий номер властивості з ім'ям pszPropName;
• -1 — властивість не знайдено.

GetPropName

Опис:

До повертального значення поміщається ім'я властивості з порядковим номером lPropNum; якщо властивість із таким номером відсутня, повертається NULL. Пам'ять для рядка виділяється об'єктом компоненти функцією AllocMemory менеджера пам'яті. "1С:Підприємство 8" звільняє цю пам'ять викликом FreeMemory.

Синтаксис:

const WCHAR_T* _stdcall GetPropName(long lPropNum, long lPropAlias);

Параметри:

lPropNum

Тип: long. Порядковий номер властивості.

lAliasNum

Тип: long. Мова найменування:

• 0 — англійське найменування;
• 1 — локальне найменування.

Повертане значення:

• Потрібне ім'я властивості;
• NULL – якщо властивість із потрібним номером не існує.

GetPropVal

Опис:

До змінної pvPropVal поміщається значення властивості з порядковим номером lPropNum; якщо властивість із таким номером відсутня або недоступна для читання, має бути тип VTYPE_EMPTY. Якщо повертальне значення має тип рядок, компонента виділяє пам'ять для нього функцією AllocMemory. "1С:Підприємство 8" звільнить цю пам'ять.

Синтаксис:

bool _stdcall GetPropVal(const long lPropNum, tVariant* pvarPropVal);

Параметри:

lPropNum

Тип: const long. Порядковий номер властивості.

pvarPropVal

Тип: tVariant*. Вказівник на структуру tVariant, що під час повернення містить значення властивості.

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

SetPropVal

Опис:

Змінна pvPropVal містить значення властивості з порядковим номером lPropNum; якщо властивість із таким номером відсутня, недоступна для запису або тип переданого pvPropVal несумісний, метод має повернути false.

Синтаксис:

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

Параметри:

lPropNum

Тип: const long. Порядковий номер властивості.

pvarPropVal

Тип: tVariant*. Структура tVariant, що містить нове значення властивості.

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

IsPropReadable

Опис:

Повертається прапорець можливості читання властивості з порядковим номером lPropNum. Якщо властивість із таким номером відсутня, метод має повертати false.

Синтаксис:

bool _stdcall IsPropReadable(const long lPropNum);

Параметри:

lPropNum

Тип: const long. Порядковий номер властивості.

Повертане значення:

• true – читання доступне,
• false – читання недоступне.

IsPropWritable

Опис:

Повертається прапорець можливості запису властивості з порядковим номером lPropNum. Якщо властивість із таким номером відсутня, метод має повертати false.

Синтаксис:

bool _stdcall IsPropWritable(const long lPropNum);

Параметри:

lPropNum

Тип: const long. Порядковий номер властивості.

Повертане значення:

• true – запис доступний;
• false – запис недоступний.

GetNMethods

Опис:

Повертається кількість методів цього розширення.

Синтаксис:

long _stdcall GetNMethods();

Повертане значення:

• кількість методів розширення;
• 0 – методи відсутні.

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

FindMethod

Опис:

Повертається порядковий номер методу з ім'ям bstrMethodName.

Синтаксис:

long _stdcall FindMethod(const WCHAR_T* wsMethodName);

Параметри:

wsMethodName

Тип: const WCHAR_T*. Ім'я методу.

Повертане значення:

• порядковий номер методу;
• -1 – метод відсутній.

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

GetMethodName

Опис:

Повертається ім'я властивості з порядковим номером. Пам'ять для рядка виділяється об'єктом компоненти функцією AllocMemory менеджера пам'яті. "1С:Підприємство 8" звільняє цю пам'ять викликом FreeMemory.

Синтаксис:

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

Параметри:

lMethodNum

Тип: const long. Порядковий номер методу.

lAliasNum

Тип: const long. Мова імені методу:

• 0 — англійське найменування;
• 1 — локальне найменування.

Повертане значення:

• ім'я методу із зазначеним номером;
• NULL, якщо метод із зазначеним номером відсутній.

GetNParams

Опис:

Повертається кількість параметрів методу з порядковим номером lMethodNum.

Синтаксис:

long _stdcall GetNParams(const long lMethodNum);

Параметри:

lMethodNum

Тип: const long. Порядковий номер методу.

Повертане значення:

• кількість параметрів методу;
• 0 – метод відсутній або не має параметрів.

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

GetParamDefValue

Опис:

До змінної pvParamDefVal поміщається значення за замовчуванням параметра lParamNum методу з порядковим номером lMethodNum. До pvParamDefVal поміщається тип VTYPE_EMPTY, якщо метод із таким номером відсутній, не має параметра з номером або параметр не має значення за замовчуванням. Якщо значення за замовчуванням має тип VTYPE_PSTR, VTYPE_PWSTR або VTYPE_BLOB, компонента виділяє пам'ять функцією AllocMemory менеджера пам'яті, записує туди дані й зберігає цю адресу у відповідному полі структури. "1С:Підприємство 8" звільнить цю пам'ять викликом FreeMemory.

Синтаксис:

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

Параметри:

lMethodNum

Тип: const long. Порядковий номер методу.

lParamNum

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

pvarParamDefValue

Тип: tVariant* . Вказівник на структуру tVariant, що під час повернення містить значення параметра за замовчуванням.

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

HasRetVal

Опис:

Повертається прапорець наявності в методу з порядковим номером lMethodNum повертального значення.

Синтаксис:

bool _stdcall HasRetVal(const long lMethodNum)

Параметри:

lMethodNum

Тип: const long. Порядковий номер методу.

Повертане значення:

• true – метод повертає значення;
• false – метод не має повертального значення.

CallAsProc

Опис:

Виконується метод із порядковим номером lMethodNum. Якщо метод повертає false, виникає помилка часу виконання, і виконання модуля "1С:Підприємство 8" припиняється. Пам'ять для масиву параметрів виділяється та звільняється "1С:Підприємством 8".

Синтаксис:

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

Параметри:

lMethodNum

Тип: const long. Порядковий номер методу.

paParams

Тип: tVariant*. Вказівник на масив структур tVariant, що містить значення параметрів методу. Якщо метод не має параметрів, то містить NULL.

lSizeArray

Тип: const long. Розмір масиву paParams.

Повертане значення:

• true – відповідний метод викликано, помилок не сталося;
• false – метод відсутній або сталася помилка часу виконання (runtime error).

CallAsFunc

Опис:

Виконується метод із порядковим номером lMethodNum. Якщо метод повертає false, виникає помилка часу виконання і виконання модуля "1С:Підприємство 8" припиняється. Пам'ять для масиву параметрів виділяється "1С:Підприємством 8". Якщо повертальне значення має тип рядок або двійкові дані, компонента виділяє пам'ять функцією AllocMemory менеджера пам'яті, записує туди дані й зберігає цю адресу у відповідному полі структури. "1С:Підприємство 8" звільнить цю пам'ять викликом FreeMemory.

Синтаксис:

bool _stdcall 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).

SetLocale

Опис:

"1С:Підприємство" викликає цей метод для локалізації компоненти відповідно до використовуваного коду локалізації. Компонента може налаштувати своє оточення для правильного виведення інформації.

Синтаксис:

void _stdcall SetLocale(const WCHAR_T* wsLocale);

Параметри:

wsLocale

Тип: const WCHAR_T*. Рядок локалізації у форматі < language> _< REGION> . Наприклад: для Linux – ru_RU, для Windows — rus_RUS.

Повертане значення:

Немає.

Інтерфейс "1С:Підприємства"

Під час ініціалізації об'єкта компоненти йому передається вказівник на інтерфейс "1С:Підприємства 8", за допомогою якого можна викликати перелічені нижче методи. Слід пам'ятати, що ці методи не працюватимуть на сервері застосунків.

AddError

Опис:

Додає інформаційне повідомлення під час роботи методів розширення мови. Якщо scode має ненульове значення, буде згенеровано виняток, який може бути перехоплений та оброблений засобами вбудованої мови "1С:Підприємства 8".

Можливі коди повідомлень і поведінку "1С:Підприємства 8" наведено в розділі "Інформаційні повідомлення про роботу об'єкта".

Синтаксис:

bool _stdcall 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

Тип: long. Код помилки.

Повертане значення:

• true – інформацію про помилку успішно додано;
• false – виявлено помилки.

RegisterProfileAs

Опис:

Реєструє список параметрів компоненти з іменем wsProfileName.

Синтаксис:

bool _stdcall RegisterProfileAs(WCHAR_T* wsProfileName);

Параметри:

wsProfileName

Тип: WCHAR_T* . Найменування списку параметрів компоненти.

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

Read

Опис:

Читає збережене значення параметра компоненти з іменем pszPropName. У разі невдачі читання та ненульового значення errDescriptor "1С:Підприємство 8" виділить пам'ять і помістить опис помилки. Компонента має звільнити пам'ять викликом FreeMemory. Для повертальних даних типу рядок пам'ять також виділяється "1С:Підприємством 8", а адреса зберігається у відповідному полі структури tVariant. Компонента має звільнити її викликом FreeMemory.

Синтаксис:

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

Параметри:

pszPropName

Тип: WCHAR_T* . Ім'я параметра.

pVal

Тип: tVariant* . Вказівник на повертальне значення параметра.

pErrCode

Тип: long* . Вказівник на змінну, куди буде поміщено код помилки, якщо вона виникне.

errDescriptor

Тип: WCHAR_T** . Подвійний вказівник на змінну, куди буде поміщено опис помилки.

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

Write

Опис:

Зберігає значення параметра компоненти з іменем pszPropName.

Синтаксис:

bool _stdcall Write(WCHAR_T* pszPropName, tVariant* pVar);

Параметри:

pszPropName

Тип: WCHAR_T*. Ім'я параметра.

pVar

Тип: tVariant*. Вказівник на значення параметра.

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

SetEventBufferDepth

Опис:

Установлює розмір черги подій для цього об'єкта. Якщо поточна кількість подій у черзі більша за встановлювану довжину, останні події видаляються.

Синтаксис:

bool _stdcall SetEventBufferDepth( long lDepth);

Параметри:

lDepth

Тип: long. Довжина черги повідомлень.

Повертане значення:

• true – успішне завершення;
• false – виявлено помилки.

GetEventBufferDepth

Опис:

Повертається розмір черги подій для цього об'єкта.

Синтаксис:

long _stdcall GetEventBufferDepth();

Параметри:

Немає.

Повертане значення:

Розмір черги повідомлень.

ExternalEvent

Опис:

Поміщає подію до черги, записуючи джерело події, найменування та параметри події. Під час обробки події ці дані передаються процедурі ОбробкаЗовнішньоїПодії(). Під час виклику методу ExternalEvent() подальша обробка події відбувається так: подія записується до черги подій (якщо черга повністю зайнята, подія втрачається), потім за відсутності системних подій із черги береться перша подія (якщо черга не порожня) і запускається процес обробки зовнішніх подій. Цей процес повторюється для всіх об'єктів зовнішніх компонентів. Таким чином, обробка зовнішніх подій синхронізується з обробкою системних подій.

Синтаксис:

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

Параметри:

wsSource

Тип: WCHAR_T*. Рядок із найменуванням джерела повідомлення.

wsMessage

Тип: WCHAR_T*. Рядок із найменуванням повідомлення.

wsData

Тип: WCHAR_T*. Рядок c параметрами повідомлення.

Повертане значення:

• true – подію поміщено до черги;
• false – черга переповнена, обробка подій недоступна або невідома помилка.

CleanEventBuffer

Опис:

Очищає чергу подій, видаляючи всі наявні в черзі події.

Синтаксис:

void _stdcall CleanEventBuffer();

SetStatusLine

Опис:

Установлює текст рядка стану.

Синтаксис:

bool _stdcall SetStatusLine(WCHAR_T* wsStatusLine);

Параметри:

wsStatusLine

Тип: WCHAR_T* . Текст рядка стану.

Повертане значення:

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

ResetStatusLine

Опис:

Ініціалізує рядок стану.

Синтаксис:

void _stdcall 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.

Відповідність типів tVariant і "1С:Підприємства"

Тип tVariant оголошено у файлі types.h (входить до комплекту постачання).

• 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 не підтримуються.

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

Компонента з використанням цієї технології є платформозалежною. Тому розробник має будувати варіант компоненти як для платформи x86, так і для x86-64. У процесі використання розробник конфігурації визначить тип платформи та завантажить потрібний варіант компоненти.

Також слід пам'ятати, що компонента може бути завантажена на сервері застосунків "1С:Підприємства" під керуванням ОС Windows або Linux. Також компонента може бути завантажена у веб-клієнті, що функціонує в ОС Windows або Linux. Тому бажано робити реалізацію кросплатформною.

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

Якщо зовнішня компонента використовує додаткові модулі, це потрібно зазначати в документації до компоненти. Використовувані несистемні run-time бібліотеки мають бути статично включені до компоненти (якщо дозволяє ліцензія на run-time бібліотеку), оскільки на комп'ютері, де використовуватиметься компонента, їх може не бути або вони можуть бути іншої версії. Також до компоненти для Windows потрібно включати маніфест.

У разі виникнення виняткових ситуацій вони мають бути перехоплені та оброблені в компоненті, а інформація про них передана до "1С:Підприємства" за допомогою методу AddError().

У разі використання компоненти на сервері застосунків зовнішні події не обробляються. Також не оброблятимуться методи роботи з рядком стану та збереження параметрів.

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

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

Увага! Повертальні значення типу VTYPE_ARRAY і VTYPE_BYREF не підтримуються.

Створення компонентів із використанням технології COM

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

Під час завантаження зовнішньої компоненти функцією ЗавантажитиЗовнішнюКомпоненту() або ПідключитиЗовнішнюКомпоненту() (для компоненти, створеної за технологією COM) "1С:Підприємство 8" визначає ProgID COM-об'єкта компоненти так:

• ProgID має вигляд Vendor.Component;
• як перша частина (Vendor) використовується рядок AddIn;
• як друга частина (Component) використовується рядок з ID100 із таблиці рядків компоненти. Рядок може мати вигляд Name1|Name2|...|NameN, і в цьому разі будуть створені всі об'єкти з ProgID вигляду AddIn.NameX. Якщо такого рядка немає, використовується ім'я файлу зовнішньої компоненти без розширення.

Також під час використання функції ПідключитиЗовнішнюКомпоненту() ProgID COM-об'єкта компоненти передається як параметр функції та може бути поданий рядком вигляду ProgID1| ProgID2|...|ProgIDX.

Ініціалізація та вивантаження компоненти

Для ініціалізації та вивантаження компоненти використовується інтерфейс IInitDone. Цей інтерфейс успадкований від IUnknown і призначений для ініціалізації об'єкта та завершення роботи з об'єктом.

Init

Опис:

Під час завантаження "1С:Підприємство 8" ініціалізує об'єкт компоненти, викликаючи метод Init і передаючи вказівник на IDispatch. Об'єкт може зберегти цей вказівник для подальшого використання. Усі інші інтерфейси "1С:Підприємства 8" об'єкт може отримати, викликавши метод QueryInterface() переданого йому інтерфейсу IDispatch. Об'єкт має повернути S_OK, якщо ініціалізація пройшла успішно, та E_FAIL у разі виникнення помилки. Цей метод може використовувати інтерфейс IErrorLog для виведення інформації про помилки. При цьому ініціалізація вважається невдалою, якщо одна з переданих структур EXCEPINFO має поле scode, що не дорівнює S_OK. Усі передані в IErrorLog дані обробляються під час повернення з цього методу. У момент виклику цього методу властивість AppDispatch не визначена.

Синтаксис:

HRESULT Init(IDispatch* pBackConnection);

Параметри:

pBackConnection

Тип: Idispatch* . Вказівник на інтерфейс "1С:Підприємства 8".

Повертане значення:

• E_FAIL — під час ініціалізації сталася помилка;
• S_OK — ініціалізація пройшла успішно.

Done

Опис:

"1С:Підприємство 8" викликає цей метод у разі завершення роботи з об'єктом компоненти. Об'єкт має повернути S_OK. Цей метод викликається незалежно від результату ініціалізації об'єкта (метод Init).

Синтаксис:

HRESULT Done(void);

Повертане значення:

• S_OK — об'єкт завершив роботу.

GetInfo

Опис:

"1С:Підприємство 8" викликає цей метод для отримання інформації про компоненту. У технології створення зовнішніх компонентів версії 2.0 в елемент з індексом 0 необхідно записати версію підтримуваної технології у форматі V_I4 — цілого числа, при цьому старший номер версії записується в тисячні розряди, молодший номер версії — в одиниці. Наприклад: версія 1.00 — число 1000. Усі об'єкти зовнішніх компонентів можуть підтримувати версію 1.0 (відповідає числу 1000) або 2.0 (відповідає 2000). Пам'ять для pInfo виділяється "1С:Підприємством 8". Метод має повертати S_OK.

Об'єкт зовнішньої компоненти зобов'язаний реалізувати цей інтерфейс. За його відсутності компонента не буде завантажена.

Синтаксис:

HRESULT GetInfo(SAFEARRAY** pInfo);

Параметри:

pInfo

Тип: SAFEARRAY** . Подвійний вказівник на масив структур VARIANT. Пам'ять для масиву виділяється "1С:Підприємством 8".

Повертане значення:

• S_OK — інформацію про компоненту повернуто.

Розширення вбудованої мови

Для розширення вбудованої мови компонента має реалізувати інтерфейс ILanguageExtender. Цей інтерфейс успадкований від IUnknown і призначений для розширення вбудованої мови "1С:Підприємство 8". Для використання цього розширення необхідно використовувати оператор Новий, передавши йому рядок вигляду AddIn.Ім'яРозширення, де Ім'яРозширення повертається методом цього інтерфейсу. Потім можна використовувати створений об'єкт, викликаючи його методи та властивості.

Версія 2.0 дає змогу створювати кілька об'єктів одного типу AddIn.Ім'яРозширення, однак компонента має явно зазначити підтримку версії 2.0 у методі GetInfo(). В іншому разі допускається створення лише одного об'єкта.

RegisterExtensionAs

Опис:

До змінної pExtensionName поміщається найменування розширення. Пам'ять для рядка виділяється об'єктом компоненти стандартними системними функціями для роботи з COM-рядками (наприклад, SysAllocString(). "1С:Підприємство 8" звільняє цю пам'ять викликом SysFreeString()).

Перша властивість має порядковий номер 0.

Синтаксис:

HRESULT RegisterExtensionAs(BSTR* pExtensionName);

Параметри:

pExtensionName

Тип: BSTR* . Найменування розширення вбудованої мови "1С:Підприємства".

Повертане значення:

• S_OK

GetNProps

Опис:

Повертає кількість властивостей цього розширення, 0 – за відсутності властивостей. Пам'ять для змінної plProps виділяється "1С:Підприємством".

Синтаксис:

HRESULT GetNProps(long* plProps);

Параметри:

plProps

Тип: long* . Вказівник на змінну, що під час повернення містить кількість властивостей розширення. 0 – за відсутності властивостей.

Повертане значення:

• S_OK

FindProp

Опис:

Повертає порядковий номер властивості з ім'ям pszPropName, -1, якщо властивість не знайдено. Пам'ять для змінної plPropNum виділяється "1С:Підприємством 8".

Синтаксис:

HRESULT FindProp(BSTR pszPropName, long* plPropNum);

Параметри:

pszPropName

Тип: BSTR. Найменування властивості.

plPropNum

Тип: long* . Вказівник на змінну, що під час повернення містить порядковий номер властивості.

Повертане значення:

• S_OK — операцію успішно завершено;
• S_FALSE — властивість з ім'ям pszPropName у цьому розширенні відсутня.

GetPropName

Опис:

До змінної pPropName поміщається ім'я властивості з порядковим номером lPropNum; якщо властивість із таким номером відсутня, до pPropName поміщається порожній рядок. Пам'ять для рядка виділяється об'єктом компоненти стандартними системними функціями для роботи з COM-рядками (наприклад, SysAllocString(). "1С:Підприємство 8" звільняє цю пам'ять викликом SysFreeString()).

Синтаксис:

HRESULT GetPropName(long lPropNum, long lAliasNum, BSTR* pPropName);

Параметри:

lPropNum

Тип: long. Порядковий номер властивості.

lAliasNum

Тип: long. Мова найменування:

• 0 — англійське найменування;
• 1 — локальне найменування.

pPropName

Тип: BSTR* . Вказівник на рядок, що під час повернення містить найменування властивості.

Повертане значення:

• S_OK — операцію успішно завершено;
• S_FALSE — властивість із номером lPropNum у цьому розширенні відсутня.

GetPropVal

Опис:

До змінної pvPropVal поміщається значення властивості з порядковим номером lPropNum; якщо властивість із таким номером відсутня або недоступна для читання, має бути тип VT_EMPTY.

Синтаксис:

HRESULT GetPropVal(long lPropNum, VARIANT* pvPropVal);

Параметри:

lPropNum

Тип: long. Порядковий номер властивості.

pvPropVal

Тип: VARIANT*. Вказівник на структуру VARIANT, що під час повернення містить значення властивості.

Повертане значення:

• S_OK — операцію успішно завершено;
• S_FALSE — властивість із номером lPropNum у цьому розширенні відсутня або недоступна для читання.

SetPropVal

Опис:

Змінна pvPropVal містить значення властивості з порядковим номером lPropNum; якщо властивість із таким номером відсутня, недоступна для запису або тип переданого pvPropVal не приводиться до потрібного, метод має повернути S_FALSE.

Синтаксис:

HRESULT SetPropVal(long lPropNum, VARIANT* pvPropVal);

Параметри:

lPropNum

Тип: long. Порядковий номер властивості.

pvPropVal

Тип: VARIANT*. Структура VARIANT, що містить нове значення властивості.

Повертане значення:

• S_OK — операцію успішно завершено;
• S_FALSE — властивість із номером lPropNum у цьому розширенні відсутня або недоступна для запису.

IsPropReadable

Опис:

До змінної pboolPropReadable поміщається прапорець можливості читання властивості з порядковим номером lPropNum: FALSE (0) — властивість недоступна для читання, TRUE (1) — властивість допускає читання. Якщо властивість із таким номером відсутня, метод має повертати S_FALSE.

Синтаксис:

HRESULT IsPropReadable(long lPropNum, BOOL* pboolPropReadable);

Параметри:

lPropNum

Тип: long. Порядковий номер властивості.

pboolPropReadable

Тип: BOOL*. Вказівник на змінну, що під час повернення містить прапорець можливості читання властивості.

Повертане значення:

• S_OK — операцію успішно завершено;
• S_FALSE — властивість із номером lPropNum у цьому розширенні відсутня.

IsPropWritable

Опис:

До змінної pboolPropWritable поміщається прапорець можливості запису властивості з порядковим номером lPropNum: FALSE (0) — властивість недоступна для запису, TRUE (1) — властивість допускає запис. Якщо властивість із таким номером відсутня, метод має повертати S_FALSE.

Синтаксис:

HRESULT IsPropWritable(long lPropNum, BOOL* pboolPropWritable);

Параметри:

lPropNum

Тип: long. Порядковий номер властивості.

pboolPropWritable

Тип: BOOL*. Вказівник на змінну, що під час повернення містить прапорець можливості запису властивості.

Повертане значення:

• S_OK — операцію успішно завершено;
• S_FALSE — властивість із номером у цьому розширенні відсутня.

GetNMethods

Опис:

До змінної plMethods поміщається кількість методів цього розширення, 0 — за відсутності методів.

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

Синтаксис:

HRESULT GetNMethods(long* plMethods);

Параметри:

plMethods

Тип: long*. Вказівник на змінну, що під час повернення містить кількість методів розширення мови.

Повертане значення:

• S_OK

FindMethod

Опис:

До змінної plMethNum поміщається порядковий номер методу з ім'ям bstrMethodName або -1 — за відсутності методу.

Синтаксис:

HRESULT FindMethod(BSTR bstrMethodName, long* plMethNum);

Параметри:

bstrMethodName

Тип: BSTR. Ім'я методу.

plMethNum

Тип: long*. Вказівник на змінну, що під час повернення містить порядковий номер методу з ім'ям methodName.

Повертане значення:

• S_OK

GetMethodName

Опис:

До змінної поміщається ім'я властивості з порядковим номером; якщо властивість із таким номером відсутня, поміщається порожній рядок. Пам'ять для рядка виділяється об'єктом компоненти стандартними системними функціями для роботи з COM-рядками (наприклад, SysAllocString(). 1cg звільняє цю пам'ять викликом SysFreeString()).

Синтаксис:

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

Параметри:

lMethodNum

Тип: long. Порядковий номер методу.

lAliasNum

Тип: long. Мова імені методу:

• 0 — англійське найменування;
• 1 — локальне найменування.

pbstrMethName

Тип: BSTR*. Вказівник на рядок, що під час повернення містить ім'я методу.

Повертане значення:

• S_OK — операцію успішно завершено;
• S_FALSE — метод із номером у цьому розширенні відсутній.

GetNParams

Опис:

До змінної plMethParams поміщається кількість параметрів методу з порядковим номером lMethodNum; якщо метод із таким номером відсутній або не має параметрів, то поміщається 0. Пам'ять для змінної виділяється "1С:Підприємством 8".

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

Синтаксис:

HRESULT GetNParams(long lMethodNum, long* plMethParams);

Параметри:

lMethodNum

Тип: long. Порядковий номер методу.

plMethParams

Тип: long*. Вказівник на змінну, що під час повернення містить кількість параметрів методу.

Повертане значення:

• S_OK — операцію успішно завершено,
• S_FALSE — метод із номером у цьому розширенні відсутній.

GetParamDefValue

Опис:

До змінної pvParamDefVal поміщається значення за замовчуванням параметра lParamNum методу з порядковим номером lMethodNum. До pvParamDefVal поміщається тип VT_EMPTY, якщо метод із таким номером відсутній, не має параметра з номером або параметр не має значення за замовчуванням. Пам'ять для змінної виділяється "1С:Підприємством".

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

Синтаксис:

HRESULT GetParamDefValue(long lMethodNum, long lParamNum, VARIANT* pvParamDefVal);

Параметри:

lMethodNum

Тип: long. Порядковий номер методу.

lParamNum

Тип: long. Порядковий номер параметра.

pvParamDefVal

Тип: VARIANT*. Вказівник на структуру VARIANT, що під час повернення містить значення параметра за замовчуванням.

Повертане значення:

• S_OK — операцію успішно завершено (незалежно від наявності в параметра значення за замовчуванням);
• S_FALSE — метод або параметр методу відсутній.

HasRetVal

Опис:

До змінної pboolHasRetVal поміщається прапорець наявності повертального значення в методу з порядковим номером lMethodNum: TRUE для методів із повертальним значенням і FALSE в іншому разі. Пам'ять для змінної виділяється "1С:Підприємством 8".

Синтаксис:

HRESULT HasRetVal(long lMethodNum,BOOL* pboolHasRetVal);

Параметри:

lMethodNum

Тип: long. Порядковий номер методу.

pboolHasRetVal

Тип: BOOL*.. Вказівник на змінну, що під час повернення містить прапорець наявності повертального значення.

Повертане значення:

• S_OK — операцію успішно завершено;
• S_FALSE — метод відсутній.

CallAsProc

Опис:

Виконується метод із порядковим номером lMethodNum. Якщо метод повертає E_FAIL, виникає помилка часу виконання і виконання модуля "1С:Підприємство 8" припиняється. Пам'ять для масиву параметрів виділяється "1С:Підприємством 8".

Синтаксис:

HRESULT CallAsProc(long lMethodNum, SAFEARRAY** pVars);

Параметри:

lMethodNum

Тип: long. Порядковий номер методу.

pVars

Тип: SAFEARRAY**. Подвійний вказівник на масив структур VARIANT, що містить значення параметрів методу. Якщо метод не має параметрів, то містить NULL.

Повертане значення:

• S_OK — відповідний метод викликано, помилок не сталося.
• E_FAIL — відповідний метод викликано, сталася помилка часу виконання (runtime error). Виконання модуля припиняється.
• S_FALSE – відсутній метод, що відповідає переданому lMethodNum.

CallAsFunc

Опис:

Виконується метод із порядковим номером lMethodNum. Якщо метод повертає E_FAIL, виникає помилка часу виконання і виконання модуля "1С:Підприємства 8" припиняється. Пам'ять для масиву виділяється "1С:Підприємством 8".

Синтаксис:

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.

Локалізація

SetLocale

Опис:

"1С:Підприємство" викликає цей метод для локалізації компоненти відповідно до використовуваного коду локалізації. Компонента може налаштувати своє оточення для правильного виведення інформації.

Синтаксис:

HRESULT SetLocale(BSTR bstrLocale);

Параметри:

bstrLocale

Тип: BSTR. Рядок локалізації у форматі language-REGION. Наприклад: для Росії – ru-RU.

Повертане значення:

• S_OK

Використання типу COM VARIANT під час обміну даними

Виклик функції компоненти

Відповідність між типами "1С:Підприємства" і COM:

• Значення Невизначено відповідає VT_EMPTY.
• Цілочислове значення відповідає VT_I4 і поміщається в lVal.
• Дробове значення відповідає VT_R8 і поміщається в dblVal. Слід врахувати, що внутрішнє подання може мати точність, що перевищує точність типу double (близько 15 цифр після коми), тому під час конвертації може відбуватися втрата точності.
• Значення дати відповідає VT_DATE і поміщається в date.
• Рядкове значення відповідає VT_BSTR і поміщається в bstrVal.
• Об'єкти відповідають VT_DISPATCH і поміщаються в pdispVal. Під час використання об'єктів "1С:Підприємство 8" у компоненті необхідно визначити 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С:Підприємства 8" через інтерфейс IPropertyProfile. Цей інтерфейс успадкований від інтерфейсу IPropertyBag, стандартного для COM, і відрізняється єдиним методом:

RegisterProfileAs

Опис:

Реєструє список параметрів компоненти з іменем 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" – у профілі, що відповідає поєднанню комп'ютер – ІБ — користувач.

Синтаксис:

HRESULT RegisterProfileAs(BSTR bstrProfileName);

Параметри:

bstrProfileName

Тип: BSTR. Найменування списку параметрів компоненти.

Повертане значення:

• S_OK — реєстрація пройшла успішно.
• E_FAIL — під час реєстрації сталася помилка. Інформація про помилку виводиться у вікно повідомлень.

Інформаційні повідомлення про роботу об'єкта

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

AddError

Опис:

Додає інформаційне повідомлення під час роботи методів розширення мови.

Можливі коди повідомлень:

#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 зарезервовано.

Під час обробки повідомлення виводиться вікно попередження для кодів 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).

Іконка відсутня, якщо використовується код повідомлення, що не збігається з переліченими вище.

ДжерелоПомилки — поле bstrSource у структурі EXCEPINFO.

ОписПомилки — поле bstrDescription у структурі EXCEPINFO.

КодПомилки — числовий код повідомлення в десятковому вигляді. Код повідомлення не виводиться, якщо використовується один із перелічених вище кодів.

Для кодів ADDIN_E_MSGBOX_ATTENTION, ADDIN_E_MSGBOX_INFO та ADDIN_E_MSGBOX_FAIL виводиться вікно повідомлення з кнопкою OK та іконками MB_ICONEXCLAMATION, MB_ICONINFORMATION і MB_ICONERROR відповідно.

Повідомлення має вигляд:

ДжерелоПовідомлення:ОписПовідомлення (Код повідомлення = КодПовідомлення),

Де опис ДжерелоПовідомлення, ОписПовідомлення та КодПовідомлення див. вище.Синтаксис:

HRESULT AddError(BSTR pszPropName, LPEXCEPINFO pExcepInfo);

Параметри:

pszPropName

Тип: BSTR. У цій реалізації параметр pszPropName ігнорується.

pExcepInfo

Тип: LPEXCEPINFO. Вказівник на структуру EXCEPINFO.

Повертане значення:

• S_OK — повідомлення успішно додано.
• E_OUTOFMEMORY — недостатньо пам'яті.
• Можливі інші коди повернення, що сигналізують про помилку.

Діалогові повідомлення

Для діалогу з користувачем об'єкт може використовувати інтерфейс IMsgBox, стандартний для COM. Інтерфейс IMsgBox успадкований від IUnknown. Недоступний на сервері та у зовнішньому з'єднанні.

Confirm

Опис:

Виводить діалог із текстом, заданим параметром queryText, і кнопками ОК та Скасування.

Синтаксис:

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

Параметри:

< queryText>

Тип: BSTR. Текст запитання.

< retVal>

Тип: VARIANT. Повертане значення діалогу.

Тип VT_BOOL. Значення TRUE відповідає кнопці ОК, FALSE – Скасування.

Повертане значення:

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

Alert

Опис:

Виводить простий діалог із кнопкою ОК.

Синтаксис:

HRESULT Alert( BSTR text)

Параметри:

< queryText>

Тип: BSTR. Текст повідомлення.

Повертане значення:

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

Інформація про платформу

Для отримання інформації про застосунок, що підключив об'єкт, може використовувати інтерфейс IPlatformInfo, стандартний для COM. Інтерфейс IPlatformInfo успадкований від IUnknown.

GetPlatformInfo

Опис:

Запитує інформацію про платформу. У разі підключення компоненти у веб-клієнті старої версії платформи буде заповнено лише поле Application структури AppInfo.

Синтаксис:

HRESULT GetPlatformInfo(AppInfo** info)

Параметри:

< info>

Тип AppInfo**. - вказівник на структуру з полями:

AppVersion

Тип: BSTR, версія застосунку,

Application

Тип: перелік, тип застосунку, що підключив компоненту

UserAgentInformation

Тип: BSTR, інформація про браузер (лише для веб-клієнта)

Повертане значення:

• S_OK — виконано успішно.

Зовнішні події

У разі виникнення асинхронної події (наприклад, зчитування штрихкоду) об'єкт може використовувати інтерфейс IAsyncEvent для створення зовнішньої події в "1С:Підприємстві 8". Інтерфейс IAsyncEvent успадкований від IUnknown. Усі події поміщаються до черги й обробляються в порядку появи. Кількість запам'ятовуваних подій обмежена довжиною черги. Під час ініціалізації довжина черги встановлюється рівною 1 і може бути змінена викликом SetEventBufferDepth(), а поточний розмір черги отримано за допомогою методу GetEventBufferDepth(). Для кожного об'єкта зовнішньої компоненти підтримується власна черга подій. Обробка зовнішньої події здійснюється визначеною процедурою ОбробкаЗовнішньоїПодії() та обробниками зовнішніх подій у модулях форм.

SetEventBufferDepth

Опис:

Установлює розмір черги подій для цього об'єкта. Якщо поточна кількість подій у черзі більша за встановлювану довжину, останні події видаляються.

Синтаксис:

HRESULT SetEventBufferDepth(long lDepth);

Параметри:

lDepth

Тип: long. Довжина черги повідомлень.

Повертане значення:

• S_OK — розмір черги успішно встановлено.
• E_FAIL — під час установлення розміру черги сталася помилка.
• Можливі інші коди повернення, що сигналізують про помилку.

GetEventBufferDepth

Опис:

До змінної plDepth поміщається розмір черги подій для цього об'єкта.

Синтаксис:

HRESULT GetEventBufferDepth(long* plDepth);

Параметри:

plDepth

Тип: long*. Вказівник на змінну, що під час повернення містить довжину черги повідомлень.

Повертане значення:

• S_OK — розмір черги успішно повернуто.
• E_FAIL — під час отримання розміру черги сталася помилка.
• Можливі інші коди повернення, що сигналізують про помилку.

ExternalEvent

Опис:

Поміщає подію до черги, записуючи джерело події, найменування та параметри події. Під час обробки події ці дані передаються процедурі ОбробкаЗовнішньоїПодії(). Під час виклику методу ExternalEvent() подальша обробка події відбувається так:

• подія записується до черги подій (якщо черга повністю зайнята, подія втрачається);
• потім за відсутності системних подій із черги береться перша подія (якщо черга не порожня);
• запускається процес обробки зовнішніх подій.

Цей процес повторюється для всіх об'єктів зовнішніх компонентів. Таким чином, обробка зовнішніх подій синхронізується з обробкою системних подій.

Синтаксис:

HRESULT ExternalEvent(BSTR bstrWho, BSTR bstrWhat, BSTR bstrData);

Параметри:

bstrWho

Тип: BSTR. Рядок із найменуванням джерела повідомлення.

bstrWhat

Тип: BSTR. Рядок із найменуванням повідомлення.

bstrData

Тип: BSTR. Рядок c параметрами повідомлення.

Повертане значення:

• S_OK – подію поміщено до черги.
• E_FAIL – черга переповнена або невідома помилка.
• E_OUTOFMEMORY – відсутність пам'яті.
• Можливі інші коди повернення, що сигналізують про помилку.

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С:Підприємство 8". Однак слід врахувати, що створений діалог не входить до списку відкритих вікон і не з'являється на панелі вікон, тому використання таких діалогів не рекомендується (замість них можна використовувати форми самого "1С:Підприємства 8").

У "1С:Підприємстві 8" можливість створення вікон збережена в скороченому вигляді для сумісності з наявними компонентами. Для відображення нестандартної інформації у вікнах "1С:Підприємство 8" рекомендується використовувати форми з елементами керування ActiveX або Активні документи. Нижче наведено описи методів інтерфейсу IExtWndsSupport.

Увага! Можливість роботи з вікнами відсутня у веб-клієнті.

GetAppMainFrame

Опис:

Повертає дескриптор основного вікна "1С:Підприємства 8".

Синтаксис:

HRESULT GetAppMainFrame(HWND* pHWnd);

Параметри:

• pHWnd

Тип: HWND*. Вказівник на дескриптор вікна.

Повертане значення:

• S_OK

GetAppMDIFrame

Опис:

Повертає дескриптор активного вікна "1С:Підприємства 8".

Синтаксис:

HRESULT GetAppMDIFrame(HWND* pHWnd);

Параметри:

pHWnd

Тип: HWND*. Вказівник на дескриптор вікна.

Повертане значення:

• S_OK

Доступ до "1С:Підприємства" через механізм OLE Automation

Версія технології 2.0

Переданий у методі Init() вказівник на IDispatch дає змогу отримати доступ до "1С:Підприємства 8" через механізм OLE Automation. З отриманого вказівника можна отримати властивість AppDispatch, доступну лише для читання. Ця властивість містить вказівник на IDispatch "1С:Підприємства 8" (не плутати з переданим у Init()). Під час підключення компоненти до веб-клієнта властивість AppDispatch буде недоступна. Це слід враховувати під час розробки компонентів.

Властивість AppDispatch стає доступною лише після повної ініціалізації всієї системи "1С:Підприємство 8", тому в момент завантаження зовнішньої компоненти та виклику методу Init() ця властивість забезпечує доступ не до всіх можливостей "1С:Підприємства 8".

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

Visual Basic має обмежені можливості роботи з різними інтерфейсами. Найбільш "природним" механізмом для Visual Basic є робота з OLE Automation, для цього у VB використовується тип Object, який є вказівником на IDispatch. Тому "1С:Підприємство 8" надає можливість використовувати механізм 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) отримує з інформаційної бази файл зовнішньої компоненти, якщо остання перебуває там, і викликає функцію реєстрації об'єктів компоненти DllRegisterServer. Якщо користувач обмежений у правах, то реєстрація та підключення зовнішньої компоненти завершаться невдачею. Розробник має передбачити можливість реєстрації компоненти для користувача за його поточними правами. У прикладі COM-компоненти, що постачається, показано, як це можна зробити. Якщо зовнішня компонента має власний інсталятор, то вона має реєструватися для комп'ютера.

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

Взаємодія зовнішніх компонентів із веб-клієнтом здійснюється за допомогою розширень. У прикладах наведено проєкти для побудови розширень для Mozilla Firefox та Internet Explorer. З метою безпеки кожне розширення може працювати лише з однією компонентою, заданою на етапі компіляції. Кожне розширення складається власне із зовнішньої компоненти та адаптера браузера. Зовнішньою компонентою може бути вже наявна зовнішня компонента, створена за технологією COM.

Скриптова мова програмування браузерів є однопотоковою. У зв'язку з цим слід уникати зворотних викликів із неосновного потоку в компоненті. В інших потоках працюватимуть лише методи ExternalEvent(), SetStatusLine(), ResetStatusLine(). Слід враховувати ці особливості під час розробки зовнішньої компоненти.

Для збирання адаптерів Firefox версій 6 і 19 для ОС Windows – слід використовувати компілятор від Visual Studio 2008, для версії 22 – компілятор від Visual Studio 2010. Для ОС Linux для Firefox-22 – слід використовувати gcc версії не нижче 4.4.

Бібліотеки для інших браузерів для ОС Windows використовують компілятор від Visual Studio 2008.

Зовнішні компоненти для Mozilla Firefox

Створення адаптера для Mozilla Firefox

Під час створення розширення для Firefox на комп'ютері розробника потрібно встановити xulrunner-sdk. Останню версію можна взяти із сайту Mozilla. Підтримувані версії: xulrunner-6.0 для Firefox із версії 4 до 18, xulrunner-19.0 для Firefox із версії 19 до 22, xulrunner-22.0 для Firefox із 22 і вище. Для різних версій Firefox мають бути зібрані різні інсталяційні пакети, у яких використовуються відповідні версії xulrunner. У процесі встановлення компоненти платформа вибере потрібний пакет, ґрунтуючись на зазначеній версії в маніфесті (див. нижче). Також для кожної версії Firefox використовуються різні файли опису інтерфейсів (файли з розширенням xpt).

Для версій Firefox від 4 до 18 включно слід використовувати xulrunner-6.0 або вище та версію бібліотеки адаптера для Firefox-6 цієї « Технології зовнішніх компонентів» . Із версії Firefox-19.0 до 22.0 слід використовувати xulrunner із версії 19.0 до 21.0 та версію бібліотеки адаптера для Firefox-19. Із версії Firefox-22.0 слід використовувати xulrunner-22.0 і версію бібліотеки адаптера для Firefox-22, бібліотека адаптера сумісна з новішими версіями xulrunner і Firefox.

За основу під час створення розширення розробник може взяти проєкт AddInFF з каталогу example. У файлі config.cpp потрібно змінити значення текстових змінних на власні значення та згенерувати нові uuid. Імена змінних змінювати не треба. Також у змінній nameFileComponent указати ім'я зовнішньої компоненти (наприклад: AddInNative.dll), а в nameFilePrj – ім'я вихідного файлу проєкту розширення (наприклад: AddInFF.dll). В опціях компілятора, у розділі General-> Additional Include Directories виправити шляхи до заголовкових файлів addn\include, xulrunner-sdk\include. В опціях компонувальника, у розділі General-> Additional Library Directories виправити так, щоб могли бути знайдені каталоги xulrunner-sdk\sdk\lib і xulrunner-sdk\lib та addin\lib зі складу цього постачання. Збирання адаптера для ОС GNU/Linux має виконуватися з прапорами компілятора -fshort-wchar – fno-rtti.

Створення інсталяційного пакета

Інсталяційний пакет для Mozilla Firefox являє собою особливим чином зібраний ZIP-архів із розширенням xpi. Структуру каталогів і файлів можна побачити в каталозі example/PackageFF. Слід звернути увагу на формування файлів install.rdf та install.js. У першому файлі міститься інформація про Ваше розширення. У ньому обов'язково потрібно змінити uuid, що знаходиться під рядком < !-— my package uuid-->, і заповнити рядки після < !-— my component info--> інформацією про створюване розширення. Докладну інформацію про заповнення install.rdf можна знайти на сайті Mozilla: http://developer.mozilla.org/en/Install_Manifests. У файлі install.js міститься скрипт установлення, у якому потрібно в змінній XPCOM_FILES указати назви файлів зовнішньої компоненти та адаптера. Файли 1CEAdnWebFF.xpt із каталогу lib, компоненти та адаптера поміщаються до каталогу Components. Збирання пакета виконується у два етапи:

1. Підкаталог content у каталозі chrome упаковується в ZIP-архів. В архіву змінюється розширення на jar. Після цього каталог content можна видалити.

2. Увесь вміст каталогу PackageFF (не включаючи сам PackageFF) упаковується в один ZIP-архів. Отриманий архів перейменовується відповідно до назви компоненти з розширенням xpi. Для перевірки правильності створеного пакета потрібно в меню Mozilla Firefox вибрати Файл - Відкрити файл… і вибрати щойно створений пакет.

Докладніше дізнатися про створення розширень для Mozilla Firefox можна на сайті Mozilla: http://developer.mozilla.org/en/Creating_XPCOM_Components/Packaging_WebLock#Component_Installation_Overview.

Зовнішні компоненти для Internet Explorer

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

За основу під час створення розширення розробник може взяти проєкт AddInIE з каталогу example. В idl-файлі потрібно змінити назву бібліотеки (наприклад library MyComponenIEtLib) і 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 являє собою CAB-архів. Для його побудови необхідно завантажити MS CAB SDK: http://support.microsoft.com/kb/310618. У каталозі example\PackageIE міститься приклад для побудови інсталяційного пакета. Розробник має змінити назву файлу addin.inf на свою (наприклад, MyComponent.inf). У цей файл внести зміни, що відповідають проєкту компоненти:

• імена файлів, каталогів;
• у змінній LayoutFile та секції inffile указати ім'я свого inf-файлу.

Розробник має обов'язково передбачити способи коректного видалення зовнішньої компоненти, установленої в Internet Explorer за допомогою компонента операційної системи Add/Remove Program.

"1С:Підприємство", починаючи з версії 8.2.11, уміє самостійно визначити результат установлення зовнішньої компоненти. Але якщо передбачається використання компоненти з ранніми версіями "1С:Підприємства", то розробник має обов'язково передбачити спосіб сповіщення користувача про успішне встановлення компоненти.

Докладніше дізнатися про заповнення inf-файлу можна в MSDN або на сайті Microsoft: http://msdn.microsoft.com/en-us/library/aa376858(VS.85).aspx. Усі виконувані файли, що входять до інсталяційного пакета, і сам cab-файл мають бути підписані цифровим підписом розробника. Скрипт побудови cab-файлу наведено в buildcab.bat.

Зовнішні компоненти для Google Chrome

Увага! Ця можливість підтримується лише починаючи з 1С:Підприємства 8.3.1.

Створення адаптера для Google Chrome

Адаптер зовнішньої компоненти для Chrome та 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. Розробник компоненти випускає нову версію компоненти. Для включення її до конфігурації потрібно перезібрати адаптери для Chrome та 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.dll), nameFileComponent - ім'я файлу зовнішньої компоненти (наприклад, AddInNative.dll). mimeType містить MIME media type компоненти. Крім того, MIME media type потрібно змінити в ресурсах проєкту, у блоці VERSION. Блок VERSION обов'язково має бути присутній у ресурсах адаптера, оскільки під Windows браузер отримує MIME media type розширення саме з ресурсів. Значення MIMEType не видно в редакторі ресурсів Visual Studio, його задають вручну, редагуючи текст rc-файлу. Папка AddInNPAPI містить проєкт Visual Studio для збирання прикладу під Windows і makefile для збирання під Linux. Під Windows збирається лише 32х-розрядна версія, оскільки Chrome під Windows існує лише 32х-розрядний. Під Linux збираються 32х- і 64х-розрядні версії.

Створення інсталяційного пакета

Інсталяційний пакет для Chrome під Windows створюється у форматі MSI. Під час встановлення пакет має скопіювати файли на диск комп'ютера та зареєструвати розширення як плагін браузера в системному реєстрі. У реєстрі потрібно створити гілку HKCU\Software\MozillaPlugins\@YourCompanyName.com/YouExtensionName (замість YourCompanyName.com та YouExtensionName підставте свої значення), у якій створити такі параметри. Усі параметри рядкового типу.

Найменування	Опис
Description	Відображуваний опис компоненти
Path	Повний шлях до файлу адаптера компоненти
ProductName	Відображувана назва програмного продукту
Vendor	Розробник компоненти
Version	Номер версії

Пакет має бути підписаний цифровим підписом розробника.

У папці example\AddInNPAPISetup міститься проєкт Visual Studio, що збирає пакет MSI для прикладу компоненти. Для кожної компоненти має бути сформований унікальний UUID ProductCode.

Інсталяційний пакет для Chrome під Linux створюється у форматі CRX. Це формат інсталяційних пакетів для розширень Chrome. Докладніше про цей формат можна прочитати на сайті Google Code. Для збирання CRX-файлу на комп'ютері має бути встановлено Chrome. CRX-файл являє собою архів, що містить бінарні модулі зовнішньої компоненти, адаптера, а також файл маніфесту. Усі файли, включені до пакета, мають бути перелічені у файлі маніфесту, причому файл адаптера має фігурувати там з ознакою "public":true, а файл(и) зовнішньої компоненти - без цієї ознаки. Також до пакета можна включити логотип, який потім відображатиметься Chrome поруч із найменуванням компоненти в списку встановлених розширень. Папка PackageChrome містить файли, потрібні для створення інсталяційних пакетів для Linux. Файл manifest.json містить маніфест для Linux. Пакетний файл buildcrx.bat виконує збирання інсталяційних пакетів прикладу для Linux.

Зовнішні компоненти для Safari

Увага! Ця можливість підтримується лише починаючи з 1С:Підприємства 8.3.1.

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

Збирання адаптера для Safari під Windows майже не відрізняється від збирання адаптера для Chrome. Зібраний бінарний модуль адаптера для Chrome може бути використаний і для Safari. Єдина особливість збирання для Safari така. Потрібно простежити, щоб блок ресурсів VERSION знаходився в англійській секції, як це зроблено у ресурсному файлі прикладу. Інакше Safari може не виявити навіть правильно встановленого розширення. Рекомендується під час збирання власного адаптера брати rc-файл із прикладу, включати його до свого проєкту та редагувати поля блоку VERSION.

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

Створення інсталяційного пакета

Під Windows для Safari та Google Chrome використовується один і той самий інсталяційний пакет MSI. Під час установлення компоненти в одному з браузерів компонента стає доступною обом браузерам. Створення пакета описано вище, у розділі про Google Chrome.

Під 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-архів. Для роботи з Веб-клієнтом і тонким клієнтом – це обов'язкова умова. До нього мають увійти власне компоненти для ОС Windows (x86, x86_64), GNU/Linux (x86, x86_64), створені розширення для Internet Explorer (x86, x86_64) та Firefox (Windows x86, GNU/Linux x86 і x86_64). До складу архіву включається файл MANIFEST.XML з описом вмісту:

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

<
bundle xmlns="http://v8.1c.ru/8.2/addin/bundle">

<
component os="Windows" path="AddIn_FF6Windows_x86.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="i386" client="Firefox" clientVersion="6.*" />

<
component os="Linux" path="AddIn_FF6Linux_x86.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="i386" client="Firefox" clientVersion="6.*" />

<
component os="Linux" path="AddIn_FF6Linux_x86_64.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="x86_64" client="Firefox" clientVersion="6.*" />

<
component os="Windows" path="AddIn_FF19Windows_x86.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="i386" client="Firefox" clientVersion="19.*" />

<
component os="Linux" path="AddIn_FF19Linux_x86.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="i386" client="Firefox" clientVersion="19.*" />

<
component os="Linux" path="AddIn_FF19Linux_x86_64.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="x86_64" client="Firefox" clientVersion="19.*" />

<
component os="Windows" path="AddIn_FF22Windows_x86.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="i386" client="Firefox" clientVersion="22.*" />

<
component os="Linux" path="AddIn_FF22Linux_x86.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="i386" client="Firefox" clientVersion="22.*" />

<
component os="Linux" path="AddIn_FF22Linux_x86_64.xpi" type="plugin" object="@vendor.ru/ClassService;
1" arch="x86_64" client="Firefox" clientVersion="22.*" />

<
component os="Windows" path="Addin_IEWindows_x86.cab" type="plugin" object="MyComponenIE.AddInServiceEx" arch="i386" client="MSIE" />

<
component os="Windows" path="AddIn_IEWindows_x86_64.cab" type="plugin" object=" MyComponenIE.AddInServiceEx" arch="x86_64" client="MSIE" />

<
component os="Windows" path="AddIn_NPAPIWindows_x86.msi" type="plugin" object=" application/component-example-1" arch="i386" client="Chrome" />

<
component os="Linux" path="AddIn_ChrLinux_x86.crx" type="plugin" object=" application/component-example-1" arch="i386" client="Chrome" />

<
component os="Linux" path="AddIn_ChrLinux_x86_64.crx" type="plugin" object=" application/component-example-1" arch="x86_64" client="Chrome" />

<
component os="Windows" path="AddIn_NPAPIWindows_x86.msi" type="plugin" object=" application/component-example-1" arch="i386" client="Safari" />

<
component os="MacOS" path="AddIn_SafMacOS_x86.pkg" type="plugin" object=" application/component-example-1" arch="i386" client="Safari" />

<
component os="Windows" path="AddInNative.dll" type="native" arch="i386" />

<
component os="Windows" path="AddInNative64.dll" type="native" arch="x86_64" />

<
component os="Linux" path="AddInNative.so" type="native" arch="i386" />

<
component os="Linux" path="AddInNative64.so" type="native" arch="x86_64" />

<
/bundle>
,

Де:

• os – операційна система:
  • Windows;
  • Linux;
• path – назва файлу в архіві;
• type – тип компоненти:
  • plugin – розширення для браузера;
  • native – Native-компонента;
  • com – COM-компонента.
• object – назва об'єкта, який буде створюватися браузером;
• arch – для якої архітектури процесора має використовуватися компонента:
  • i386 – 32-розрядний процесор;
  • x86_64 – 64-розрядний процесор;
• Client – використовується для зазначення браузера, що використовується веб-клієнтом:
  • MSIE – Microsoft Internet Explorer;
  • Firefox – Mozilla Firefox;
• clientVersion – версія браузера.

Відповідність версій clientVersion, зазначених у маніфесті, та версій браузера Firefox:

У разі зміни зовнішніх компонентів (новий реліз, виправлення помилок тощо) нову версію потрібно додавати до імені файлу. Наприклад: AddInNative_1_1.so. Це правило не поширюється на розширення для браузерів. Для них має бути змінено назву object.

Зверніть увагу, що записи для Google Chrome та Safari під Windows посилаються на один і той самий інсталяційний пакет.

Manifest.xml	Firefox
6.*	4.0-18.*
19.*	19.0-21.*
22.0	*

Опис прикладів

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

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

Компоненти реалізують такі властивості та методи:

Властивості

Увімкнено (IsEnabled)

Використання:

Читання та запис.

Опис:

Тип: Булево. Містить стан компоненти.

ЄТаймер (IsTimerPresent)

Використання:

Читання.

Опис:

Тип: Булево. Визначає наявність у компоненти таймера.

Методи

Увімкнути (Enable)

Опис:

Увімкнює об'єкт компоненти.

Синтаксис:

Увімкнути()

Вимкнути (Disable)

Опис:

Вимикає об'єкт компоненти.

Синтаксис:

Вимкнути()

ПоказатиУРядкуСтану (ShowInStatusLine)

Опис:

На 5 секунд виводить у рядок стану отриманий текст.

Синтаксис:

ПоказатиУРядкуСтану(< Текст> )

Параметри:

Текст.

Тип: Рядок. Текст, що виводиться в рядку стану.

УвімкнутиТаймер (StartTimer)

Опис:

Увімкнює таймер компоненти. Щосекунди компонента надсилає повідомлення "1С:Підприємство 8" з параметрами Component, Timer та рядком лічильника системного годинника.

Синтаксис:

УвімкнутиТаймер()

ВимкнутиТаймер (StopTimer)

Опис:

Вимикає таймер компоненти.

Крім того, компонента, розроблена з використанням Native API, додатково реалізує метод ЗавантажитиКартинку().

Синтаксис:

ВимкнутиТаймер()

ЗавантажитиКартинку(LoadPicture)

Опис:

Завантажує зображення із зазначеного файлу та передає його в "1С:Підприємство 8" у вигляді двійкових даних.

Синтаксис:

ЗавантажитиКартинку (< Ім'яФайлу> )

Параметри:

Ім'яФайлу

Тип: Рядок. Ім'я файлу із зображенням.

Засоби розробки та приклади

Як засоби розробки можна застосовувати:

• Microsoft Visual C++,
• Delphi,
• C++ Builder,
• gcc

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

Приклади для роботи з "1С:Підприємством 8.3" розташовуються в підкаталозі VNCOMP83.

ВИ МОЖЕТЕ ПРЯМО ЗАРАЗ СКОПІЮВАТИ ПРИКЛАДИ ЗОВНІШНІХ КОМПОНЕНТІВ
НА ЖОРСТКИЙ ДИСК ВАШОГО КОМП'ЮТЕРА

Копіювати