org.apache.cordova

Class CordovaPlugin

java.lang.Object

org.apache.cordova.CordovaPlugin

Direct Known Subclasses:

CoreAndroid

public class CordovaPlugin
extends java.lang.Object

Plugins must extend this classes and override one of the execute methods.

Field Summary

Fields

Modifier and Type	Field and Description
CordovaInterface	cordova
protected CordovaPreferences	preferences
CordovaWebView	webView

Constructor Summary

Constructors

Constructor and Description
CordovaPlugin()

Method Summary

Modifier and Type	Method and Description
boolean	execute(java.lang.String action, CordovaArgs args, CallbackContext callbackContext) Executes the request.
boolean	execute(java.lang.String action, org.json.JSONArray args, CallbackContext callbackContext) Executes the request.
boolean	execute(java.lang.String action, java.lang.String rawArgs, CallbackContext callbackContext) Executes the request.
protected android.net.Uri	fromPluginUri(android.net.Uri pluginUri) Refer to remapUri() Added in cordova-android@4.0.0
java.lang.String	getServiceName() Returns the plugin's service name (what you'd use when calling pluginManger.getPlugin())
CordovaResourceApi.OpenForReadResult	handleOpenForRead(android.net.Uri uri) Called to handle CordovaResourceApi.openForRead() calls for a cdvplugin://pluginId/ URL.
boolean	hasPermisssion()
void	initialize(CordovaInterface cordova, CordovaWebView webView) Called after plugin construction and fields have been initialized.
void	onActivityResult(int requestCode, int resultCode, android.content.Intent intent) Called when an activity you launched exits, giving you the requestCode you started it with, the resultCode it returned, and any additional data from it.
void	onConfigurationChanged(android.content.res.Configuration newConfig) Called by the system when the device configuration changes while your activity is running.
void	onDestroy() The final call you receive before your activity is destroyed.
java.lang.Object	onMessage(java.lang.String id, java.lang.Object data) Called when a message is sent to plugin.
void	onNewIntent(android.content.Intent intent) Called when the activity receives a new intent.
boolean	onOverrideUrlLoading(java.lang.String url) Allows plugins to handle a link being clicked.
void	onPause(boolean multitasking) Called when the system is about to start resuming a previous activity.
boolean	onReceivedClientCertRequest(CordovaWebView view, ICordovaClientCertRequest request) Called when he system received an SSL client certificate request.
boolean	onReceivedHttpAuthRequest(CordovaWebView view, ICordovaHttpAuthHandler handler, java.lang.String host, java.lang.String realm) Called when the system received an HTTP authentication request.
void	onRequestPermissionResult(int requestCode, java.lang.String[] permissions, int[] grantResults) Called by the system when the user grants permissions
void	onReset() Called when the WebView does a top-level navigation or refreshes.
void	onRestoreStateForActivityResult(android.os.Bundle state, CallbackContext callbackContext) Called when a plugin is the recipient of an Activity result after the CordovaActivity has been destroyed.
void	onResume(boolean multitasking) Called when the activity will start interacting with the user.
android.os.Bundle	onSaveInstanceState() Called when the Activity is being destroyed (e.g. if a plugin calls out to an external Activity and the OS kills the CordovaActivity in the background).
void	onStart() Called when the activity is becoming visible to the user.
void	onStop() Called when the activity is no longer visible to the user.
protected void	pluginInitialize() Called after plugin construction and fields have been initialized.
void	privateInitialize(java.lang.String serviceName, CordovaInterface cordova, CordovaWebView webView, CordovaPreferences preferences) Call this after constructing to initialize the plugin.
android.net.Uri	remapUri(android.net.Uri uri) Hook for redirecting requests.
void	requestPermissions(int requestCode) Called by the Plugin Manager when we need to actually request permissions
java.lang.Boolean	shouldAllowBridgeAccess(java.lang.String url) Hook for allowing page to call exec().
java.lang.Boolean	shouldAllowNavigation(java.lang.String url) Hook for blocking navigation by the Cordova WebView.
java.lang.Boolean	shouldAllowRequest(java.lang.String url) Hook for blocking the loading of external resources.
java.lang.Boolean	shouldOpenExternalUrl(java.lang.String url) Hook for blocking the launching of Intents by the Cordova application.
protected android.net.Uri	toPluginUri(android.net.Uri origUri) Refer to remapUri() Added in cordova-android@4.0.0

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

webView

public CordovaWebView webView

cordova

public CordovaInterface cordova

preferences

protected CordovaPreferences preferences

Constructor Detail

CordovaPlugin

public CordovaPlugin()

Method Detail

privateInitialize

public final void privateInitialize(java.lang.String serviceName,
                                    CordovaInterface cordova,
                                    CordovaWebView webView,
                                    CordovaPreferences preferences)

Call this after constructing to initialize the plugin. Final because we want to be able to change args without breaking plugins.

