Extending Phonegap’s Android APIs

Phonegap provides a standard list of APIs that can be exercised in a cross platform manner across all devices.

For device-specific features, PhoneGap provides a system of PlugIns.

An Android-PhoneGap plugin is developed in Java. The main interface IPlugin has an execute() function.

public interface IPlugin {

	/**
	 * Executes the request and returns PluginResult.
	 *
	 * @param action 		The action to execute.
	 * @param args 			JSONArry of arguments for the plugin.
	 * @param callbackId	The callback id used when calling back into JavaScript.
	 * @return 				A PluginResult object with a status and message.
	 */
	PluginResult execute(String action, JSONArray args, String callbackId);

        // ... more ...
}

JavaScript code calls into the native plugin via the PhoneGap.exec method.

    /* src/com/phonegap/api/PluginManager.java */
    /**
     * Receives a request for execution and fulfills it by finding the appropriate
     * Java class and calling it's execute method.
     *
     * PluginManager.exec can be used either synchronously or async. In either case, a JSON encoded
     * string is returned that will indicate if any errors have occurred when trying to find
     * or execute the class denoted by the clazz argument.
     *
     * @param service       String containing the service to run
     * @param action        String containt the action that the class is supposed to perform. This is
     *                      passed to the plugin execute method and it is up to the plugin developer
     *                      how to deal with it.
     * @param callbackId    String containing the id of the callback that is execute in JavaScript if
     *                      this is an async plugin call.
     * @param args          An Array literal string containing any arguments needed in the
     *                      plugin execute method.
     * @param async         Boolean indicating whether the calling JavaScript code is expecting an
     *                      immediate return value. If true, either PhoneGap.callbackSuccess(...) or
     *                      PhoneGap.callbackError(...) is called once the plugin code has executed.
     *
     * @return              JSON encoded string with a response message and status.
     */
    @SuppressWarnings("unchecked")
    public String exec(final String service, final String action,
        final String callbackId, final String jsonArgs,
        final boolean async)

Registration of Plugins

Registration of plugins is in javascript code. A layer of glue code is usually written to hide the ugliness of the PhoneGap.exec command. Rather than have users call PhoneGap.exec() directly, the extension developer provides an Object Oriented class, and have each method in the class call PhoneGap.exec.

In the example below, the author defined a javascript BarcodeScanner class and registers it using the addConstructor method.

Two steps are carried out in the addConstructor:

1. Create a new instance of BarcodeScanner in javascript and registers it. This is accessible in javascript as window.plugins.barcodeScanner
2. Registers the custom Plugin class with a service name. This service name is passed in as the first argument to PhoneGap.exec so that PhoneGap can instantiate the java plugin class and call the execute() method on it.

PhoneGap.addConstructor(function() {
    /* The following registers an instance of BarcodeScanner in window.plugins.barcodeScanner */
    PhoneGap.addPlugin('barcodeScanner', new BarcodeScanner());

    /* The following associates a service name BarcodeScanner with a class com.beetight.barcodescanner.BarcodeScanner */
    /* The service name is the first argument passed into PhoneGap.exec */
    PluginManager.addService("BarcodeScanner","com.beetight.barcodescanner.BarcodeScanner");
});