Условия успешного старта

Поддержка технологии внешних компонент (ТВК) мобильной платформой 1С начиная с 8-го релиза является почти революционным шагом. Особое ее значение проявляется в сегменте приложений для терминалов сбора данных и другого специального оборудования, где дизайн приложения (минус платформы 1С) играет второстепенную роль по отношению к функциональности. Мобильная технология внешних компонент, точно также как и стационарная, поддерживает работу с внешними устройствами. Кроме того, она позволяет расширить функциональность приложений, используя возможности ОС Андроид, напрямую обращаясь к API SDK.

Со стороны программистов 1С с момента выхода к этой технологии проявляется устойчивый интерес. Вместе с тем в библиотеке Инфостарта и в сети пока мало реальных рабочих примеров, пусть даже с закрытым кодом, хотя ее описание и учебный пример опубликованы на официальном ресурсе 1С в открытом доступе. Как мне кажется, есть несколько препятствий для освоения технологии. Во-первых, примеры не содержат указания на среду разработки (кроме компонент для Windows 8 phone, но это выходит за рамки статьи), во-вторых, они скорее предназначены для профессионалов, имеющих опыт программирования на C++ под Android NDK и Java. Огромную трудность представляет отладка и поиск ошибок, половина из которых приводят к "падению" платформы. Для программиста с малым опытом в Android SDK и C++ JNI поиск источника ошибки будет непреодолимой преградой, если учесть, что сама ошибка может быть не в собственном коде, а в мобильной платформе.

В этой статье я попытаюсь объяснить по шагам процедуру создания внешних компонент на трех простых примерах. Но следует предупредить начинающих, что даже собрав и запустив эти примеры, на каждом следующем шаге в процессе самостоятельного освоения, вы будете сталкиваться с большими преградами. "Серебряной пули" на этом пути не существует! Мобильная разработка требует специфического опыта. К освоению технологии лучше приступать, если вы сталкивались с написанием нативных (NativeAPI) компонент для стационарной платформы 1С, знаете как и в какой последовательности платформа вызывает API компоненты, какие внешние интерфейсы и зачем должна реализовать компонента - эти вопросы здесь рассматриваться не будут. Также вам необходим опыт разработки приложений под Андроид. Особое внимание уделите средствам взаимодействия управляемого и неуправляемого кода (JNI). В награду, если у вас получится создать несколько мобильных компонент, вы окажетесь на голову выше не только ваших коллег 1С-ников, но и многих разработчиков Android, которые часто ограничиваются Java, Android SDK и frontend'ом. В отличие от них, вы будете знать такие сложные темы, как JNI, NDK, многопоточность, устройство ядра.

Архитектура

Мобильная платформа предоставляет разработчикам внешних компонент интерфейс IComponetnBase (файл ComponentBase.h). Он является базой функционирования как мобильной так и десктопной внешней компоненты и состоит из интерфейсов:

• IInitDoneBase - шлюз для получения функциональности платформы: загрузка/выгрузка, управление памятью, генерация внешних событий
• ILanguageExtenderBase - описатель типа компоненты, предоставляет возможности для расширения встроенного языка 1С
• LocaleBase - управление локализацией компоненты

При начале работы с компонентой 1С вызывает несколько классических экспортных C-функций из динамической библиотеки компоненты:

• GetClassNames - возвращает имена объектов вашей компоненты, это то, что пишется после на месте <объект> в коде 1С: 

• Новый("AddIn.<псевдоним>.<объект>");

• GetClassObject - создает ваш объект компоненты, реализующий IComponentBase
• DestroyObject - удаляет объект
• SetPlatformCapabilities - получает версию платформы (для мобильной платформы в настоящий момент версия не важна)

Таким образом, наша задача - реализовать методы интерфейса IComponentBase. Минимальную компоненту можно сделать на C++, используя API ядра Linux. Но, к сожалению, их множество очень ограничено, поэтому трудно обойтись без JNI. С его помощью можно создавать и вызывать функции объектов java и, за некоторыми исключениями, написать компоненту полностью. Но перевести весь java-код в JNI очень трудоемко и чревато трудно обнаруживаемыми ошибками. Это может пригодится только, если вы хотите защитить свой код. В обычной практике лучше использовать часть на C++ как промежуточный слой, а главную реализацию сделать на Java.