initialize

public void initialize(CordovaInterface cordova,
                       CordovaWebView webView)

Called after plugin construction and fields have been initialized. Prefer to use pluginInitialize instead since there is no value in having parameters on the initialize() function.

pluginInitialize

protected void pluginInitialize()

Called after plugin construction and fields have been initialized.

getServiceName

public java.lang.String getServiceName()

Returns the plugin's service name (what you'd use when calling pluginManger.getPlugin())

execute

public boolean execute(java.lang.String action,
                       java.lang.String rawArgs,
                       CallbackContext callbackContext)
                throws org.json.JSONException,
                       java.lang.NoSuchMethodException

Executes the request. This method is called from the WebView thread. To do a non-trivial amount of work, use: cordova.getThreadPool().execute(runnable); To run on the UI thread, use: cordova.getActivity().runOnUiThread(runnable);

Parameters:

action - The action to execute.

rawArgs - The exec() arguments in JSON form.

callbackContext - The callback context used when calling back into JavaScript.

Returns:

Whether the action was valid.

Throws:

org.json.JSONException

java.lang.NoSuchMethodException

execute

public boolean execute(java.lang.String action,
                       org.json.JSONArray args,
                       CallbackContext callbackContext)
                throws org.json.JSONException,
                       java.lang.NoSuchMethodException

Executes the request. This method is called from the WebView thread. To do a non-trivial amount of work, use: cordova.getThreadPool().execute(runnable); To run on the UI thread, use: cordova.getActivity().runOnUiThread(runnable);

Parameters:

action - The action to execute.

args - The exec() arguments.

callbackContext - The callback context used when calling back into JavaScript.

Returns:

Whether the action was valid.

Throws:

org.json.JSONException

java.lang.NoSuchMethodException

execute

public boolean execute(java.lang.String action,
                       CordovaArgs args,
                       CallbackContext callbackContext)
                throws org.json.JSONException

Executes the request. This method is called from the WebView thread. To do a non-trivial amount of work, use: cordova.getThreadPool().execute(runnable); To run on the UI thread, use: cordova.getActivity().runOnUiThread(runnable);

Parameters:

action - The action to execute.

args - The exec() arguments, wrapped with some Cordova helpers.

callbackContext - The callback context used when calling back into JavaScript.

Returns:

Whether the action was valid.

Throws:

org.json.JSONException

onPause

public void onPause(boolean multitasking)

Called when the system is about to start resuming a previous activity.

Parameters:

multitasking - Flag indicating if multitasking is turned on for app

onResume

public void onResume(boolean multitasking)

Called when the activity will start interacting with the user.

Parameters:

multitasking - Flag indicating if multitasking is turned on for app

onStart

public void onStart()

Called when the activity is becoming visible to the user.

onStop

public void onStop()

Called when the activity is no longer visible to the user.

onNewIntent

public void onNewIntent(android.content.Intent intent)

Called when the activity receives a new intent.

onDestroy

public void onDestroy()

The final call you receive before your activity is destroyed.

onSaveInstanceState

public android.os.Bundle onSaveInstanceState()

Called when the Activity is being destroyed (e.g. if a plugin calls out to an external Activity and the OS kills the CordovaActivity in the background). The plugin should save its state in this method only if it is awaiting the result of an external Activity and needs to preserve some information so as to handle that result; onRestoreStateForActivityResult() will only be called if the plugin is the recipient of an Activity result

Returns:

Bundle containing the state of the plugin or null if state does not need to be saved

onRestoreStateForActivityResult

public void onRestoreStateForActivityResult(android.os.Bundle state,
                                            CallbackContext callbackContext)

Called when a plugin is the recipient of an Activity result after the CordovaActivity has been destroyed. The Bundle will be the same as the one the plugin returned in onSaveInstanceState()

Parameters:

state - Bundle containing the state of the plugin

callbackContext - Replacement Context to return the plugin result to

onMessage

public java.lang.Object onMessage(java.lang.String id,
                                  java.lang.Object data)

Called when a message is sent to plugin.

Parameters:

id - The message id

data - The message data

Returns:

Object to stop propagation or null

onActivityResult

public void onActivityResult(int requestCode,
                             int resultCode,
                             android.content.Intent intent)

Called when an activity you launched exits, giving you the requestCode you started it with, the resultCode it returned, and any additional data from it.

Parameters:

requestCode - The request code originally supplied to startActivityForResult(), allowing you to identify who this result came from.

resultCode - The integer result code returned by the child activity through its setResult().

intent - An Intent, which can return result data to the caller (various data can be attached to Intent "extras").

shouldAllowRequest

public java.lang.Boolean shouldAllowRequest(java.lang.String url)

