native api что это
Технология внешних компонентов
Технология внешних компонентов позволяет создавать программы (внешние компоненты), которые будут динамически подключаться и тесно взаимодействовать с системой 1С:Предприятие 8, расширяя ее возможности. Данная технология позволяет подключать к системе 1С:Предприятие 8 различное торговое оборудование: сканеры штрих-кодов, принтеры этикеток и т. д.
Native API
Для создания внешних компонентов используется технология Native API — собственный интерфейс системного программирования 1С:Предприятия 8. Она поддерживает операционные системы Windows и Linux, и дает возможность создавать внешние компоненты, работающие как под одной, так и под другой операционной системой. Компоненты, созданные по технологии Native API, могут быть подключены в толстом клиенте, в тонком клиенте, в веб-клиенте, внешнем соединении и в сервере приложений.
Расширение встроенного языка
Внешние компоненты позволяют расширять встроенный язык новыми объектами. Структуры механизмов внешних компонент максимально приближены к внутренним структурам системы 1С:Предприятие 8, что повышает эффективность работы.
Вызов процедуры обработки событий, контролируемых внешней компонентой
Внешняя компонента может порождать события, обрабатываемые в предопределенной процедуре языка ОбработкаВнешнегоСобытия. Это позволяет подключать к системе 1С:Предприятие 8 сканеры и другие устройства, требующие асинхронного обмена данными.
Добавление страницы свойств в параметры «1С:Предприятие 8»
Внешние компоненты могут добавлять свои страницы свойств в диалог параметров системы 1С:Предприятие 8. Таким образом, торговое оборудование может включаться в систему и управляться стандартным для системы 1С:Предприятие 8 способом.
Сохранение параметров компоненты через механизм сохранения параметров «1С:Предприятие 8»
При сохранении своих параметров внешняя компонента может использовать механизмы системы 1С:Предприятие 8.
Доступ к строке состояния
При работе состояние внешней компоненты может отражаться в панели состояния системы 1С:Предприятие 8.
Внешние компоненты в 1С 8.3
Внешние компоненты
Внешние компоненты 1С — это файлы с расширением dll (или so для Linux), которые представляют из себя динамически подключаемую библиотеку. С помощью внешних компонент можно расширить функциональность платформы 1С.
Внешние компоненты можно использовать на разных операционных системах:
А также может быть 32-х разрядная версия внешней компоненты и 64-х разрядная.
Внешние компоненты могут использоваться при работе через веб-клиент для браузеров:
И в мобильной платформе 1С для мобильных операционных систем:
Существует две технологии создания внешних компонент для 1С:
Внешние компоненты разработанные по технологии COM можно использовать только:
Для подключения внешней компоненты используется метод НачатьПодключениеВнешнейКомпоненты, вторым параметром нужно указать ProgID COM компоненты.
Также можно использовать синхронный метод ПодключитьВнешнююКомпоненту и асинхронный ПодключитьВнешнююКомпонентуАсинх.
На данный момент данная технология является устаревшей, рекомендуется использовать технологию Native API.
Native API
Внешние компоненты разработанные по технологии Native API можно использовать:
Внешняя компонента может быть запакована в ZIP-архив или представлена в виде отдельного файла.
Так как внешние компоненты по технологии Native API могут быть использованы как в Windows, так и в Linux, то желательно помещать в архив с компонентой 5 файлов:
В этом случае при подключении внешней компоненты платформа сама определит какой файл использовать по файлу-манифесту.
Подключение внешней компоненты на клиенте
Перед подключением внешней компоненты на клиенте, ее сначала нужно установить методом НачатьУстановкуВнешнейКомпоненты. Установка выполняется в каталог компьютера клиента %APPDATA%\1C\1Cv8\ExtCompT. Установка выполняется один раз. В дальнейшем перед использованием компоненты ее нужно только подключать. Подключение выполняется методом НачатьПодключениеВнешнейКомпоненты.
Компонента может храниться:
Шелл для синего экрана: Изучаем программирование на Native API на примере шелла
Содержание статьи
Если программе проверки диска требуется исправить ошибки системного раздела, который не может быть отключен во время работы Windows, после перезагрузки программа запускается до открытия окна логина, отображая белые буквы на синем экране. Это — особый режим работы Windows, в котором еще не работает подсистема Win32, зато есть полный доступ к файлам и реестру.
Загрузочный экран
В Windows XP такой режим работы выглядит как синий экран с логотипом в верхнем правом углу, в Windows 2003 цвет этого экрана серый, в Vista и Windows 7 — черный. Самое частое приложение, которое ты можешь наблюдать работающим в этом режиме, это программа проверки диска. Обычно диск проверяется консольной программой chkdsk.exe. Но в загрузочном экране стартует вовсе не оно, как можно было бы подумать, а autochk.exe — приложение, написанное на чистом Native API. Только такие программы способны запуститься до загрузки подсистемы Win32.
Неплохо было бы написать шелл, командную строку для экспериментов, чтобы побродить по системе еще до ее полной загрузки, с возможностью редактировать файлы и реестр. Я загорелся этой идеей и занялся разработкой такого шелла. Первая версия программы была написана с использованием библиотеки ZenWinX, позже я изучил исходный код шелла NCLI из проекта TinyKRNL и решил строить свой собственный шелл на его основе. От использования ZenWinX я отказался, но часть исходного кода оттуда, связанная с обработкой клавиатурных комбинаций, перекочевала в новую версию, чтобы правильнее, чем в NCLI, реализовать работу с клавиатурой. В частности, NCLI даже не поддерживал переключение регистра символов по клавише Shift. К набору команд, доступных в NCLI, добавились команды, написанные мной. Так получилась программа, которую я назвал Native Shell.
Программирование
Программы, которые могут запускаться из «синего экрана», — это native-приложения, то есть такие приложения, которым доступны только функции NT Native API, экспортируемые библиотекой ntdll.dll.
Это набор функций, выполняющихся в режиме ядра, которые можно вызывать из пользовательского режима. Библиотека экспортирует два набора функций — с одинаковыми названиями, но разными префиксами: «Zw» и «Nt». Функции с префиксом «Zw» предназначены для прямого вызова из режима ядра (например, из драйверов), а функции с префиксом Nt — из пользовательского режима (из приложений). При вызове функции с префиксом «Nt» в итоге выполняется тот же код, что и при использовании префикса Zw, но при этом перед исполнением кода параметры функции проходят дополнительную проверку, так как с точки зрения системы пользовательский режим — это ненадежный источник входных данных.
Вообще, при программировании Native-приложений следует иметь в виду, что почти никаких готовых или заданных по умолчанию возможностей в этом режиме нет, разве что вывод букв на экран реализуется сравнительно просто. Все остальные операции, будь то ввод с клавиатуры или установка текущего рабочего каталога, не говоря уж об остальном, реализуется непосредственно самой программой.
Native API непривычен и не слишком удобен для использования, но другие API недоступны. Если в программировании с использованием WinAPI для какого-то действия требуется одна-две функции, то в Native API, возможно, потребуется пять-шесть. Это и не удивительно, ведь каждый вызов WinAPI внутри реализуется как раз вызовом нескольких функций из ntdll.dll.
Настройка проекта
Для написания собственного native-приложения понадобится документация, среда разработки и заголовочные файлы Native API. Функции NT Native API частично документированы в MSDN. Однако там описано далеко не все, что имеется в ntdll, так что информацию следует по возможности искать в других источниках.
В качестве среды разработки может выступить любой редактор кода, а компиляция native-приложения будет производиться утилитой build из Windows Driver Kit, так что его придется установить себе на машину. WDK используется для разработки драйверов, но способен также компилировать native-приложения.
Проект приложения в WDK выглядит как каталог, где лежат файлы исходного кода, рядом с которыми расположен файл конфигурации проекта под именем SOURCES. Так может выглядеть простой nativeпроект:
TARGETNAME=native
TARGETTYPE=PROGRAM
UMTYPE=nt
INCLUDES=$(DDK_INC_PATH)
SOURCES=native.c
PRECOMPILED_INCLUDE=precomp.h
Сборка программы осуществляется командой build, набранной в командной строке Build Environment WDK. Перед сборкой следует скачать заголовочные файлы NDK (Native NT Toolkit), так как стандартных хидеров из WDK недостаточно, чтобы использовать все существующие функции Native API. Каталог ndk следует распаковать в папку, содержащую заголовочные файлы WDK, и прописать к ней путь в файле bin/setenv.bat (в строке «include=»).
Обработка команд
Шелл загрузочного экрана должен вести себя точно так же, как и шелл для любой другой среды, то есть воспринимать команды, набранные с клавиатуры, и выводить на экран результаты исполнения команд в текстовом виде. Чтобы шелл мог воспринимать ввод, он должен самостоятельно получить скан-коды с клавиатуры и преобразовать их в коды символов.
Для чтения с клавиатуры необходимо с помощью функции NtCreateFile открыть устройство клавиатуры как файл. Имя файла при этом будет выглядеть как «DeviceKeyboardClass0».
Параллельно нужно создать событие (объект ядра типа Event), которое будет использоваться для ожидания ввода символов.
Чтение с клавиатуры осуществляется функцией NtReadFile, которой в параметрах переданы хэндл клавиатуры и хэндл события.
IO_STATUS_BLOCK Iosb;
LARGE_INTEGER ByteOffset = 0;
NTSTATUS Status;
RtlZeroMemory(&Iosb, sizeof(Iosb));
Status = NtReadFile(hDriver, hEvent, NULL, NULL, &Iosb, Buffer, *BufferSize, &ByteOffset, NULL);
Следует проанализировать возвращаемое значение функции и при необходимости подождать наступления события с помощью
NtWaitForSingleObject.
if (Status == STATUS_PENDING)
<
Status = NtWaitForSingleObject(hEvent, TRUE, NULL);
>
NtReadFile вернет данные в виде структуры KEYBOARD_INPUT_DATA.
Эта структура имеет следующий формат:
typedef struct _KEYBOARD_INPUT_DATA
<
USHORT UnitId;
USHORT MakeCode;
USHORT Flags;
USHORT Reserved;
ULONG ExtraInformation;
> KEYBOARD_INPUT_DATA, *PKEYBOARD_INPUT_DATA;
Поле MakeCode содержит сканкод нажатой клавиши, а поле Flags — необходимую дополнительную информацию о том, были ли нажаты одновременно Shift, Ctrl или что-то еще. Шелл должен содержать таблицу, из которой по сканкоду и флагам можно выбрать конкретный символ, соответствующий определенному сочетанию клавиш. Полученный символ можно возвратить из собственного аналога стандартной функции getch. Из символов можно складывать строки, а строки — обрабатывать как команды. Среди команд, к слову, следует обязательно предусмотреть команду завершения работы шелла, чтобы Windows могла загружаться в свое обычное состояние. Работа Native-приложения завершается вызовом функции NtTerminateProcess(NtCurrentProcess(), 0);
Вывод текста на экран чрезвычайно прост, он заключается в помещении в строку типа UNICODE_STRING какого-либо текста и последующем вызове функции NtDisplayString:
UNICODE_STRING unic;
RtlInitUnicodeString(&unic, L»Hello, world!n»);
NtDisplayString(&unic);
Функция поддерживает два управляющих символа — возврат каретки «r» и перевод строки «n».
Операции с файлами
Самые элементарные операции для командной строки — это отображение текущего каталога, перемещение между ними и операции над файлами. В native-режиме при всех операциях с файлами система ничего не знает о концепции «текущего каталога». Во всех файловых функциях требуется передавать полный путь, формат которого, к тому же, отличается от привычного. Существует функция, помогающая хранить значение текущего каталога, но сцеплять это значение с именем файла нужно самостоятельно.
Функции для установки и получения текущего каталога определены так:
NTSYSAPI ULONG NTAPI RtlGetCurrentDirectory_U(
ULONG MaximumLength,
PWSTR Buffer
);
NTSYSAPI NTSTATUS NTAPI RtlSetCurrentDirectory_U(
IN PUNICODE_STRING name
);
NTSYSAPI BOOLEAN NTAPI RtlDosPathNameToNtPathName_U(
IN PCWSTR DosPathName,
OUT PUNICODE_STRING NtPathName,
OUT PCWSTR *NtFileNamePart,
OUT CURDIR *DirectoryInfo
);
Целесообразно сохранять путь в DOS-формате. Его можно показывать пользователю без изменений, если он хочет увидеть текущий каталог. При каждой файловой операции придется формировать полный NTпуть к файлу вызовом соответствующей функции или прямой склейкой пути с префиксом.
Одна из необходимых возможностей шелла — это вывод листинга каталога. Чтобы его вывести, программа должна получить список файлов и каталогов текущей директории. Прежде всего, надо открыть каталог функцией NtCreateFile с опцией FILE_LIST_DIRECTORY и указанием флага FILE_DIRECTORY_FILE. Полученный хэндл скармливается функции NtQueryDirectoryFile, которой передается константа FileBothDirectoryInformation и указатель на буфер данных типа FILE_ BOTH_DIR_INFORMATION. Структура этого типа позволяет узнать о файлах и каталогах все их важные параметры: имя, атрибуты, размер и время создания.
typedef struct _FILE_BOTH_DIR_INFORMATION
<
ULONG NextEntryOffset;
ULONG FileIndex;
LARGE_INTEGER CreationTime;
LARGE_INTEGER LastAccessTime;
LARGE_INTEGER LastWriteTime;
LARGE_INTEGER ChangeTime;
LARGE_INTEGER EndOfFile;
LARGE_INTEGER AllocationSize;
ULONG FileAttributes;
ULONG FileNameLength;
ULONG EaSize;
CCHAR ShortNameLength;
WCHAR ShortName[12];
WCHAR FileName[1];
> FILE_BOTH_DIR_INFORMATION, *PFILE_BOTH_DIR_INFORMATION;
При вызове функции NtQueryDirectoryFile можно использовать параметр ReturnSingleEntry = TRUE, тогда за один вызов функции в буфер будет помещена только одна структура FILE_BOTH_DIR_ INFORMATION, а вызвать функцию в цикле придется столько раз, сколько файлов в каталоге. При установке того же параметра в FALSE функция будет вызвана всего один раз, а в буфере окажется массив структур. Перемещаться по нему можно, сдвигая указатель на структуру по смещению, указанному в поле NextEntryOffset. У последнего элемента массива значение этого поля будет NULL.
Функции для стандартных файловых операций, таких как чтение из файла, запись в файл и удаление файла, документированы в MSDN. Их названия NtReadFile, NtWriteFile, NtDeleteFile соответственно, а использование мало чем отличается от привычных функций WinAPI.
Чтобы скопировать файл, нужно просто прочитать его из одного места и записать копию в другом. А вот переименование файла — более комплексная операция, поэтому стоит рассмотреть ее подробнее.
Переименование файла
Существует функция NtSetInformationFile, которая может производить множество различных операций над файлом. Нас интересует операция переименования. Прототип функции выглядит так:
NTSYSCALLAPI NTSTATUS NTAPI NtSetInformationFile(
IN HANDLE FileHandle,
IN PIO_STATUS_BLOCK IoStatusBlock,
IN PVOID FileInformation,
IN ULONG Length,
IN FILE_INFORMATION_CLASS FileInformationClass
);
В параметре FileInformationClass передается константа
FileRenameInformation, означающая операцию переименования. В сочетании с этой константой функция получает в параметре FileInformation указатель на структуру FILE_RENAME_INFORMATION.
typedef struct _FILE_RENAME_INFORMATION
<
BOOLEAN ReplaceIfExists;
HANDLE RootDirectory;
ULONG FileNameLength;
WCHAR FileName[1];
> FILE_RENAME_INFORMATION, *PFILE_RENAME_INFORMATION;
Структура FILE_RENAME_INFORMATION имеет переменную длину, зависящую от длины нового имени файла. Нужно выделить для структуры достаточное количество памяти. Предположим, у тебя есть буфер NewFileName с новым именем файла и его размер в переменной FileNameSize.
PFILE_RENAME_INFORMATION FileRenameInfo;
FileRenameInfo = RtlAllocateHeap(RtlGetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(FILE_RENAME_INFORMATION) + FileNameSize);
После выделения памяти следует скопировать буфер NewFileName в поле структуры FileName и проинициализировать другие ее поля. Поле ReplaceIfExists определяет, заменять ли существующий файл, если его имя совпадает с новым именем файла при переименовании. В параметре RootDirectory может содержаться хэндл другой директории, в которой должен оказаться файл после перемещения.
Проще оставить это поле равным NULL, ведь для перемещения файла в другой каталог достаточно указать в поле FileName полный путь к новому расположению файла в NT-формате. Если осуществляется переименование файла, а не перемещение, в FileName должно быть только имя файла. После инициализации структуры остается только вызвать функцию для осуществления операции:
Размер буфера FileRenameInfo нельзя считать равным sizeof(FILE_ RENAME_INFORMATION), ведь в определении структуры не учтена изменчивая длина поля FileName. Поэтому в четвертом параметре Length следует передать длину структуры, к которой прибавлен размер строки FileName.
Реестр
Для операций с реестром используются документированные в MSDN функции, названия которых оканчиваются на «-Key», например, для чтения из реестра используется NtQueryValueKey.
На уровне Native API реестр выглядит немного не так, как в Win32. Вместо нескольких корневых псевдоключей HKEY_XXX используется единственный ключ «REGISTRY» с двумя подключами «USER» и « MACHINE». Эти два ключа соответствуют «HKEY_USERS» и «HKEY_ LOCAL_MACHINE». Эквивалента ключу «HKEY_CURRENT_USER» нет, ветки разных пользователей следует искать в «USER». Ключу «HKEY_ CLASSES_ROOT» соответствуют разные ветви реестра, располагающиеся как в ветке «USER», так и в «MACHINE». Еще одно отличие от WinAPI в том, что работая с реестром, мы оперируем обычным типом HANDLE, а не специальным типом HKEY.
Дэниэл Мэдден еще в 2006 году написал программу с открытым исходным кодом под названием NtRegEdit — аналог стандартного редактора реестра (regedit.exe). NtRegEdit использует для доступа к реестру только функции Native API, поэтому код из программы можно перенести в свое собственное native-приложение.
В библиотеке ZenWinX также присутствует код, использующий функции реестра. Например, функция winx_register_boot_exec_command умеет, как видно из названия, прописывать команду, выполняющуюся при запуске, то есть выполнять запись в ключ реестра BootExecute.
Библиотека ntreg корейского программиста rodream содержит набор функций для работы с реестром — достаточно просто подключить к своему проекту файлы ntreg.c и ntreg.h, и программа может в него читать и писать. В этой библиотеке отсутствует функция вывода списка ключей и значений из заданной ветки реестра, но, к счастью, ее несложно написать самостоятельно.
Чтобы узнать, какие подключи есть у какого-либо ключа, используется функция NtEnumerateKey.
NTSYSCALLAPI NTSTATUS NTAPI NtEnumerateKey(
IN HANDLE KeyHandle,
IN ULONG Index,
IN KEY_INFORMATION_CLASS KeyInformationClass,
OUT PVOID KeyInformation,
IN ULONG Length,
OUT PULONG ResultLength
);
Имена подключей будут браться из указателя на структуру KEY_ NODE_INFORMATION. В параметр KeyInformationClass записываем константу KeyNodeInformation, в параметр KeyInformation помещаем указатель на структуру. Код для получения всех подключей в итоге будет выглядеть следующим образом:
ULONG ResultLength, i = 0;
char buf[BUFFER_SIZE];
PKEY_NODE_INFORMATION pki = (PKEY_NODE_INFORMATION)buf;
while (STATUS_SUCCESS == NtEnumerateKey(hKey, i++, KeyNodeInformation, pki, BUFFER_SIZE, &ResultLength))
<
;
>
Внутри этого цикла очередное имя подключа доступно как строка WCHAR pki->Name, ее можно выводить на экран или сохранять в какой-нибудь внутренний список. Похожим образом можно получить список всех значений, содержащихся в ключе реестра, только используется другая функция NtEnumerateValueKey с константой KeyValueBasicInformation, а результат оказывается в структуре KEY_ VALUE_BASIC_INFORMATION.
pbi = (PKEY_VALUE_BASIC_INFORMATION)buf;
while (STATUS_SUCCESS == NtEnumerateValueKey(hKey, i++, KeyValueBasicInformation, pbi, BUFFER_SIZE, &ResultLength))
<
;
>
Имя находится в строке pbi->Name, а тип значения (REG_SZ, REG_DWORD или другой) определяется в pbi->Type.
Запуск процессов
Неплохо иметь в шелле возможность запускать другие процессы. Это сразу расширяет применяемость программы, ведь если программа может запускать процессы, ее функциональность уже не ограничена операциями, зашитыми в ее код. Дальнейшее расширение доступных действий в native-режиме можно осуществлять разработкой новых программ. Да и запускать native-приложения, поставляемые с операционной системой, тоже можно. В загрузочном режиме невозможен запуск Win32-приложений, так как процессы подсистемы Win32 при создании требуют уведомления CSRSS о новом процессе (а он еще неактивен). Поэтому подавляющее большинство утилит Windows запуститься не смогут, за исключением лишь немногих программ, таких как autochk.exe, autofmt.exe (аналоги Win32-утилит chkdsk.exe и format.exe для проверки и форматирования диска), srdelayed.exe (программа отложенных операций с файлами).
Чтобы запустить из native-программы другую такую же программу, используется функция RtlCreateUserProcess. Ей передаются параметры запускаемого процесса в виде структуры типа RTL_USER_PROCESS_ PARAMETERS, которая инициализируется специальной функцией RtlCreateProcessParameters. Именно в эту структуру помещают полный путь к исполняемому файлу в NT-формате, название для отображения в списке процессов и командную строку приложения. После запуска функция помещает параметры процесса в заранее приготовленный буфер RTL_USER_PROCESS_INFORMATION. Оттуда берется тред потока и передается в функцию NtResumeThread, чтобы поток начал выполняться. С этого момента новый процесс запущен.
Перед запуском процесса неплохо бы отключаться от обработки клавиатуры, то есть закрыть ее хэндл, а также хэндл обработки ее событий. Это позволит вновь запущенному приложению обрабатывать клавиатуру самостоятельно, без дублирования обработки в шелле. Восстанавливать контроль над клавиатурой можно после завершения запущенного процесса. Чтобы дождаться завершения процесса, нужно всего лишь извлечь его хэндл из поля ProcessHandle структуры RTL_USER_PROCESS_INFORMATION и передать его в функцию NtWaitForSingleObject, которая приостановит выполнение текущего процесса до завершения запущенного.
Для проверки возможности запуска процессов можно запустить autochk.exe так, чтобы запустилась проверка системного диска. Для этого следует в RtlCreateUserProcess передать следующие строки:
Native-приложения — это самый низкий уровень взаимодействия приложения с системой в пользовательском режиме. Режим native-загрузки сочетает в себе почти неограниченный доступ к потрохам системы с возможностью выполнять различные действия в интерактивном режиме. Я уверен, что освоив написание программ на чистом Native API, ты найдешь для них множество интересных применений.
Ключи запуска
Автозапуск native-приложений задается в ветке реестра HKEY_LOCAL_ MACHINECurrentControlSetControlSession Manager. Здесь есть два ключа, позволяющих запустить приложение на этапе загрузки системы. Обычно присутствует только один из них, BootExecute. Это мультистроковый параметр, содержащий строку «autocheck autochk *». После нее можно добавить свою команду запуска. Например, можно поместить native.exe в папку %systemroot% system32, а в BootExecute прописать строку «native». В результате native.exe запустится сразу после autochk.exe при запуске системы. Здесь же можно указать командную строку процесса, например «native some-command».
Второй ключ реестра, через который возможен запуск, носит название SetupExecute и полностью аналогичен BootExecute. Разница между ними в том, что запуск из этих ключей происходит на разных этапах инициализации системы. На этапе запуска из SetupExecute в системе уже создан файл подкачки и инициализированы переменные среды, а на этапе BootExecute еще нет.
Технология создания внешних компонент
Введение
Система программ «1С:Предприятие» предназначена для решения самых разнообразных задач автоматизации деятельности организаций. Она обладает мощными средствами конфигурирования, которые позволяют штатными средствами настроить систему на особенности обработки информации в конкретной организации. В тоже время, «1С:Предприятие» является открытой системой. Для связи с другими программами могут использоваться встроенные средства загрузки-выгрузки информации в текстовом формате, в формате XML, система поддерживает стандарт интеграции программ OLE Automation, предоставляет доступ через web-сервисы. Однако для специальных задач интеграции может потребоваться более тесное взаимодействие между «1С:Предприятием» и другими программами.
Для решения таких задач разработана «Технология внешних компонент». Данная технология позволяет создавать программы, которые будут динамически подключаться и тесно взаимодействовать с системой «1С:Предприятие», расширяя ее возможности. Внешние компоненты позволяют решать широкий спектр специальных задач, в частности, задачи, связанные с использованием различного торгового оборудования совместно с «1С:Предприятием». Внешние компоненты могут быть подключены как к серверу приложения 1С:Предприятия, так и клиентским приложениям, в т.ч. и веб-клиенту.
В комплект поставки входит данное руководство и набор примеров реализации внешних компонент с помощью различных технологий.
В данном руководстве описана технология создания внешних компонент с использованием Native API и COM.
Структура каталогов комплекта поставки «Технологии внешних компонент»
Каталог include содержит набор включаемых заголовочных файлов для создания внешних компонент.
Каталог lib содержит статические библиотеки для построения расширений для браузеров Mozilla Firefox, Google Chrome, Safari и Internet Explorer.
Каталог example содержит примеры внешних компонент, разработанных с использованием COM и Native API. В этом же каталоге находятся примеры расширений для браузеров и для мобильной платформы.
Каталог template содержит шаблон для создания компоненты, разработанной по технологии Native API.
Каталог templateMobile содержит шаблон для создания компоненты, разработанной по технологии Native API для мобильной платформы.
Создание компонент c использованием технологии Native API
Эта технология позволяет создавать внешние компоненты, которые могут подключаться как в клиентском приложении, так и на сервере приложений «1С:Предприятие», в версиях для Windows, Linux, а также Windows Runtime, Android и iOS.
Для операционных систем Windows Runtime, Android и iOS использование пользовательского интерфейса запрещено.
Внешняя компонента реализует один или несколько объектов компоненты, которые могут использоваться в «1С:Предприятии». Каждый объект компоненты должен наследоваться от абстрактного класса IComponentBase (файл ComponentBase.h входит в комплект поставки) и реализовать все его методы.
Внешняя компонента, разработанная по этой технологии, должна экспортировать из библиотеки четыре функции:
const WCHAR_T* GetClassNames()
Получение списка имен объектов компоненты.
long GetClassObject(const WCHAR_T* clsName, IComponentBase** pIntf)
Тип: IComponentBase**. Указатель на переменную, в которую нужно записать адрес вновь созданного объекта.
Создание экземпляра объекта компоненты. Если объект не может быть создан или не найден объект с указанным именем – возвращается 0.
long DestroyObject(IComponentBase** pIntf)
Тип: IComponentBase**. Указатель на объект компонеты.
Удаление экземпляра ранее созданного объекта. Компонента должна своими средствами удалить объект и освободить используемую им память. При успешном завершении возвращается 0, иначе – код ошибки (Runtime error).
AppCapabilities SetPlatformCapabilities(const AppCapabilities capabilities)
Устанавливает версию поддерживаемых платформой возможностей. Компонента должна вернуть версию, с которой она может работать. Если функция не реализована, то для компоненты не будут доступны возможности вывода сообщений, запроса информации о платформе.
Компонента должна вернуть поддерживаемый тип подключения, с которым она может работать. Если функция не реализована, то компонента будут подключаться в зависимости от режима совместимости конфигурации.
Интерфейс компоненты
bool Init(void* Interface)
При загрузке «1С:Предприятие» инициализирует объект компоненты, вызывая метод Init и передавая указатель на IAddInDefBase. Объект может сохранить этот указатель для дальнейшего использования. Объект должен возвратить true, если инициализация прошла успешно, и false при возникновении ошибки.
bool setMemManager(void* memManager)
Установка менеджера памяти для компоненты. При вызове методов компоненты и передаче возвращаемых значений, которые не могут быть переданы полностью через стек, компонента должна выделять память с помощью функции AllocMemory, предоставляемую менеджером памяти. «1С:Предприятие» впоследствии освободит эту память с помощью функции FreeMemory.
ВАЖНО : нельзя выделять память для возврата значений с помощью new или malloc, т.к. это приведет к утечке памяти и к нестабильности работы программы.
«1С:Предприятие» вызывает этот метод для получения информации о компоненте. Например: версия 3.56 — число 3560.
Возвращаемое значение: нет.
«1С:Предприятие» вызывает этот метод при завершении работы с объектом компоненты. Этот метод вызывается независимо от результата инициализации объекта (метод Init).
bool RegisterExtensionAs(WCHAR_T** wsExtName)
В переменную wsExtName помещается наименование расширения. Память для строки выделяется объектом компоненты функцией AllocMemory менеджера памяти. «1С:Предприятие» освобождает эту память вызовом FreeMemory.
Возвращает количество свойств данного расширения, 0 – при отсутствии свойств.
long FindProp(const WCHAR_T* wsPropName);
const WCHAR_T* GetPropName(long lPropNum, long lPropAlias)
В возвращаемое значение помещается имя свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, возвращается NULL. Память для строки выделяется объектом компоненты функцией AllocMemory менеджера памяти. «1С:Предприятие» освобождает эту память вызовом FreeMemory.
bool GetPropVal(const long lPropNum, tVariant* pvarPropVal)
Тип: tVariant*. Указатель на структуру tVariant, содержащую при возврате значение свойства.
В переменную pvarPropVal помещается значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует или недоступно для чтения, должен иметь тип VTYPE_EMPTY. Если возвращаемое значение имеет тип строка, то компонента выделяет память для нее функцией AllocMemory. «1С:Предприятие» освободит эту память.
bool SetPropVal(const long lPropNum, tVariant* pvarPropVal);
Тип: tVariant*. Структура tVariant, содержащая новое значение свойства.
Переменная pvarPropVal содержит значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, недоступно для записи или тип переданного pvarPropVal не совместим, метод должен возвратить false.
bool IsPropReadable(const long lPropNum)
Возвращается флаг возможности чтения свойства с порядковым номером lPropNum: false — свойство недоступно для чтения, true — свойство допускает чтение. Если свойство с таким номером отсутствует, метод должен возвращать false.
bool IsPropWritable(const long lPropNum)
Возвращается флаг возможности записи свойства с порядковым номером lPropNum: false — свойство недоступно для записи, true — свойство допускает запись. Если свойство с таким номером отсутствует, метод должен возвращать false.
Первый метод имеет порядковый номер 0. Первый параметр метода имеет порядковый номер 0.
long FindMethod(const WCHAR_T* wsMethodName);
const WCHAR_T* GetMethodName(const long lMethodNum, const long lMethodAlias)
Возвращается имя метода с порядковым номером; если свойство с таким номером отсутствует, возвращается NULL. Память для строки выделяется объектом компоненты функцией AllocMemory менеджера памяти. «1С:Предприятие» освобождает эту память вызовом FreeMemory.
long GetNParams(const long lMethodNum)
Возвращается количество параметров метода с порядковым номером lMethodNum; если метод с таким номером отсутствует или не имеет параметров, возвращается 0.
bool GetParamDefValue(const long lMethodNum, const long lParamNum, tVariant* pvarParamDefValue)
Тип: tVariant*. Указатель на структуру tVariant, содержащую при возврате значение параметра по умолчанию.
В переменную pvarParamDefValue помещается значение по умолчанию параметра с номером lParamNum метода с порядковым номером lMethodNum. В pvarParamDefValue помещается тип VTYPE_EMPTY, если метод с таким номером отсутствует, не имеет параметра с номером или параметр не имеет значения по умолчанию. В случае, если значение по умолчанию имеет тип VTYPE_PSTR, VTYPE_PWSTR или VTYPE_BLOB, компонента выделяет память функцией AllocMemory менеджера памяти, записывает туда данные и сохраняет этот адрес в соответствующем поле структуры. «1С:Предприятие» освободит эту память вызовом FreeMemory.
bool HasRetVal(const long lMethodNum)
Возвращается флаг наличия у метода с порядковым номером lMethodNum возвращаемого значения: true для методов с возвращаемым значением и false в противном случае.
bool CallAsProc(const long lMethodNum, tVariant* paParams, const long lSizeArray)
Выполняется метод с порядковым номером lMethodNum. Если метод возвращает false, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров выделяется и освобождается «1С:Предприятием».
bool CallAsFunc(const long lMethodNum, tVariant* pvarRetValue, tVariant* paParams, const long lSizeArray)
Тип: tVariant*. Указатель на структуру tVariant, содержащую возвращаемое значение.
Выполняется метод с порядковым номером lMethodNum. Если метод возвращает false, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров выделяется «1С:Предприятием». Если возвращаемое значение имеет тип строка или двоичные данные, компонента выделяет память функцией AllocMemory менеджера памяти, записывает туда данные и сохраняет этот адрес в соответствующем поле структуры. «1С:Предприятие» освободит эту память вызовом FreeMemory.
Локализация
void SetLocale(const WCHAR_T* wsLocale)
«1С:Предприятие» вызывает этот метод для локализации компоненты в соответствии с используемым кодом локализации. Компонента может настроить свое окружение для правильного вывода информации.
Интерфейс 1С:Предприятия
При инициализации объекта компоненты, ему передается указатель на интерфейс 1С:Предприятия, с помощью которого можно вызывать ниже перечисленные методы. Следует помнить, что эти методы не будут работать на сервере приложений.
bool AddError(unsigned short wcode, const WCHAR_T* source, const WCHAR_T* descr, long scode)
Добавляет информационное сообщение при работе методов расширения языка. Если возвращаемое значение true – информация об ошибке успешно добавлена. Если scode имеет не нулевое значение – будет сгенерировано исключение, которое может быть перехвачено и обработано средствами встроенного языка «1С:Предприятия».
Возможные коды сообщений и поведение 1С:Предприятия подробно описаны в разделе «Информационные сообщения о работе объекта» для COM-компонент.
bool RegisterProfileAs(WCHAR_T* wsProfileName)
Регистрирует список параметров компоненты с именем wsProfileName.
bool Read(WCHAR_T* pszPropName, tVariant* pVal, long* pErrCode, WCHAR_T** errDescriptor)
Тип: WCHAR_T*. Имя параметра
Читает сохраненное значение параметра компоненты с именем pszPropName. В случае неудачи чтения, и ненулевого значения errDescriptor, «1С:Предприятие» выделит память и поместит описание ошибки. Компонента должна освободить память вызовом FreeMemory. Для возвращаемых данных типа строка, память также выделяется «1С:Предприятие»м и адрес сохраняется в соответствующем поле структуры tVariant. Компонента должна освободить ее вызовом FreeMemory.
bool Write(WCHAR_T* pszPropName, tVariant* pVar)
Тип: WCHAR_T*. Имя параметра
Тип: tVariant _t*. Указатель на значение параметра
Сохраняет значение параметра компоненты с именем pszPropName. В случае неудачи возвращается false.
bool SetEventBufferDepth( long lDepth)
Устанавливает размер очереди событий для данного объекта. Если текущее количество событий в очереди больше устанавливаемой длины, последние события удаляются.
Возвращается размер очереди событий для данного объекта.
bool ExternalEvent(WCHAR_T* wsSource, WCHAR_T* wsMessage, WCHAR_T* wsData)
Помещает событие в очередь, записывая источник события, наименование и параметры события. При обработке события эти данные передаются процедуре ОбработкаВнешнегоСобытия. При вызове метода ExternalEvent дальнейшая обработка события происходит следующим образом: событие записывается в очередь событий (если очередь полностью занята, событие теряется), затем при отсутствии системных событий из очереди берется первое событие (если очередь не пуста) и запускается процесс обработки внешних событий. Этот процесс повторяется для всех объектов внешних компонент. Таким образом, обработка внешних событий синхронизируется с обработкой системных событий.
Очищает очередь событий, удаляя все присутствующие в очереди события.
bool SetStatusLine(WCHAR_T* wsStatusLine)
Устанавливает текст строки состояния.
Инициализирует строку состояния.
IInterface* GetInterface(Interfaces iface)
Запрашивает интерфейс платформы. Если запрашиваемый интерфейс поддерживается платформой, будет возвращен указатель на интерфейс. Иначе — 0.
bool Confirm(const WCHAR_T* queryText, tVariant* retVal)
Выводит диалог с текстом, заданным параметром queryText, и кнопками ОК и Отмена.
bool Alert(const WCHAR_T* text)
Тип: WCHAR_T*. Текст сообщения.
Выводит простой диалог уведомления с текстом, заданным параметром text и кнопкой ОК.
Запрашивает информацию о платформе. При подключении компоненты в веб-клиенте версии платформы ниже 8.3.3, будет заполнено только поле Application структуры AppInfo.
Запрашивает информацию о типе подключения компоненты.
Соответствие типов tVariant и 1С:Предприятия
Соответствие между типами 1С:Предприятия и COM:
Типы VTYPE_INTERFACE, VTYPE_VARIANT не поддерживаются.
Примечание:
Числовые значения, переданные в качестве параметров из веб-клиента, могут приходить с любым числовым типом.
Тип VTYPE_BLOB не поддерживается в веб-клиенте.
Особенности разработки компонент с использованием Native API
Компонента с использованием этой технологии является платформозависимой. Поэтому разработчик должен строить вариант компоненты как для x86 платформы, так и для x86-64. В процессе использования, разработчик конфигурации определит тип платформы и загрузит нужный вариант компоненты.
Так же следует помнить, что компонента может быть загружена на сервере приложений 1С:Предприятия под управлением любой ОС. Поэтому желательно реализацию делать кроссплатформенной.
«1С:Предприятие» работает со строками в формате Unicode (WCHAR_T) с размером символа 2 байта. Размерность совпадает со встроенным типом wchar_t для ОС Windows, но может отличаться для остальных ОС, где, например, размер wchar_t, может составлять 4 байта. Разработчик компоненты должен самостоятельно выполнять преобразование символьных данных этого типа.
Если внешняя компонента использует дополнительные модули, это нужно указывать в документации к компоненте. Используемые не системные run-time библиотеки должны быть статически включены в компоненту (если позволяет лицензия на run-time библиотеку), так как на компьютере, где будет использоваться компонента, их может не оказаться или они могут быть другой версии. Так же в компоненту для Windows нужно включать манифест.
При возникновении исключительных ситуаций, они должны быть перехвачены и обработаны в компоненте, а информация о них передана в «1С:Предприятие» с помощью метода AddError.
В случае использования компоненты на сервере приложений 1С:Предприятия, внешние события не обрабатываются. Также не будут обрабатываться методы работы со строкой статуса и сохранения параметров.
Компонента может возвращать любые двоичные данные, например – сформированное изображение штрих-кода. Для этого данные помещаются в поле pstrVal структуры tVariant, в strLen – размер данных, а тип устанавливается в VTYPE_BLOB. «1С:Предприятие» использует для них тип ДвоичныеДанные.
Значение даты передается во внешнюю компоненту в виде структуры tm и указанием типа VTYPE_TM. Компонента может вернуть значение даты как в struct tm, так и в типе DATE Windows, указав тип VTYPE_DATE. «1С:Предприятие» обработает его корректно.
Возвращаемые значения типа VTYPE_ARRAY и VTYPE_BYREF не поддерживаются.
Настройки Web-публикации для мобильной платформы «1С:Предприятие»
Во время настройки Web-публикации следует провести следующее действие. В настройках http-сервера необходимо добавить типы MIME для следующих расширений:
Тип MIME: application/octet-stream
ОС Windows Runtime
Для разработки под ОС Windows Runtime требуется установленная минимум Windows 8.1 с MS Visual Studio 2017 (пакет Windows Phone SDK).
Результатом разработки компоненты должна быть группа динамических библиотек *.dll для мобильных и планшетов всех поддерживаемых процессоров.
Примеры проектов внешней компоненты находятся в каталоге \example\NativeAPIMobile\WinRT_Proj\.
Отладка внешней компоненты проводится с помощью проектов, находящихся в поставке mobile.zip\Windows\vcproj.zip:
Перед применением в директорию appx\ необходимо скопировать содержимое соответствующего архива поставки 1cem-XXXXX.appx.
Далее, добавив исходные коды внешней компоненты, для отладки можно использовать стандартные средства MS Visual Studio.
Для Windows Runtime не реализована возможность загрузки динамических библиотек из Web-публикации.
ОС Android
Разработка под ОС Android поддерживает написание кода на языке программирования c++, так и использование технологии Java Native Interface.
Результатом разработки компоненты под ОС Android должна быть группа динамических библиотек *.so для всех поддерживаемых процессоров. В случае использования кода Java, также должен присутствовать файл *.apk. Файл *.apk не является отдельным приложением и не предназначен для самостоятельного запуска. Впоследствии он включается в состав собранного мобильного приложения.
Пример проекта находится в каталоге \example\NativeAPIMobile\Android_Proj\.
Для отладки внешней компоненты следует использовать возможность загрузки динамических библиотек из Web-публикации. Это происходит автоматически после обновления конфигурации (с вложенными библиотеками) на устройстве с Web-публикации на компьютере разработчика.
ОС iOS
Специфика разработки приложений под iOS не позволяет использование несистемных динамических библиотек для публикации в AppStore. В связи с этим разработчик внешней компоненты должен использовать их только для разработки и отладки.
Результатом разработки компоненты под ОС iOS должен быть файл динамической библиотеки *.dylib для целей тестирования, подписанный сертификатом разработчика и бинарный файл для статической линковки *.a для сборщика приложения.
Отладка внешней компоненты проводится с помощью проекта, находящегося в поставке mobile.zip\iOS\prjios.zip.
Далее, добавив исходные коды внешней компоненты, для отладки можно использовать стандартные средства Xcode.
Для отладки внешней компоненты также можно использовать возможность загрузки динамических библиотек из Web-публикации. Это происходит автоматически после обновления конфигурации (с вложенными библиотеками) на устройстве с Web-публикации на компьютере разработчика.
Начиная с версии ОС iOS 10.0, стала недоступна возможность использования динамических библиотек из Web-публикации. В этом случае, для целей тестирования следует использовать бинарный файл статической библиотеки *.a.
Подпись сертификатом разработчика
Подпись сертификатом разработчика выполняется с помощью утилиты codesign следующей командой:
Статическая библиотека
Статическая библиотека *.a предназначена для сборки конечного приложения путем влинковки внешней компоненты в платформу.
Для исключения конфликта имен, код внешней компоненты должен находится в собственном уникальном пространстве имен. Наименование пространства имен должно соответствовать имени внешней компоненты или включать его как составляющую.
Регистрация компоненты производится статически при загрузке приложения. Соответствующий код можно увидеть в примере.
Пример проекта находится в каталоге \example\NativeAPIMobile\iOS_Proj\.
Создание компонент с использованием технологии COM
Технология внешних компонент с использованием COM может также применяться в «1С:Предприятии» более ранних версий (7.7, 8.0 и 8.1).
Создание компонент под Windows Runtime, Android и iOS, с использованием данной технологии, невозможно.
При использовании функции ПодключитьВнешнююКомпоненту( ) ProgID COM-объекта компоненты передается в качестве параметра функции и также может представляться строкой вида ProgID1| ProgID2|. |ProgIDX.
Инициализация и выгрузка компоненты
Для инициализации и выгрузки компоненты используется интерфейс IInitDone. Этот интерфейс наследован от IUnknown и предназначен для инициализации объекта и завершения работы с объектом.
HRESULT Init(IDispatch *pBackConnection)
Тип: IDispatch. Указатель на интерфейс 1С:Предприятия.
При загрузке «1С:Предприятие» инициализирует объект компоненты, вызывая метод Init и передавая указатель на IDispatch. Объект может сохранить этот указатель для дальнейшего использования. Все остальные интерфейсы 1С:Предприятия объект может получить, вызвав метод QueryInterface переданного ему интерфейса IDispatch. Объект должен возвратить S_OK, если инициализация прошла успешно, и E_FAIL при возникновении ошибки. Данный метод может использовать интерфейс IerrorLog для вывода информации об ошибках. При этом инициализация считается неудачной, если одна из переданных структур EXCEPINFO имеет поле scode, не равное S_OK. Все переданные в IErrorLog данные обрабатываются при возврате из данного метода. В момент вызова этого метода свойство AppDispatch не определено.
«1С:Предприятие» вызывает этот метод при завершении работы с объектом компоненты. Объект должен возвратить S_OK. Этот метод вызывается независимо от результата инициализации объекта (метод Init).
HRESULT GetInfo(SAFEARRAY** pInfo)
Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT. Память для массива выделяется «1С:Предприятием».
«1С:Предприятие» вызывает этот метод для получения информации о компоненте. В текущей версии 2.0 компонентной технологии в элемент с индексом 0 необходимо записать версию поддерживаемой компонентной технологии в формате V_I4 — целого числа, при этом старший номер версии записывается в тысячные разряды, младший номер версии — в единицы. Например: версия 3.56 — число 3560. В настоящее время все объекты внешних компонент могут поддерживать версию 1.0 (соответствует числу 1000) или 2.0 (соответствует 2000). Память для pInfo выделяется «1С:Предприятием». Метод должен возвращать S_OK.
Объект внешней компоненты обязан реализовать этот интерфейс. При его отсутствии компонента не будет загружена.
Расширение встроенного языка
Для расширения встроенного языка компонента должна реализовать интерфейс ILanguageExtender. Этот интерфейс унаследован от IUnknown и предназначен для расширения встроенного языка 1С:Предприятия. Для использования этого расширения необходимо вызвать функцию СоздатьОбъект (Новый в «1С:Предприятии 8»), передав ей строку вида «AddIn. «, где возвращается методом этого интерфейса. Затем можно использовать созданный объект, вызывая его методы и свойства.
Версия 2.0 позволяет создавать несколько объектов одного типа «AddIn. «, однако компонента должна явно указать поддержку версии 2.0 в методе GetInfo. В противном случае допускается создание только одного объекта.
HRESULT RegisterExtensionAs(BSTR *pExtensionName)
Тип: BSTR*. Наименование расширения встроенного языка 1С:Предприятия.
В переменную pExtensionName помещается наименование расширения. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. «1С:Предприятие» освобождает эту память вызовом SysFreeString).
HRESULT GetNProps(long* plProps)
Тип: long*. Указатель на переменную, содержащую при возврате количество свойств расширения.
Возвращает количество свойств данного расширения, 0 – при отсутствии свойств. Память для переменной plProps выделяется «1С:Предприятием».
HRESULT FindProp(BSTR pszPropName,long* plPropNum)
Тип: BSTR. Наименование свойства.
Тип: long*. Указатель на переменную, содержащую при возврате порядковый номер свойства.
HRESULT GetPropName(long lPropNum,long lAliasNum,BSTR* pPropName)
Тип: BSTR*. Указатель на строку, содержащую при возврате наименование свойства.
В переменную pPropName помещается имя свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, в pPropName помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. «1С:Предприятие» освобождает эту память вызовом SysFreeString).
HRESULT GetPropVal(long lPropNum,VARIANT* pvPropVal)
Тип: VARIANT*. Указатель на структуру VARIANT, содержащую при возврате значение свойства.
В переменную pvPropVal помещается значение свойства с порядковым номером lPropNum, если свойство с таким номером отсутствует или недоступно для чтения, переменная должна иметь тип VT_EMPTY.
HRESULT SetPropVal(long lPropNum, VARIANT* pvPropVal)
Тип: VARIANT*. Структура VARIANT, содержащая новое значение свойства.
Переменная pvPropVal содержит значение свойства с порядковым номером lPropNum; если свойство с таким номером отсутствует, недоступно для записи или тип переданного pvPropVal не приводится к необходимому, метод должен возвратить S_FALSE.
HRESULT IsPropReadable(long lPropNum, BOOL* pboolPropReadable)
Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг возможности чтения свойства.
В переменную pboolPropReadable помещается флаг возможности чтения свойства с порядковым номером lPropNum: FALSE(0) — свойство недоступно для чтения, TRUE(1) — свойство допускает чтение. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.
HRESULT IsPropWritable(long lPropNum, BOOL* pboolPropWritable)
Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг возможности записи свойства.
В переменную pboolPropWritable помещается флаг возможности записи свойства с порядковым номером lPropNum: FALSE(0) — свойство недоступно для записи, TRUE(1) — свойство допускает запись. Если свойство с таким номером отсутствует, метод должен возвращать S_FALSE.
Первый метод имеет порядковый номер 0. Первый параметр метода имеет порядковый номер 0.
HRESULT GetNMethods(long* plMethods)
Тип: long*. Указатель на переменную, содержащую при возврате количество методов расширения языка.
HRESULT FindMethod(BSTR bstrMethodName, long* plMethNum)
Тип: long*. Указатель на переменную, содержащую при возврате порядковый номер метода с именем methodName.
HRESULT GetMethodName(long lMethodNum, long lAliasNum, BSTR* pbstrMethName)
Тип: BSTR*. Указатель на строку, содержащую при возврате имя метода.
В переменную pbstrMethName помещается имя метода с порядковым номером; если свойство с таким номером отсутствует, в помещается пустая строка. Память для строки выделяется объектом компоненты стандартными системными функциями для работы с COM—строками (например, SysAllocString. «1С:Предприятие» освобождает эту память вызовом SysFreeString).
HRESULT GetNParams(long lMethodNum, long* plMethParams)
Тип: long*. Указатель на переменную, содержащую при возврате количество параметров метода.
В переменную plMethParams помещается количество параметров метода с порядковым номером lMethodNum; если метод с таким номером отсутствует или не имеет параметров, в помещается 0. Память для переменной выделяется «1С:Предприятие»м.
HRESULT GetParamDefValue(long lMethodNum, long lParamNum, VARIANT* pvParamDefVal)
Тип: VARIANT*. Указатель на структуру VARIANT, содержащую при возврате значение параметра по умолчанию.
В переменную pvParamDefVal помещается значение по умолчанию параметра lParamNum метода с порядковым номером lMethodNum. В pvParamDefVal помещается тип VT_EMPTY, если метод с таким номером отсутствует, не имеет параметра с номером или параметр не имеет значения по умолчанию. Память для переменной выделяется «1С:Предприятием».
HRESULT HasRetVal(long lMethodNum,BOOL* pboolHasRetVal)
Тип: BOOL*. Указатель на переменную, содержащую при возврате флаг наличия возвращаемого значения.
В переменную pboolHasRetVal помещается флаг наличия возвращаемого значения у метода с порядковым номером lMethodNum: TRUE для методов с возвращаемым значением и FALSE в противном случае. Память для переменной выделяется «1С:Предприятие»м.
HRESULT CallAsProc(long lMethodNum, SAFEARRAY** pVars)
Тип: SAFEARRAY**. Двойной указатель на массив структур VARIANT, содержащий значения параметров метода. Если метод не имеет параметров, то содержит NULL.
Выполняется метод с порядковым номером lMethodNum. Если метод возвращает E_FAIL, возникает ошибка времени выполнения и выполнение модуля 1С:Предприятия прекращается. Память для массива параметров выделяется «1С:Предприятие»м.
HRESULT CallAsFunc(long lMethodNum, VARIANT* pRetValue, SAFEARRAY** pVars)
Теги в атрибуте name=»…» указывают сборщику полный путь и наименование подсистемы.
Все содержимое тега (тегов) без анализа и изменений вносится сборщиком в корневой тег файла Info.plist.
Описание файла ANDROID_MANIFEST_EXTENSIONS.XML
Файл ANDROID_MANIFEST_EXTENSIONS.XML используется сборщиком только для ОС Android. Предназначен для внесения изменений в манифесте AndroidManifest.xml, например добавления прав, необходимых для внешней компоненты к определенным компонентам или функциональности данного приложения. Файл необязателен и его отсутствие расценивается сборщиком как отсутствие дополнительных изменений в AndroidManifest.xml.
Формат рассмотрим на примере:
После стандартного заголовка XML следует тег с фиксированным атрибутом. Тег аналогичен тегу в файлах AndroidManifest.xml.
Все что находится в тегах вставится в указанную в атрибуте xpath=»…» часть AndroidManifest.xml.
Разрешается добавлять информацию только в тег и (файлов AndroidManifest.xml).
Описание атрибутов для uses-permission, uses-feature и т.п. можно найти в документации разработчика Android.
Не рекомендуется добавлять в теги uses-permission атрибуты, указывающие максимальную версию SDK. Это может привести к конфликтам в случае сборки приложений с несколькими внешними компонентами.
Описание файла WINDOWS_RT_MANIFEST_EXTENSIONS.XML
Файл WINDOWS_RT_MANIFEST_EXTENSIONS.XML используется сборщиком для ОС Windows Runtime. Предназначен для внесения изменений в манифесте AppxManifest.xml, например добавления прав, необходимых для внешней компоненты к определенным компонентам или функциональности данного приложения. Файл необязателен и его отсутствие расценивается сборщиком как отсутствие дополнительных изменений в настройках разрешений.
Формат рассмотрим на примере:
Теги в атрибуте xpath=»…» указывают сборщику пункт назначения параметров «Name=’XXXXX'» в файле AppxManifest.xml.
Описание тегов и можно найти в документации разработчика для Windows.
Правила формирования имени внешней компоненты для мобильной платформы «1C:Предприятие»
В связи с тем, что, в общем случае, в мобильном приложении может использоваться несколько внешних компонент от разных разработчиков, и с целью исключения конфликтов имен необходимо соблюдать следующие правила формирования имени внешней компоненты.
Имя внешней компоненты должно состоять из латинских букв и/или цифр и не может включать пробелы. Разрешается также использования знака подчеркивания (_). Первым символом может быть только буква или символ подчеркивания (_). Имя компоненты чувствительно к регистру клавиатуры.
Если программа создается в организации, у которой есть свой интернет-сайт, и доменное имя такого сайта, например, 1c.com, то имя внешней компоненты должно начинаться с этих же слов, выписанных в обратном порядке: com_1c. Точки заменяются на знак подчеркивания (_). Далее через (_) следует имя самой внешней компоненты.
Если имя сайта противоречит требованиям к имени внешней компоненты, то можно предпринять следующие шаги:
Ограничения в работе внешних компонент
Разработчик должен учитывать, что внешняя компонента может быть подключена как в оконном приложении (тонкий клиент, толстый клиент), так и в консольном (например: на сервере 1С:Предприятия или в веб-клиенте), где может отсутствовать главное окно и оконная система, очередь сообщений, таймеры, использующие очередь сообщений, нет возможности поставить локальный хук, например, на клавиатуру. В этом случае, разработчик компоненты должен самостоятельно позаботиться о создании необходимого окружения для корректной работы внешней компоненты
В случае использования технологии внешних компонент в мобильной платформе запрещен вызов методов
из системного потока, т.к. показ модальных окон в таком случае может вызвать «зависание» приложения.
Для Windows Runtime не реализована возможность загрузки динамических библиотек из Web-публикации.
Для iOS возможность загрузки динамических библиотек из Web-публикации разрешена со стороны ОС только до версии iOS 9.3.5 включительно.
Описание примеров
В поставку настоящей методики входят примеры реализации внешних компонент, разработанных с использованием технологий Native API и СОМ, расширений для Mozilla Firefox, Google Chrome и Internet Explorer. Кроме примера в поставку включен шаблон, позволяющий упростить создание компоненты «с нуля».
Реализации компонент максимально приближены друг к другу (одинаковые идентификаторы, названия и т.д.), что упрощает процесс освоения и разбора различных реализаций.
В связи со спецификой использования, пример для мобильной платформы отличается от остальных. В нем реализуется упрощенный шагомер. Располагается в каталоге \example\NativeAPIMobile\.
Для полной сборки примеров для персонального компьютера, разработчику понадобится CMake, версии не ниже 3.6, NSIS для сборки инсталляторов для ОС Windows, makeself для сборки инсталляторов для ОС GNU/Linux.
Компоненты реализуют следующие свойства и методы:
Примеры внешней компоненты «1С:Предприятие» для персонального компьютера
Свойства
Использование: Чтение и запись.
Описание: Тип: Булево. Содержит состояние компоненты.
Описание: Тип: Булево. Определяет наличие у компоненты таймера.