Плагины BlackBerry 10

Этот раздел содержит подробную информацию о том, как реализовать код нативных плагинов на платформе BlackBerry 10. Перед чтением этого раздела ознакомьтесь с разделом Плагины приложений, чтобы получить общее представление о структуре плагина и его общем JavaScript-интерфейсе. В этом разделе демонстрируется пример плагина echo, который осуществляет взаимодействие между веб-вью BlackBerry Cordova и нативной платформой.

Плагин Echo в основном возвращает строку, которую функция window.echo отправляет из JavaScript:

window.echo = function(str, callback) {
    cordova.exec(callback, function(err) {
        callback('Nothing to echo.');
    }, "Echo", "echo", [str]);
};

Плагин Cordova для BlackBerry 10 содержит как JavaScript-код, так и нативный код, которые взаимодействуют друг с другом через фреймворк, предоставляемый JNEXT. Каждый плагин также должен включать файл plugin.xml.

Создание нативного класса

Для создания нативной части вашего плагина откройте IDE BlackBerry 10 NDK и выберите Файл → Новый → Проект BlackBerry → Нативное расширение → BlackBerry 10. Введите желаемое имя проекта и расположение, а затем нажмите Готово.

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

• *name*_js.hpp: C++ заголовок для кода JNEXT.

• *name*_js.cpp: C++ код для JNEXT.

Нативный интерфейс для расширения JNEXT можно просмотреть в файле заголовка плагина, расположенном в общедоступном каталоге проекта. Он также содержит константы и служебные функции, доступные из нативного кода. Плагин должен быть производным от JSExt, которое определено в plugin.h. То есть, вы должны реализовать следующий класс:

class JSExt
{
public:
    virtual ~JSExt() {};
    virtual string InvokeMethod( const string& strCommand ) = 0;
    virtual bool CanDelete( void ) = 0;
private:
    std::string m_id;
};

Расширение должно включать заголовок plugin.h. В примере Echo вы используете JSExt следующим образом в файле echo_js.hpp.

#include "../public/plugin.h"
#include <string>

#ifndef ECHO_JS_H_
#define ECHO_JS_H_

class Echo : public JSExt
{
public:
    explicit Echo(const std::string& id);
    virtual ~Echo();
    virtual std::string InvokeMethod(const std::string& command);
    virtual bool CanDelete();
private:
    std::string m_id;
};

#endif // ECHO_JS_H_

Атрибут m_id содержит идентификатор JNEXT объекта, который передаётся в класс в качестве аргумента конструктору. Он необходим для того, чтобы нативная сторона могла вызывать события на стороне JavaScript. Метод CanDelete определяет, можно ли удалить нативный объект. Функция InvokeMethod вызывается в результате запроса из JavaScript для вызова метода этого конкретного объекта. Единственным аргументом этой функции является строка, переданная из JavaScript, которую этот метод анализирует, чтобы определить, какой из методов нативного объекта должен быть выполнен. Эти методы реализованы в echo_js.cpp. Вот функция InvokeMethod для примера Echo.

string Echo::InvokeMethod(const string& command) {

    //parse command and args from string
    int index = command.find_first_of(" ");
    string strCommand = command.substr(0, index);
    string strValue = command.substr(index + 1, command.length());

    // Determine which function should be executed
    if (strCommand == "echo") {
        return strValue;
    } else {
        return "Unsupported Method";
    }
}

Нативный плагин также должен реализовать следующие функции обратного вызова:

• extern char* onGetObjList( void );

• extern JSExt* onCreateObject( const string& strClassName, const string& strObjId );

Функция onGetObjList возвращает список классов, поддерживаемых JNEXT, разделённый запятыми. JNEXT использует эту функцию, чтобы определить набор классов, которые JNEXT может создать. Плагин Echo реализует следующее в echo_js.cpp:

char* onGetObjList() {
    static char name[] = "Echo";
    return name;
}