Hook for blocking the loading of external resources. This will be called when the WebView's shouldInterceptRequest wants to know whether to open a connection to an external resource. Return false to block the request: if any plugin returns false, Cordova will block the request. If all plugins return null, the default policy will be enforced. If at least one plugin returns true, and no plugins return false, then the request will proceed. Note that this only affects resource requests which are routed through WebViewClient.shouldInterceptRequest, such as XMLHttpRequest requests and img tag loads. WebSockets and media requests (such as

shouldAllowNavigation

public java.lang.Boolean shouldAllowNavigation(java.lang.String url)

Hook for blocking navigation by the Cordova WebView. This applies both to top-level and iframe navigations. This will be called when the WebView's needs to know whether to navigate to a new page. Return false to block the navigation: if any plugin returns false, Cordova will block the navigation. If all plugins return null, the default policy will be enforced. It at least one plugin returns true, and no plugins return false, then the navigation will proceed.

shouldAllowBridgeAccess

public java.lang.Boolean shouldAllowBridgeAccess(java.lang.String url)

Hook for allowing page to call exec(). By default, this returns the result of shouldAllowNavigation(). It's generally unsafe to allow untrusted content to be loaded into a CordovaWebView, even within an iframe, so it's best not to touch this.

shouldOpenExternalUrl

public java.lang.Boolean shouldOpenExternalUrl(java.lang.String url)

Hook for blocking the launching of Intents by the Cordova application. This will be called when the WebView will not navigate to a page, but could launch an intent to handle the URL. Return false to block this: if any plugin returns false, Cordova will block the navigation. If all plugins return null, the default policy will be enforced. If at least one plugin returns true, and no plugins return false, then the URL will be opened.

onOverrideUrlLoading

public boolean onOverrideUrlLoading(java.lang.String url)

Allows plugins to handle a link being clicked. Return true here to cancel the navigation.

Parameters:

url - The URL that is trying to be loaded in the Cordova webview.

Returns:

Return true to prevent the URL from loading. Default is false.

remapUri

public android.net.Uri remapUri(android.net.Uri uri)

Hook for redirecting requests. Applies to WebView requests as well as requests made by plugins. To handle the request directly, return a URI in the form: cdvplugin://pluginId/... And implement handleOpenForRead(). To make this easier, use the toPluginUri() and fromPluginUri() helpers: public Uri remapUri(Uri uri) { return toPluginUri(uri); } public CordovaResourceApi.OpenForReadResult handleOpenForRead(Uri uri) throws IOException { Uri origUri = fromPluginUri(uri); ... }

handleOpenForRead

public CordovaResourceApi.OpenForReadResult handleOpenForRead(android.net.Uri uri)
                                                       throws java.io.IOException

Called to handle CordovaResourceApi.openForRead() calls for a cdvplugin://pluginId/ URL. Should never return null. Added in cordova-android@4.0.0

Throws:

java.io.IOException

toPluginUri

protected android.net.Uri toPluginUri(android.net.Uri origUri)

Refer to remapUri() Added in cordova-android@4.0.0

fromPluginUri

protected android.net.Uri fromPluginUri(android.net.Uri pluginUri)

Refer to remapUri() Added in cordova-android@4.0.0

onReset

public void onReset()

Called when the WebView does a top-level navigation or refreshes. Plugins should stop any long-running processes and clean up internal state. Does nothing by default.

onReceivedHttpAuthRequest

public boolean onReceivedHttpAuthRequest(CordovaWebView view,
                                         ICordovaHttpAuthHandler handler,
                                         java.lang.String host,
                                         java.lang.String realm)

Called when the system received an HTTP authentication request. Plugin can use the supplied HttpAuthHandler to process this auth challenge.

Parameters:

view - The WebView that is initiating the callback

handler - The HttpAuthHandler used to set the WebView's response

host - The host requiring authentication

realm - The realm for which authentication is required

Returns:

Returns True if plugin will resolve this auth challenge, otherwise False

onReceivedClientCertRequest

public boolean onReceivedClientCertRequest(CordovaWebView view,
                                           ICordovaClientCertRequest request)

Called when he system received an SSL client certificate request. Plugin can use the supplied ClientCertRequest to process this certificate challenge.

Parameters:

view - The WebView that is initiating the callback

request - The client certificate request

Returns:

Returns True if plugin will resolve this auth challenge, otherwise False

onConfigurationChanged

public void onConfigurationChanged(android.content.res.Configuration newConfig)

Called by the system when the device configuration changes while your activity is running.

Parameters:

newConfig - The new device configuration

requestPermissions

public void requestPermissions(int requestCode)

Called by the Plugin Manager when we need to actually request permissions

Parameters:

requestCode - Passed to the activity to track the request

hasPermisssion

public boolean hasPermisssion()

onRequestPermissionResult

public void onRequestPermissionResult(int requestCode,
                                      java.lang.String[] permissions,
                                      int[] grantResults)
                               throws org.json.JSONException

Called by the system when the user grants permissions

Parameters:

requestCode -

permissions -

grantResults -

Throws:

org.json.JSONException