Phonegap plugin for Android to enable Torch functionality

Initial commit of Phonegap plugin for Android to enable Torch
functionality

Android/Torch/README.md

@@ -0,0 +1,91 @@
+# Torch plugin for Phonegap (Android) #
+By Arne de Bree
+
+## Adding the Plugin to your project ##
+1. To install the plugin, move `Torch.js` to your project's www folder and include a reference to it 
+in your html files. 
+
+    <script src="Torch.js"></script>
+
+2. Create a folder called 'nl/debree/phonegap/plugin/torch' within your project's src folder.
+3. And copy the java file into that new folder.
+
+<pre>
+    mkdir -p <your_project>/src/nl/debree/phonegap/plugin/torch/
+    cp ./TorchPlugin.java <your_project>/src/nl/debree/phonegap/plugin/torch/
+</pre>
+
+4. Add a plugin line to `res/xml/plugins.xml`
+
+    &lt;plugin name="Torch" value="nl.debree.phonegap.plugin.torch.TorchPlugin" /&gt;
+
+## Using the plugin ##
+The plugin creates the object `window.plugins.Torch` within your DOM. This object
+exposes the following functions:
+
+- isOn
+- isCapable
+- toggle
+- turnOn
+- turnOff
+
+<pre>
+    window.plugins.Torch.isOn( 
+        function( result ) { console.log( "isOn: " + result.on ) }      // success
+    ,   function() { console.log( "error" ) }                           // error
+    );
+
+    window.plugins.Torch.isCapable( 
+        function( result ) { console.log( "isCapable: " + result.capable ) }      // success
+    ,   function() { console.log( "error" ) }                           // error
+    );
+
+    window.plugins.Torch.toggle( 
+        function() { console.log( "toggle" ) }                          // success
+    ,   function() { console.log( "error" ) }                           // error
+    );
+
+    window.plugins.Torch.turnOn( 
+        function() { console.log( "turnOn" ) }                          // success
+    ,   function() { console.log( "error" ) }                           // error
+    );
+
+    window.plugins.Torch.turnOff( 
+        function() { console.log( "turnOff" ) }                         // success
+    ,   function() { console.log( "error" ) }                           // error
+    );
+</pre>
+
+
+## BUGS AND CONTRIBUTIONS ##
+The latest bleeding-edge version is available [on GitHub](http://github.com/adebrees/phonegap-plugins/tree/master/Android/)
+If you have a patch, fork my repo baby and send me a pull request. Submit bug reports on GitHub, please.
+
+## Licence ##
+
+The MIT License
+
+Copyright (c) 2011 Arne de Bree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+
+
+

Android/Torch/Torch.js

@@ -0,0 +1,61 @@
+/**
+ * Phonegap Torch plugin 
+ * Copyright (c) Arne de Bree 2011
+ *
+ */
+
+/**
+ *  
+ * @return Object literal singleton instance of Torch
+ */
+var Torch = function() {};
+
+/**
+  * @param success The callback for success
+  * @param error The callback for error
+  */
+Torch.prototype.isCapable = function( success, error ) 
+{
+    return PhoneGap.exec( success, error, "Torch", "isCapable", [] );   
+};
+
+/**
+ * @param success The callback for success
+ * @param error The callback for error
+ */
+Torch.prototype.isOn = function( success, error ) 
+{
+   return PhoneGap.exec( success, error, "Torch", "isOn", [] );   
+};
+
+/**
+ * @param success The callback for success
+ * @param error The callback for error
+ */
+Torch.prototype.turnOn = function( success, error ) 
+{
+   return PhoneGap.exec( success, error, "Torch", "turnOn", [] );   
+};
+
+/**
+ * @param success The callback for success
+ * @param error The callback for error
+ */
+Torch.prototype.turnOff = function( success, error ) 
+{
+   return PhoneGap.exec( success, error, "Torch", "turnOff", [] );   
+};
+
+/**
+ * @param success The callback for success
+ * @param error The callback for error
+ */
+Torch.prototype.toggle = function( success, error ) 
+{
+   return PhoneGap.exec( success, error, "Torch", "toggle", [] );   
+};
+
+PhoneGap.addConstructor( function() 
+{
+	PhoneGap.addPlugin( "Torch", new Torch() );
+} );

Android/Torch/TorchPlugin.java

@@ -0,0 +1,154 @@
+/**
+ * Phonegap Torch Plugin
+ * Copyright (c) Arne de Bree 2011
+ *
+ */
+package nl.debree.phonegap.plugin.torch;
+
+import java.util.List;
+
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+import com.phonegap.api.Plugin;
+import com.phonegap.api.PluginResult;
+import com.phonegap.api.PluginResult.Status;
+
+import android.hardware.Camera;
+import android.util.Log;
+
+/**
+ * Plugin to turn on or off the Camera Flashlight of an Android device
+ * after the capability is tested  
+ */
+public class TorchPlugin extends Plugin {
+
+	public static final String CMD_ON = "turnOn";
+	public static final String CMD_OFF = "turnOff";
+	public static final String CMD_TOGGLE = "toggle";
+	public static final String CMD_IS_ON = "isOn";
+	public static final String CMD_HAS_TORCH = "isCapable";
+
+	// Create camera and parameter objects
+	private Camera mCamera;
+	private Camera.Parameters mParameters;
+	private boolean mbTorchEnabled = false;
+
+	/**
+	 * Constructor
+	 */
+	public TorchPlugin() {
+		Log.d( "TorchPlugin", "Plugin created" );
+
+		mCamera = Camera.open();		
+	}
+
+	/*
+	 * Executes the request and returns PluginResult.
+	 * 
+	 * @param action		action to perform. Allowed values: turnOn, turnOff, toggle, isOn, isCapable
+	 * @param data			input data, currently not in use
+	 * @param callbackId	The callback id used when calling back into JavaScript.
+	 * @return 				A PluginResult object with a status and message.
+	 * 
+	 * @see com.phonegap.api.Plugin#execute(java.lang.String,
+	 * org.json.JSONArray, java.lang.String)
+	 */
+	@Override
+	public PluginResult execute(String action, JSONArray data, String callbackId) {
+		Log.d( "TorchPlugin", "Plugin Called " + action );
+
+		PluginResult result = null;
+		JSONObject response = new JSONObject();
+
+		if (action.equals(CMD_ON)) {
+
+			this.toggleTorch( true );
+			result = new PluginResult( Status.OK );
+
+		} else if (action.equals(CMD_OFF)) {
+
+			this.toggleTorch( false );
+			result = new PluginResult( Status.OK );
+
+		} else if (action.equals(CMD_TOGGLE)) {
+
+			this.toggleTorch();
+			result = new PluginResult( Status.OK );
+
+		} else if (action.equals(CMD_IS_ON)) {
+			try {
+				response.put( "on", mbTorchEnabled );
+
+				result = new PluginResult( Status.OK, response );
+			} catch( JSONException jsonEx ) {
+				result = new PluginResult(Status.JSON_EXCEPTION);
+			}			
+		} else if (action.equals(CMD_HAS_TORCH)) {
+			try {
+				response.put( "capable", this.isCapable() );
+
+				result = new PluginResult( Status.OK, response );
+			} catch( JSONException jsonEx ) {
+				result = new PluginResult(Status.JSON_EXCEPTION);
+			}			
+
+		} else {
+			result = new PluginResult(Status.INVALID_ACTION);
+			Log.d( "TorchPlugin", "Invalid action : " + action + " passed");
+		}
+
+		return result;
+	}
+
+	/**
+	 * Test if this device has a Flashlight we can use and put in Torch mode
+	 * 
+	 * @return boolean
+	 */
+	protected boolean isCapable() {
+		boolean result = false;
+
+		List<String> flashModes = mParameters.getSupportedFlashModes();
+
+		if (flashModes != null	&& flashModes.contains(Camera.Parameters.FLASH_MODE_TORCH)) {
+			result = true;
+		}
+
+		return result;
+	}
+
+	/**
+	 * True toggle function, turns the torch on when off and vise versa
+	 * 
+	 */
+	protected void toggleTorch() {
+		toggleTorch( !mbTorchEnabled );
+	}
+
+	/**
+	 * Toggle the torch in the requested state
+	 * 
+	 * @param state			The requested state
+	 * 
+	 */
+	protected void toggleTorch(boolean state) {
+		mParameters = mCamera.getParameters();
+
+		// Make sure that torch mode is supported
+		//
+		if ( this.isCapable() ) {
+			if (state) {
+				mParameters.setFlashMode(Camera.Parameters.FLASH_MODE_TORCH);
+			} else {
+				mParameters.setFlashMode(Camera.Parameters.FLASH_MODE_ON);
+			}
+
+			// Commit the camera parameters
+			//
+			mCamera.setParameters(mParameters);
+
+			mbTorchEnabled = state;
+		}
+	}
+}