Разработчики платформы предоставляют нам доступ к движку Java через API getJniEnv() и интерфейс IAndroidComponentHelper. Последний обеспечивает доступ к контексту мобильного приложения через GetActivity() - функцию, возвращающую активность приложения. Класс java, отвечающий за взаимодействие с кодом на C++ реализует интерфейс Runnable. Это - признак многопоточности, т.е. компонента запускается в отдельном потоке (thread) приложения. Одно из следствий этого - невозможность взаимодействия с интерфейсом приложения и создания собственных активностей.

Обратные вызовы платформы из Java-кода функций C++ выполняются через Java native call. Часто в технологии внешних компонент эти вызовы используются для генерации внешних событий.

В примерах я покажу, как создать простейшую компоненту на C++ (пример 1), как вызвать методы классов Java стандартных библиотек Андроида (пример 2) из C++ кода. Пример 3 представит приложение, реализующее все участки архитектуры.

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

В принципе, для создания мобильных внешних компонент необходим компилятор C++ и Java под Android SDK. Для них существует много RAD и вы можете использовать любые по своему вкусу. Содержание этого раздела отражает лишь мой личный опыт использования MS Visual Studio 2017 и Android studio. Но кто-то захочет предпочесть NetBeans, Eclipse и др. - выбор широк.

Для разработки на VS2017 + Android studio на вашем компьютере должны быть:

1. Операционная система Windows 10 pro или выше.
2. Платформа 1С:Предприятие 8.3, необходимо скачать архив свежего релиза мобильной платформы (рекомендуем не ниже 12го!), распаковать и установить сборщик мобильных приложений. (Этот этап и настройку сборщика не описываем, полагаем программисты 1С мобильных приложений знают, как это делать).
3. С сайта ИТС скачать и распаковать в отдельную папку примеры внешних компонент, нам впоследствии понадобятся из них отдельные заголовочные файлы для C++ проекта.
4. Со страницы https://visualstudio.microsoft.com загружаем небольшой установщик Visual studio community edition. Эта версия свободная и может использоваться индивидуальными разработчиками для создания коммерческих продуктов. (Если у вас есть платная версия - конечно используйте ее).
5. Запускаем установщик, после того, как он подготовит среду, ожидаем экран, похожий на этот: Если вы планируете использовать студию только для разработки мобильных компонент, вам достаточно включить флажок "Mobile development with C++". Запускаем установку и ожидаем ее окончания. Все компоненты студия загружает из интернет, поэтому позаботьтесь о хорошем канале.
6. Загружаем установщик Android studio: https://developer.android.com/studio. Запускаем и устанавливаем продукт.
7. Запускаем Android studio, чтобы она загрузила и установила необходимые компоненты, в первую очередь Android SDK.

Пример 1: "Задержка"

Внешняя компонента без использования JNI

Реализация первого примера очень простая, буквально пара строчек кода, которые я приведу в конце раздела (не считая реализации архитектуры компоненты конечно). Вначале сосредоточимся на создании проекта. В Visual studio создаем новый проект с типом C++ cross platform mobile - android - dynamic shared library:

После открытия проекта Visual studio создаст два файла с именем проекта: SharedObject1.h и SharedObject1.cpp. Я их удаляю - мы будем использовать заготовки из шаблона внешних компонент 1С.

На этом рисунке показаны из шаблона, которые вам необходимо включать в проект каждой компоненты. Вносить изменения в них не рекомендуется. Теперь настроим свойства проекта. На закладке General я изменяю имя выходного файла с учетом архитектуры процессора (выделено жирным), чтобы их можно было помещать в архив компоненты без переименования. В качестве компилятора можно использовать любой, я предпочитаю GCC, по отзывам генерирующий более эффективный код для ARM процессоров:

Версию языка (закладка Language с разделе C/C++) установим 11-ю, чтобы использовать преимущества современного C++ при разработке.

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

Компонента = Новый("AddIn.Sample.Infostart2018");