Функция onCreateObject принимает два параметра. Первый — имя запрашиваемого класса, создаваемого со стороны JavaScript, с допустимыми именами, как возвращаемыми в onGetObjList. Второй параметр — уникальный идентификатор объекта класса. Этот метод возвращает указатель на созданный объект плагина. Плагин Echo реализует следующее в echo_js.cpp:

JSExt* onCreateObject(const string& className, const string& id) {
    if (className == "Echo") {
        return new Echo(id);
    }
    return NULL;
}

Создание JavaScript-части плагина

Плагин должен содержать следующие JavaScript-файлы:

• client.js: Это считается клиентской частью и содержит API, доступное для приложения Cordova. API в client.js делает вызовы к index.js. API в client.js также подключает функции обратного вызова к событиям, которые запускают обратные вызовы.

• index.js: Cordova загружает index.js и делает его доступным через мост cordova.exec. Файл client.js делает вызовы к API в файле index.js, который, в свою очередь, делает вызовы к JNEXT для взаимодействия с нативной стороной.

Клиентская и серверная части (client.js и index.js ) взаимодействуют через функцию Cordova.exec. client.js необходимо вызвать функцию exec и предоставить необходимые аргументы. Плагин Echo реализует следующее в файле client.js:

var service = "org.apache.cordova.blackberry.echo",
    exec = cordova.require("cordova/exec");

module.exports = {
    echo: function (data, success, fail) {
        exec(success, fail, service, "echo", { data: data });
    }
};

Компонент index.js использует JNEXT для взаимодействия с нативной стороной. Привязка функции конструктора с именем Echo к JNEXT позволяет выполнять следующие ключевые операции с помощью функции init:

• Укажите необходимый модуль, экспортированный нативной стороной. Имя необходимого модуля должно совпадать с именем файла библиотеки общего использования (файл .so):

  JNEXT.require("libecho")
  

• Создайте объект, используя полученный модуль, и сохраните возвращённый вызовом идентификатор:

  self.m_id = JNEXT.createObject("libecho.Echo");
  

Когда приложение вызывает функцию echo в client.js, этот вызов, в свою очередь, вызывает функцию echo в index.js, где объект PluginResult отправляет данные в ответ client.js. Поскольку аргумент args, переданный в функции, был преобразован функцией JSON.stringfy() и закодирован как URIcomponent, вам необходимо выполнить следующее:

data = JSON.parse(decodeURIComponent(args.data));

Теперь вы можете отправить данные обратно, как показано ниже:

module.exports = {
    echo: function (success, fail, args, env) {
        var result = new PluginResult(args, env),
        data = JSON.parse(decodeURIComponent(args.data)),
        response = echo.getInstance().echo(data);
        result.ok(response, false);
    }
};

Архитектура плагина

Вы можете разместить артефакты плагина, включая файл plugin.xml , JavaScript и C++ исходные файлы и бинарные файлы .so в любой структуре каталогов, при условии, что вы правильно укажете местоположения файлов в файле plugin.xml. Вот типичная структура:

project_directory (>plugin.xml)

• www (>client.js)
• src
  • blackberry10 (>index.js, native >*.cpp, *.hpp)
  • device (>бинарный файл *.so)
  • simulator (>бинарный файл *.so)

Список показывает иерархические отношения между папками верхнего уровня. Скобки показывают содержимое данного каталога. Все имена каталогов отображаются жирным шрифтом. Имена файлов предваряются знаком >.

Файл plugin.xml

Файл plugin.xml содержит имя пространства имён расширения и другие метаданные. Настройте плагин Echo следующим образом:

<plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
    id="org.apache.cordova.blackberry.echo"
    version="1.0.0">
    <js-module src="www/client.js">
        <merges target="navigator" />
    </js-module>
    <platform name="blackberry10">
        <source-file src="src/blackberry10/index.js" />
        <lib-file src="src/blackberry10/native/device/libecho.so" arch="device" />
        <lib-file src="src/blackberry10/native/simulator/libecho.so" arch="simulator" />
        <config-file target="www/config.xml" parent="/widget">
            <feature name="org.apache.cordova.blackberry.echo" value="org.apache.cordova.blackberry.echo" />
        </config-file>
    </platform>
</plugin>