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

Введение
Структура каталогов
Создание компонент c использованиемтехнологии 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.

Создание компонент c использованием технологии 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

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

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

S_OK — соответствующий метод вызван, ошибок не произошло.
E_FAIL — соответствующий метод вызван, произошла ошибка времени исполнения (runtime error). Исполнение модуля прекращается.
S_FALSE – отсутствует метод, соответствующий переданному lMethodNum.

Локализация

SetLocale

Описание:

Синтаксис:

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

Иконка отсутствует, если используется код 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ообщения = КодСообщения),

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

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

Описание:

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

Этот процесс повторяется для всех объектов внешних компонент. Таким образом, обработка внешних событий синхронизируется с обработкой системных событий.

Синтаксис:

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.

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

Копировать

Курсы программирования 1С:Предприятие 8.2

Другие материалы по теме:
возвращаемое значение:, возвращаемое значение, параметры:, создание, события, интерфейс, свойства, конфигуратор, описание, строка, опис, файл, например, значения, объект, наименование, параметры, предприятие, пример, значение

Материалы из раздела: 1С:Предприятие 8.2 / Разработчикам / Платформа, механизмы и технологии

Другие материалы по теме:

Общесистемные механизмы и принципы

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

Описание процедур и функций

Методика перевода работы пользователей на другую информационную базу

Требования к разработке драйверов подключаемого оборудования (версия 1.5)

Нас находят: native внешняя компонента не вызывается GetClassName, 1с внешние компоненты создание, внешняя Компонента 1с, регистрация и вызов компоненты 1с, внешние компоненты 1с 8 3 на c#, внешняя компонента взаимодействие, addin idl download 1с com, 1с внешняя компонента, 1с предприятие внешние компоненты массив параметр, Технология создания внешних компонент

Мы на Facebook