Он наследуется от IComponentBase. Начинающий разработчик может взять за образец файлы AddInNative.h и AddInNative.cpp. В определении класса следует модифицировать перечисления Props и Methods и приватную часть класса. Наш пример будет выполнять задержку в ходе работы приложения на заданное число миллисекунд, логично для этого сделать метод: в перечислении Methods добавим значение eMethDelay. В файле AddInNative.cpp прописываем в статические массивы g_MethodNames и g_MethodNamesRu английское и русское имя метода. Сигнатуры методов задаются в GetNParams, GetParamDefValue и в HasRetValue. Пусть метод Delay принимает один параметр - целое число - количество миллисекунд задержки, соответственно GetNParams должен вернуть 1, HasRetValue - false. Реализацию метода пишем в CallAsProg. В ОС Андроид задержку можно реализовать, вызвав API ядра Linux - sleep или воспользоваться стандартной библиотекой C++ (здесь нам пригодилось использование версии 11 языка). Выберем последний вариант как более универсальный:

long lDelay = numericValue(paParams);
if (lDelay > 0)
  std::this_thread::sleep_for(std::chrono::milliseconds(lDelay));

После компиляции проекта для процессоров ARM и x86 создадим манифест компоненты:

<?xml version="1.0" encoding="UTF-8"?>
<bundle xmlns="http://v8.1c.ru/8.2/addin/bundle" name="ru_infostart_education">
  <component os="Android" path="libru_infostart_education_ARM.so" codeType="c++" type="native" arch="ARM"/>
  <component os="Android" path="libru_infostart_education_x86.so" codeType="c++" type="native" arch="i386"/>
  <component os="Android" path="infostart.apk" codeType="java" type="native" arch="ARM"/>
  <component os="Android" path="infostart.apk" codeType="java" type="native" arch="i386"/>
</bundle>

Если мы хотим ограничиться только первым или вторым примерами, apk-составляющие в архив можно не включать. Независимо от архитектуры устройства, имя разворачиваемой компоненты будет ru_infostart_education - оно нам потребуется в третьем примере, когда мы будет из java делать обратный вызов в библиотеку C++. Помещаем в архив динамические библиотеки so и этот манифест - и компонента готова.

Пример 2: "Информация об устройстве"

Внешняя компонента с вызовами JNI

Задача следующего примера - продемонстрировать вызовы сущностей объектов java из C++. Для этого попробуем получить имя производителя и модели устройства с помощью класса Build. В компоненте реализуем свойство ePropDevice только для чтения. Для настройки сигнатур свойств IComponentBase предоставляет ряд методов, которые должны быть читателю известны по технологии внешних компонент для настольной платформы. Сосредоточимся на коде:

IAndroidComponentHelper* helper = (IAndroidComponentHelper*)m_iConnect->GetInterface(eIAndroidComponentHelper);
pvarPropVal->vt = VTYPE_EMPTY;
if (helper)
{
	WCHAR_T* className = nullptr;
	convToShortWchar(&className, L"android.os.Build");
	jclass ccloc = helper->FindClass(className);
	delete[] className;
	className = nullptr;
	std::wstring wData{};
	if (ccloc)
	{
		JNIEnv* env = getJniEnv();
		jfieldID fldID = env->GetStaticFieldID(ccloc, "MANUFACTURER", "Ljava/lang/String;");
		jstring	jManufacturer = (jstring)env->GetStaticObjectField(ccloc, fldID);
		std::wstring wManufacturer = ToWStringJni(jManufacturer);
		env->DeleteLocalRef(jManufacturer);
		fldID = env->GetStaticFieldID(ccloc, "MODEL", "Ljava/lang/String;");
		jstring	jModel = static_cast<jstring>(env->GetStaticObjectField(ccloc, fldID));
		std::wstring wModel = ToWStringJni(jModel);
		env->DeleteLocalRef(jModel);
		if (wManufacturer.length())
			wData = wManufacturer + L": " + wModel;
		else
			wData = wModel;
		env->DeleteLocalRef(ccloc);
	}
if (wData.length())
	ToV8String(wData.c_str(), pvarPropVal);

Фактически это - классический вызов статических свойств класса java через JNI с той разницей, что указатель на окружение виртуальной машины извлекается не из функции main, а из getJniEnv() или IAndroidComponentHelper. Вспомогательные функции ToWStringJni и ToV8String выполняют преобразования строк и параметров, их код вы найдете в примере к статье. В коде C++ внешней компоненты следует строго следовать правилам программирования JNI, по собственному опыту сформулирую наиболее важные моменты:

• возвращайте как можно раньше указатели сборщику мусора с помощью DeleteLocalRef и DeleteGlobalRef
• локальные указатели преобразовывайте в глобальные, если их следует передавать в другие процедуры, а также если в процессе их "жизни" используются методы интерфейсов 1С (например, передается внешнее событие ExternalEvent)
• при работе с java-строками GetStringChar, а не GetStringUTFChar, не забывайте о ReleaseStringChars. Помните, что в Андроид размер переменной char равен 16 битам

Пример 3: "Состояние экрана"

Внешняя компонента с кодом java

Создадим внешнюю компоненту, отслеживающую событие разблокировки экрана устройства и посылающую об этом оповещение в 1С. В андроиде все оповещения получает класс BroadcastReceiver, который перед регистрацией в контексте приложения предварительно необходимо настроить, указав в отслеживаемые намерения (Intent) и возможно другие параметры. Настройка выполняется в коде или в манифесте приложения. Во внешней компоненте доступен только первый вариант, так как манифест создается сборщиком приложений автоматически. Логика работы компоненты будет реализована на java, а код C++ будет вызывать сущности из apk и  передавать внешние события в 1С. Создание объектов и вызов сущностей из созданной вами компоненты на java точно такое же как в примере 2 для стандартных библиотек - через JNI. Чтобы объекты apk были доступны из C++, они должны быть публичными (public). Для создания java-приложения компоненты сделайте в Android studio проект без активностей, я также удаляю из него лишние ресурсы (папка res), но это не обязательно. Ни ресурсы ни манифест проекта для компоненты значения не имеют и в ней не используются. В проект добавляем класс, реализующий интерфейс Runnable, например так:

И реализуем его как класс внешней компоненты. Для генерации внешних событий будет необходимо вызывать функцию из нашей динамической библиотеки. Имя ее мы задали в манифесте компоненты - "ru_infostart_education", а имя экспортной функции, вызываемой по правилам языка C должно состоять из префика Java_, имени пространства имен в apk (у нас это будет ru.infostart.education) и имени нативной java функции, которую нужно задекларировать в классе. Первые два аргумента зависят от типа функции (статический член класса или нет), остальные аргументы должны соответствовать декларации. Подробнее об этом смотрите в правилах вызова нативных функций из java. После сборки apk в Android studio, его следует переименовать в infostart.apk и поместить в архив.

Подробнее покажем взаимодействие класса LockState с C++ кодом. В нем объявим такой член:

static native void OnLockChanged(long pObject);

Соответствующая функция C в коде компоненты должна быть следующей:

extern "C" JNIEXPORT void JNICALL Java_ru_infostart_education_LockState_OnLockChanged(JNIEnv* env, jclass jClass, jlong pObject)

в ней реализуем генерацию внешнего события в 1С через ExternalEvent. Требует пояснения аргумент pObject - это указатель на интерфейс 1С платформы, который передается в класс LockState в его конструкторе. Он нужен, чтобы вернуть его обратно в экспортную функцию, так как функции типа extern с C++ не могут принадлежать какому-то классу и мы не можем в них получать адреса интерфейсов, который хранит AddInNative. Другое решение данной проблемы - глобальная переменная в коде C++ компоненты, но оно с точки зрения объектно-ориентированного подхода хуже. Приведем код начала класса LockState:

public class LockState implements Runnable {

  // in C/C++ code the function will have name Java__ru_infostart_education_LockState_OnLockChanged
  static native void OnLockChanged(long pObject);

  private long m_V8Object; // 1C application context
  private Activity m_Activity; // custom activity of 1C:Enterprise
  private BroadcastReceiver m_Receiver;

  public LockState(Activity activity, long v8Object)
  {
    m_Activity = activity;
    m_V8Object = v8Object;
  }

  public void run()
  {
    System.loadLibrary("ru_infostart_education");
  }

  public void show()
  {
    m_Activity.runOnUiThread(this);
  }

Член m_Activity необходим для получения контекста приложения, с его помощью можно зарегистрировать BroadcastReceiver. В методе run выполняется загрузка so-библиотеки в управляемый код. Метод show стандартен, он позволяет выполнить код компоненты в контексте вашего приложения.

Полный код этого и предшествующих примеров, а также конфигурацию 1С для их вызовов участники INFOSTART 2018 Education могут получить на форуме конференции. Для всех - ссылка на эти же примеры в приложении.

****************

Видео доклада, прочитанного на конференции INFOSTART EVENT 2018 EDUCATION. Больше статей можно прочитать здесь.

Приглашаем вас на новую конференцию INFOSTART EVENT 2019!