CB-12159 Android: Keystore password prompt won't show up
[cordova-android.git] / framework / src / org / apache / cordova / api / Plugin.java
1 /*
2 Licensed to the Apache Software Foundation (ASF) under one
3 or more contributor license agreements. See the NOTICE file
4 distributed with this work for additional information
5 regarding copyright ownership. The ASF licenses this file
6 to you under the Apache License, Version 2.0 (the
7 "License"); you may not use this file except in compliance
8 with the License. You may obtain a copy of the License at
9
10 http://www.apache.org/licenses/LICENSE-2.0
11
12 Unless required by applicable law or agreed to in writing,
13 software distributed under the License is distributed on an
14 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 KIND, either express or implied. See the License for the
16 specific language governing permissions and limitations
17 under the License.
18 */
19 package org.apache.cordova.api;
20
21 import org.json.JSONArray;
22 import org.json.JSONObject;
23
24 import android.content.Intent;
25 import android.webkit.WebView;
26
27 /**
28 * Plugin interface must be implemented by any plugin classes.
29 *
30 * The execute method is called by the PluginManager.
31 */
32 public abstract class Plugin implements IPlugin {
33
34 public String id;
35 public WebView webView; // WebView object
36 public CordovaInterface ctx; // CordovaActivity object
37
38 /**
39 * Executes the request and returns PluginResult.
40 *
41 * @param action The action to execute.
42 * @param args JSONArry of arguments for the plugin.
43 * @param callbackId The callback id used when calling back into JavaScript.
44 * @return A PluginResult object with a status and message.
45 */
46 public abstract PluginResult execute(String action, JSONArray args, String callbackId);
47
48 /**
49 * Identifies if action to be executed returns a value and should be run synchronously.
50 *
51 * @param action The action to execute
52 * @return T=returns value
53 */
54 public boolean isSynch(String action) {
55 return false;
56 }
57
58 /**
59 * Sets the context of the Plugin. This can then be used to do things like
60 * get file paths associated with the Activity.
61 *
62 * @param ctx The context of the main Activity.
63 */
64 public void setContext(CordovaInterface ctx) {
65 this.ctx = ctx;
66 }
67
68 /**
69 * Sets the main View of the application, this is the WebView within which
70 * a Cordova app runs.
71 *
72 * @param webView The Cordova WebView
73 */
74 public void setView(WebView webView) {
75 this.webView = webView;
76 }
77
78 /**
79 * Called when the system is about to start resuming a previous activity.
80 *
81 * @param multitasking Flag indicating if multitasking is turned on for app
82 */
83 public void onPause(boolean multitasking) {
84 }
85
86 /**
87 * Called when the activity will start interacting with the user.
88 *
89 * @param multitasking Flag indicating if multitasking is turned on for app
90 */
91 public void onResume(boolean multitasking) {
92 }
93
94 /**
95 * Called when the activity receives a new intent.
96 */
97 public void onNewIntent(Intent intent) {
98 }
99
100 /**
101 * The final call you receive before your activity is destroyed.
102 */
103 public void onDestroy() {
104 }
105
106 /**
107 * Called when a message is sent to plugin.
108 *
109 * @param id The message id
110 * @param data The message data
111 */
112 public void onMessage(String id, Object data) {
113 }
114
115 /**
116 * Called when an activity you launched exits, giving you the requestCode you started it with,
117 * the resultCode it returned, and any additional data from it.
118 *
119 * @param requestCode The request code originally supplied to startActivityForResult(),
120 * allowing you to identify who this result came from.
121 * @param resultCode The integer result code returned by the child activity through its setResult().
122 * @param data An Intent, which can return result data to the caller (various data can be attached to Intent "extras").
123 */
124 public void onActivityResult(int requestCode, int resultCode, Intent intent) {
125 }
126
127 /**
128 * By specifying a <url-filter> in plugins.xml you can map a URL (using startsWith atm) to this method.
129 *
130 * @param url The URL that is trying to be loaded in the Cordova webview.
131 * @return Return true to prevent the URL from loading. Default is false.
132 */
133 public boolean onOverrideUrlLoading(String url) {
134 return false;
135 }
136
137 /**
138 * Send generic JavaScript statement back to JavaScript.
139 * success(...) and error(...) should be used instead where possible.
140 *
141 * @param statement
142 */
143 public void sendJavascript(String statement) {
144 this.ctx.sendJavascript(statement);
145 }
146
147 /**
148 * Call the JavaScript success callback for this plugin.
149 *
150 * This can be used if the execute code for the plugin is asynchronous meaning
151 * that execute should return null and the callback from the async operation can
152 * call success(...) or error(...)
153 *
154 * @param pluginResult The result to return.
155 * @param callbackId The callback id used when calling back into JavaScript.
156 */
157 public void success(PluginResult pluginResult, String callbackId) {
158 this.ctx.sendJavascript(pluginResult.toSuccessCallbackString(callbackId));
159 }
160
161 /**
162 * Helper for success callbacks that just returns the Status.OK by default
163 *
164 * @param message The message to add to the success result.
165 * @param callbackId The callback id used when calling back into JavaScript.
166 */
167 public void success(JSONObject message, String callbackId) {
168 this.ctx.sendJavascript(new PluginResult(PluginResult.Status.OK, message).toSuccessCallbackString(callbackId));
169 }
170
171 /**
172 * Helper for success callbacks that just returns the Status.OK by default
173 *
174 * @param message The message to add to the success result.
175 * @param callbackId The callback id used when calling back into JavaScript.
176 */
177 public void success(String message, String callbackId) {
178 this.ctx.sendJavascript(new PluginResult(PluginResult.Status.OK, message).toSuccessCallbackString(callbackId));
179 }
180
181 /**
182 * Call the JavaScript error callback for this plugin.
183 *
184 * @param pluginResult The result to return.
185 * @param callbackId The callback id used when calling back into JavaScript.
186 */
187 public void error(PluginResult pluginResult, String callbackId) {
188 this.ctx.sendJavascript(pluginResult.toErrorCallbackString(callbackId));
189 }
190
191 /**
192 * Helper for error callbacks that just returns the Status.ERROR by default
193 *
194 * @param message The message to add to the error result.
195 * @param callbackId The callback id used when calling back into JavaScript.
196 */
197 public void error(JSONObject message, String callbackId) {
198 this.ctx.sendJavascript(new PluginResult(PluginResult.Status.ERROR, message).toErrorCallbackString(callbackId));
199 }
200
201 /**
202 * Helper for error callbacks that just returns the Status.ERROR by default
203 *
204 * @param message The message to add to the error result.
205 * @param callbackId The callback id used when calling back into JavaScript.
206 */
207 public void error(String message, String callbackId) {
208 this.ctx.sendJavascript(new PluginResult(PluginResult.Status.ERROR, message).toErrorCallbackString(callbackId));
209 }
210 }

Copyright 2016, The Apache Software Foundation.