Плагины BlackBerry 10

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

Плагин 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")
  

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

  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>