Merge branch 'master' of git://github.com/phonegap/phonegap-android into contactSpec

framework/src/com/phonegap/DirectoryManager.java

@@ -6,26 +6,47 @@ import android.os.Environment;
 import android.os.StatFs;
 import android.util.Log;
 
+/**
+ * This class provides file directory utilities.  
+ * All file operations are performed on the SD card.
+ *   
+ * It is used by the FileUtils class.
+ */
 public class DirectoryManager {
 	
-	protected static boolean testFileExists (String name){
+	/**
+	 * Determine if a file or directory exists.
+	 * 
+	 * @param name				The name of the file to check.
+	 * @return					T=exists, F=not found
+	 */
+	protected static boolean testFileExists(String name) {
 		boolean status;
-		if ((testSaveLocationExists())&&(!name.equals(""))){
+		
+		// If SD card exists
+		if ((testSaveLocationExists()) && (!name.equals(""))) {
     		File path = Environment.getExternalStorageDirectory();
             File newPath = constructFilePaths(path.toString(), name);
             status = newPath.exists();
-    	}else{
+    	}
+		
+		// If no SD card
+		else{
     		status = false;
     	}
 		return status;
 	}
 	
-	protected static long getFreeDiskSpace(){
-		/*
-		 * gets the available SD card free space or returns -1 if the SD card is not mounted.
-		 */
+	/**
+	 * Get the free disk space on the SD card
+	 * 
+	 * @return 		Size in KB or -1 if not available
+	 */
+	protected static long getFreeDiskSpace() {
 		String status = Environment.getExternalStorageState();
 		long freeSpace = 0;
+		
+		// If SD card exists
 		if (status.equals(Environment.MEDIA_MOUNTED)) {
 			try {
 				File path = Environment.getExternalStorageDirectory();
@@ -34,44 +55,82 @@ public class DirectoryManager {
 				long availableBlocks = stat.getAvailableBlocks();
 				freeSpace = availableBlocks*blockSize/1024;
 			} catch (Exception e) {e.printStackTrace(); }
-		} else { return -1; }
+		} 
+		
+		// If no SD card, then return -1
+		else { 
+			return -1; 
+		}
+		
 		return (freeSpace);
 	}	
 	
-	protected static boolean createDirectory(String directoryName){
+	/**
+	 * Create directory on SD card.
+	 * 
+	 * @param directoryName		The name of the directory to create.
+	 * @return 					T=successful, F=failed
+	 */
+	protected static boolean createDirectory(String directoryName) {
 		boolean status;
-		if ((testSaveLocationExists())&&(!directoryName.equals(""))){
+		
+		// Make sure SD card exists
+		if ((testSaveLocationExists()) && (!directoryName.equals(""))) {
 			File path = Environment.getExternalStorageDirectory();
             File newPath = constructFilePaths(path.toString(), directoryName);
 			status = newPath.mkdir();
 			status = true;
-		}else
+		}
+		
+		// If no SD card or invalid dir name
+		else {
 			status = false;
+		}
 		return status;
 	}
 	
-	protected static boolean testSaveLocationExists(){
+	/**
+	 * Determine if SD card exists.
+	 * 
+	 * @return				T=exists, F=not found
+	 */
+	protected static boolean testSaveLocationExists() {
 		String sDCardStatus = Environment.getExternalStorageState();
 		boolean status;
-		if (sDCardStatus.equals(Environment.MEDIA_MOUNTED)){
+		
+		// If SD card is mounted
+		if (sDCardStatus.equals(Environment.MEDIA_MOUNTED)) {
 			status = true;
-		}else
+		}
+		
+		// If no SD card
+		else {
 			status = false;
+		}
 		return status;
 	}
 	
-	protected static boolean deleteDirectory(String fileName){
+	/**
+	 * Delete directory.
+	 * 
+	 * @param fileName		The name of the directory to delete
+	 * @return				T=deleted, F=could not delete
+	 */
+	protected static boolean deleteDirectory(String fileName) {
 		boolean status;
 		SecurityManager checker = new SecurityManager();
 			
-		if ((testSaveLocationExists())&&(!fileName.equals(""))){
-		
+		// Make sure SD card exists
+		if ((testSaveLocationExists()) && (!fileName.equals(""))) {	
 			File path = Environment.getExternalStorageDirectory();
             File newPath = constructFilePaths(path.toString(), fileName);
 			checker.checkDelete(newPath.toString());
-			if(newPath.isDirectory()){
+			
+			// If dir to delete is really a directory
+			if (newPath.isDirectory()) {
 				String[] listfile = newPath.list();
-				// delete all files within the specified directory and then delete the directory
+				
+				// Delete all files within the specified directory and then delete the directory
 				try{
 					for (int i=0; i < listfile.length; i++){
 						File deletedFile = new File (newPath.toString()+"/"+listfile[i].toString());
@@ -80,27 +139,43 @@ public class DirectoryManager {
 					newPath.delete();
 					Log.i("DirectoryManager deleteDirectory", fileName);
 					status = true;
-				}catch (Exception e){
+				}
+				catch (Exception e){
 					e.printStackTrace();
 					status = false;
 				}
-				
-			}else
+			}
+			
+			// If dir not a directory, then error
+			else {
 				status = false;
-		}else
+			}
+		}
+		
+		// If no SD card 
+		else {
 			status = false;
+		}
 		return status;
 	}
 	
-	protected static boolean deleteFile(String fileName){
+	/**
+	 * Delete file.
+	 * 
+	 * @param fileName				The name of the file to delete
+	 * @return						T=deleted, F=not deleted
+	 */
+	protected static boolean deleteFile(String fileName) {
 		boolean status;
 		SecurityManager checker = new SecurityManager();
 			
-		if ((testSaveLocationExists())&&(!fileName.equals(""))){
-		
+		// Make sure SD card exists
+		if ((testSaveLocationExists()) && (!fileName.equals(""))) {
 			File path = Environment.getExternalStorageDirectory();
             File newPath = constructFilePaths(path.toString(), fileName);
 			checker.checkDelete(newPath.toString());
+			
+			// If file to delete is really a file
 			if (newPath.isFile()){
 				try {
 					Log.i("DirectoryManager deleteFile", fileName);
@@ -110,14 +185,28 @@ public class DirectoryManager {
 					se.printStackTrace();
 					status = false;
 				}
-			}else
+			}
+			// If not a file, then error
+			else {
 				status = false;
-		}else
+			}
+		}
+		
+		// If no SD card
+		else {
 			status = false;
+		}
 		return status;
 	}
 	
-	private static File constructFilePaths (String file1, String file2){
+	/**
+	 * Create a new file object from two file paths.
+	 * 
+	 * @param file1			Base file path
+	 * @param file2			Remaining file path
+	 * @return				File object
+	 */
+	private static File constructFilePaths (String file1, String file2) {
 		File newPath;
 		newPath = new File(file1+"/"+file2);
 		return newPath;

framework/src/com/phonegap/DroidGap.java

@@ -82,7 +82,6 @@ public class DroidGap extends Activity {
 	protected Boolean loadInWebView = false;
     private LinearLayout root;
 
-    private FileUtils fs;
     private BrowserKey mKey;
     public CallbackServer callbackServer;
 	private PluginManager pluginManager;
@@ -266,13 +265,11 @@ public class DroidGap extends Activity {
     private void bindBrowser(WebView appView) {
         this.callbackServer = new CallbackServer();
     	this.pluginManager = new PluginManager(appView, this);
-        this.fs = new FileUtils(appView, this);
         this.mKey = new BrowserKey(appView, this);
     	
     	// This creates the new javascript interfaces for PhoneGap
     	appView.addJavascriptInterface(this.pluginManager, "PluginManager");
         
-        appView.addJavascriptInterface(this.fs, "FileUtil");
         appView.addJavascriptInterface(this.mKey, "BackButton");
         
         appView.addJavascriptInterface(this.callbackServer, "CallbackServer");
@@ -285,10 +282,10 @@ public class DroidGap extends Activity {
             Storage cupcakeStorage = (Storage)this.pluginManager.addPlugin("com.phonegap.Storage");
         	cupcakeStorage.setStorage(appPackage);
 
-            this.pluginManager.addPlugin("com.phonegap.GeoBroker");
 
         }
         
+        this.addService("Geolocation", "com.phonegap.GeoBroker");
         this.addService("Device", "com.phonegap.Device");
         this.addService("Accelerometer", "com.phonegap.AccelListener");
         this.addService("Compass", "com.phonegap.CompassListener");
@@ -296,6 +293,7 @@ public class DroidGap extends Activity {
         this.addService("Camera", "com.phonegap.CameraLauncher");
         this.addService("Contacts", "com.phonegap.ContactManager");
         this.addService("Crypto", "com.phonegap.CryptoHandler");
+        this.addService("File", "com.phonegap.FileUtils");
         this.addService("Location", "com.phonegap.GeoBroker");
         this.addService("Network Status", "com.phonegap.NetworkManager");
         this.addService("Storage", "com.phonegap.Storage");

framework/src/com/phonegap/FileUtils.java

@@ -2,123 +2,264 @@ package com.phonegap;
 
 import java.io.*;
 
+import org.apache.commons.codec.binary.Base64;
+import org.json.JSONArray;
+import org.json.JSONException;
+
+import com.phonegap.api.Plugin;
+import com.phonegap.api.PluginResult;
+
+import android.content.Intent;
 import android.webkit.WebView;
 
-public class FileUtils {
+/**
+ * This class provides SD card file and directory services to JavaScript.
+ * Only files on the SD card can be accessed.
+ */
+public class FileUtils implements Plugin {
+
+	public static int NOT_FOUND_ERR = 8;
+	public static int SECURITY_ERR = 18;
+	public static int ABORT_ERR = 20;
+
+	public static int NOT_READABLE_ERR = 24;
+	public static int ENCODING_ERR = 26;
 
 
-	WebView mView;
+    WebView webView;						// WebView object
+    DroidGap ctx;							// DroidGap object
+	
 	FileReader f_in;
 	FileWriter f_out;
 	
-	public FileUtils(WebView view, DroidGap gap)
-	{
-		mView = view;
+	/**
+	 * Constructor.
+	 */
+	public FileUtils() {
+		System.out.println("FileUtils()");
 	}
-	
-    public int testSaveLocationExists(){
-        if (DirectoryManager.testSaveLocationExists())
-            return 0;
-        else
-            return 1;
-    }
-    
-    public long getFreeDiskSpace(){
-        long freeDiskSpace=DirectoryManager.getFreeDiskSpace();
-        return freeDiskSpace;
-    }
 
-    public int testFileExists(String file){
-        if (DirectoryManager.testFileExists(file))
-            return 0;
-        else
-            return 1;
-    }
-    
-    public int testDirectoryExists(String file){
-        if (DirectoryManager.testFileExists(file))
-            return 0;
-        else
-            return 1;
-    } 
-
-    /**
-	 * Delete a specific directory. 
-	 * Everyting in side the directory would be gone.
-	 * TODO: JavaScript Call backs for success and error handling 
+	/**
+	 * Sets the context of the Command. This can then be used to do things like
+	 * get file paths associated with the Activity.
+	 * 
+	 * @param ctx The context of the main Activity.
 	 */
-    public int deleteDirectory (String dir){
-        if (DirectoryManager.deleteDirectory(dir))
-            return 0;
-        else
-            return 1;
-    }
-    
+	public void setContext(DroidGap ctx) {
+		this.ctx = ctx;
+	}
 
-    /**
-	 * Delete a specific file. 
-	 * TODO: JavaScript Call backs for success and error handling 
+	/**
+	 * Sets the main View of the application, this is the WebView within which 
+	 * a PhoneGap app runs.
+	 * 
+	 * @param webView The PhoneGap WebView
 	 */
-    public int deleteFile (String file){
-        if (DirectoryManager.deleteFile(file))
-            return 0;
-        else
-            return 1;
-    }
-    
+	public void setView(WebView webView) {
+		this.webView = webView;
+	}
 
-    /**
-	 * Create a new directory. 
-	 * TODO: JavaScript Call backs for success and error handling 
+	/**
+	 * Executes the request and returns CommandResult.
+	 * 
+	 * @param action The command to execute.
+	 * @param args JSONArry of arguments for the command.
+	 * @return A CommandResult object with a status and message.
 	 */
-    public int createDirectory(String dir){
-    	if (DirectoryManager.createDirectory(dir))
-            return 0;
-        else
-            return 1;
-    } 
-	
-    public String read(String filename)
-    {
-    	String data = "";
-    	String output = "";
-    	try {
-    		FileInputStream fstream = new FileInputStream(filename);
-			DataInputStream in = new DataInputStream(fstream);
-			  while (in.available() !=0)
-				{                 
-					data += in.readLine();
-				}
-			  
-		} catch (FileNotFoundException e) {
-			data = "FAIL: File not found";
-		} catch (IOException e) {
-			data = "FAIL: IO ERROR";		
-		}
+	public PluginResult execute(String action, JSONArray args) {
+		PluginResult.Status status = PluginResult.Status.OK;
+		String result = "";		
+		//System.out.println("FileUtils.execute("+action+")");
 		
-		//mView.loadUrl("javascript:navigator.FileReader.hasRead('" + data + "')");
+		try {
+			if (action.equals("testSaveLocationExists")) {
+		        boolean b = DirectoryManager.testSaveLocationExists();
+		        return new PluginResult(status, b);
+		    }  
+			else if (action.equals("getFreeDiskSpace")) {
+		        long l = DirectoryManager.getFreeDiskSpace();
+		        return new PluginResult(status, l);
+		    }
+			else if (action.equals("testFileExists")) {
+		        boolean b = DirectoryManager.testFileExists(args.getString(0));
+		        return new PluginResult(status, b);
+		    }
+			else if (action.equals("testDirectoryExists")) {
+		        boolean b = DirectoryManager.testFileExists(args.getString(0));
+		        return new PluginResult(status, b);
+		    }
+			else if (action.equals("deleteDirectory")) {
+		        boolean b = DirectoryManager.deleteDirectory(args.getString(0));
+		        return new PluginResult(status, b);
+		    }
+			else if (action.equals("deleteFile")) {
+		        boolean b = DirectoryManager.deleteFile(args.getString(0));
+		        return new PluginResult(status, b);
+		    }	
+			else if (action.equals("createDirectory")) {
+		        boolean b = DirectoryManager.createDirectory(args.getString(0));
+		        return new PluginResult(status, b);
+		    }
+			else if (action.equals("readAsText")) {
+				try {
+					String s = this.readAsText(args.getString(0), args.getString(1));
+			        return new PluginResult(status, s);
+				} catch (FileNotFoundException e) {
+					e.printStackTrace();
+					return new PluginResult(PluginResult.Status.ERROR, FileUtils.NOT_FOUND_ERR);
+				} catch (IOException e) {
+					e.printStackTrace();
+					return new PluginResult(PluginResult.Status.ERROR, FileUtils.NOT_READABLE_ERR);
+				}
+		    }
+			else if (action.equals("readAsDataURL")) {
+				try {
+					String s = this.readAsDataURL(args.getString(0));
+			        return new PluginResult(status, s);
+				} catch (FileNotFoundException e) {
+					e.printStackTrace();
+					return new PluginResult(PluginResult.Status.ERROR, FileUtils.NOT_FOUND_ERR);
+				} catch (IOException e) {
+					e.printStackTrace();
+					return new PluginResult(PluginResult.Status.ERROR, FileUtils.NOT_READABLE_ERR);
+				}
+		    }
+			else if (action.equals("writeAsText")) {
+				try {
+					this.writeAsText(args.getString(0), args.getString(1), args.getBoolean(2));
+				} catch (FileNotFoundException e) {
+					e.printStackTrace();
+					return new PluginResult(PluginResult.Status.ERROR, FileUtils.NOT_FOUND_ERR);
+				} catch (IOException e) {
+					e.printStackTrace();
+					return new PluginResult(PluginResult.Status.ERROR, FileUtils.NOT_READABLE_ERR);
+				}
+		    }
+			return new PluginResult(status, result);
+		} catch (JSONException e) {
+			e.printStackTrace();
+			return new PluginResult(PluginResult.Status.JSON_EXCEPTION);
+		}
+	}
+
+	/**
+	 * Identifies if action to be executed returns a value and should be run synchronously.
+	 * 
+	 * @param action	The action to execute
+	 * @return			T=returns value
+	 */
+	public boolean isSynch(String action) {
+		if (action.equals("readAsText")) {
+			return false;
+		}
+		else if (action.equals("readAsDataURL")) {
+			return false;
+		}
+		else if (action.equals("writeAsText")) {
+			return false;
+		}
+		return true;
+	}
+
+	/**
+     * Called when the system is about to start resuming a previous activity. 
+     */
+    public void onPause() {
+    }
+
+    /**
+     * Called when the activity will start interacting with the user. 
+     */
+    public void onResume() {
+    }
+    
+    /**
+     * Called by AccelBroker when listener is to be shut down.
+     * Stop listener.
+     */
+    public void onDestroy() {  	
+    }
+	
+    /**
+     * 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. 
+     * 
+     * @param requestCode		The request code originally supplied to startActivityForResult(), 
+     * 							allowing you to identify who this result came from.
+     * @param resultCode		The integer result code returned by the child activity through its setResult().
+     * @param data				An Intent, which can return result data to the caller (various data can be attached to Intent "extras").
+     */
+    public void onActivityResult(int requestCode, int resultCode, Intent intent) {
+    }
+
+    //--------------------------------------------------------------------------
+    // LOCAL METHODS
+    //--------------------------------------------------------------------------
+	
+    /**
+     * Read content of text file.
+     * 
+     * @param filename			The name of the file.
+     * @param encoding			The encoding to return contents as.  Typical value is UTF-8.
+     * 							(see http://www.iana.org/assignments/character-sets)
+     * @return					Contents of file.
+     * @throws FileNotFoundException, IOException
+     */
+    public String readAsText(String filename, String encoding) throws FileNotFoundException, IOException {
+    	System.out.println("FileUtils.readAsText("+filename+", "+encoding+")");
+    	StringBuilder data = new StringBuilder();
+   		FileInputStream fis = new FileInputStream(filename);
+   		BufferedReader reader = new BufferedReader(new InputStreamReader(fis, encoding), 1024);
+   		String line;
+   		while ((line = reader.readLine()) != null) {
+   			data.append(line);
+   		}
+    	return data.toString();
+    }
+    
+    /**
+     * Read content of text file and return as base64 encoded data url.
+     * 
+     * @param filename			The name of the file.
+     * @return					Contents of file = data:<media type>;base64,<data>
+     * @throws FileNotFoundException, IOException
+     */
+    public String readAsDataURL(String filename) throws FileNotFoundException, IOException {
+    	byte[] bytes = new byte[1000];
+   		BufferedInputStream bis = new BufferedInputStream(new FileInputStream(filename), 1024);
+   		ByteArrayOutputStream bos = new ByteArrayOutputStream();
+    	int numRead = 0;
+    	while ((numRead = bis.read(bytes, 0, 1000)) >= 0) {
+    	    bos.write(bytes, 0, numRead);
+    	}
+    	
+    	// Determine content type from file name
+    	// TODO
+    	String contentType = "";
+
+		byte[] base64 = Base64.encodeBase64(bos.toByteArray());
+		String data = "data:" + contentType + ";base64," + new String(base64);
     	return data;
     }
     
-    public int write(String filename, String data, boolean append)
-    {
-    		String FilePath= filename;
-    		try {
-				byte [] rawData = data.getBytes();
-    			ByteArrayInputStream in = new ByteArrayInputStream(rawData);    			    			
-    			FileOutputStream out= new FileOutputStream(FilePath, append);
-    			byte buff[] = new byte[rawData.length];
-    			in.read(buff, 0, buff.length);
-    			out.write(buff, 0, rawData.length);
-    			out.flush();
-    			out.close();    			
-    			//mView.loadUrl("javascript:navigator.FileReader.onsuccess('File written')");
-    		} catch (Exception e) { 
-    			//mView.loadUrl("javascript:navigator.FileReader.onerror('Fail')");
-    			// So, do we just return -1 at this point!
-    			return -1;
-    		}
-		return 0;
+    /**
+     * Write contents of file.
+     * 
+     * @param filename			The name of the file.
+     * @param data				The contents of the file.
+     * @param append			T=append, F=overwrite
+     * @throws FileNotFoundException, IOException
+     */
+    public void writeAsText(String filename, String data, boolean append) throws FileNotFoundException, IOException {
+    	String FilePath= filename;
+   		byte [] rawData = data.getBytes();
+   		ByteArrayInputStream in = new ByteArrayInputStream(rawData);    			    			
+   		FileOutputStream out= new FileOutputStream(FilePath, append);
+   		byte buff[] = new byte[rawData.length];
+   		in.read(buff, 0, buff.length);
+   		out.write(buff, 0, rawData.length);
+   		out.flush();
+   		out.close();    			
     }
     
 

framework/src/com/phonegap/GeoBroker.java

@@ -1,6 +1,7 @@
 package com.phonegap;
 
 import java.util.HashMap;
+import java.util.Map.Entry;
 
 import org.json.JSONArray;
 import org.json.JSONException;
@@ -22,6 +23,7 @@ public class GeoBroker implements Plugin {
 	WebView webView;					// WebView object
     DroidGap ctx;						// DroidGap object
 
+    // List of gGeolocation listeners
     private HashMap<String, GeoListener> geoListeners;
 	private GeoListener global;
 	
@@ -65,10 +67,10 @@ public class GeoBroker implements Plugin {
 		
 		try {
 			if (action.equals("getCurrentLocation")) {
-				this.getCurrentLocation();
+				this.getCurrentLocation(args.getBoolean(0), args.getInt(1), args.getInt(2));
 			}
 			else if (action.equals("start")) {
-				String s = this.start(args.getInt(0), args.getString(1));
+				String s = this.start(args.getString(0), args.getBoolean(1), args.getInt(2), args.getInt(3));
 				return new PluginResult(status, s);
 			}
 			else if (action.equals("stop")) {
@@ -87,7 +89,8 @@ public class GeoBroker implements Plugin {
 	 * @return			T=returns value
 	 */
 	public boolean isSynch(String action) {
-		return false;
+		// Starting listeners is easier to run on main thread, so don't run async.
+		return true;
 	}
 
 	/**
@@ -103,10 +106,22 @@ public class GeoBroker implements Plugin {
     }
     
     /**
-     * Called by AccelBroker when listener is to be shut down.
+     * Called when the activity is to be shut down.
      * Stop listener.
      */
-    public void onDestroy() {   	
+    public void onDestroy() {
+		java.util.Set<Entry<String,GeoListener>> s = this.geoListeners.entrySet();
+        java.util.Iterator<Entry<String,GeoListener>> it = s.iterator();
+        while (it.hasNext()) {
+            Entry<String,GeoListener> entry = it.next();
+            GeoListener listener = entry.getValue();
+            listener.destroy();
+		}
+        this.geoListeners.clear();
+        if (this.global != null) {
+        	this.global.destroy();
+        }
+        this.global = null;
     }
 
     /**
@@ -125,23 +140,57 @@ public class GeoBroker implements Plugin {
     // LOCAL METHODS
     //--------------------------------------------------------------------------
 
-	public void getCurrentLocation() {	
-		//It's supposed to run async!
-		if (global == null) {
-			global = new GeoListener("global", this.ctx, 10000, this.webView);
+    /**
+     * Get current location.
+     * The result is returned to JavaScript via a callback.
+     * 
+	 * @param enableHighAccuracy
+	 * @param timeout
+	 * @param maximumAge
+     */
+	public void getCurrentLocation(boolean enableHighAccuracy, int timeout, int maximumAge) {
+		
+		// Create a geolocation listener just for getCurrentLocation and call it "global"
+		if (this.global == null) {
+			this.global = new GeoListener("global", this.ctx, maximumAge, this.webView);
 		}
 		else {
-			global.start(10000);
+			this.global.start(maximumAge);
 		}
 	}
 	
-	public String start(int freq, String key) {
-		GeoListener listener = new GeoListener(key, this.ctx, freq, this.webView);
-		geoListeners.put(key, listener);
+	/**
+	 * Start geolocation listener and add to listener list.
+	 * 
+	 * @param key					The listener id
+	 * @param enableHighAccuracy
+	 * @param timeout
+	 * @param maximumAge
+	 * @return
+	 */
+	public String start(String key, boolean enableHighAccuracy, int timeout, int maximumAge) {
+		
+		// Make sure this listener doesn't already exist
+		GeoListener listener = geoListeners.get(key);
+		if (listener == null) {
+			listener = new GeoListener(key, this.ctx, maximumAge, this.webView);
+			geoListeners.put(key, listener);
+		}
+		
+		// Start it
+		listener.start(maximumAge);
 		return key;
 	}
 	
+	/**
+	 * Stop geolocation listener and remove from listener list.
+	 * 
+	 * @param key			The listener id
+	 */
 	public void stop(String key) {
-		GeoListener geo = geoListeners.get(key);
+		GeoListener listener = geoListeners.remove(key);
+		if (listener != null) {
+			listener.stop();
+		}
 	}
 }

framework/src/com/phonegap/GeoListener.java

@@ -6,83 +6,112 @@ import android.location.LocationManager;
 import android.webkit.WebView;
 
 public class GeoListener {
-	String id;
-	String successCallback;
+	public static int PERMISSION_DENIED = 1;
+	public static int POSITION_UNAVAILABLE = 2;
+	public static int TIMEOUT = 3;
+
+	String id;							// Listener ID
+	String successCallback;				// 
 	String failCallback;
-    GpsListener mGps; 
-    NetworkListener mNetwork;
-    LocationManager mLocMan;
-    private DroidGap mCtx;
-    private WebView mAppView;
+    GpsListener mGps;					// GPS listener
+    NetworkListener mNetwork;			// Network listener
+    LocationManager mLocMan;			// Location manager
+    
+    private DroidGap ctx;				// DroidGap object
+    @SuppressWarnings("unused")
+	private WebView mAppView;			// Webview object
 	
 	int interval;
 	
-	GeoListener(String i, DroidGap ctx, int time, WebView appView) {
-		id = i;
-		interval = time;
-		mCtx = ctx;
-		mGps = null;
-		mNetwork = null;
-		mLocMan = (LocationManager) mCtx.getSystemService(Context.LOCATION_SERVICE);
+	/**
+	 * Constructor.
+	 * 
+	 * @param id			Listener id
+	 * @param ctx
+	 * @param time			Sampling period in msec
+	 * @param appView
+	 */
+	GeoListener(String id, DroidGap ctx, int time, WebView appView) {
+		this.id = id;
+		this.interval = time;
+		this.ctx = ctx;
+		this.mGps = null;
+		this.mNetwork = null;
+		this.mLocMan = (LocationManager) ctx.getSystemService(Context.LOCATION_SERVICE);
 
-		if (mLocMan.getProvider(LocationManager.GPS_PROVIDER) != null) {
-			mGps = new GpsListener(mCtx, interval, this);
+		// If GPS provider, then create and start GPS listener
+		if (this.mLocMan.getProvider(LocationManager.GPS_PROVIDER) != null) {
+			this.mGps = new GpsListener(ctx, time, this);
 		}
-		if (mLocMan.getProvider(LocationManager.NETWORK_PROVIDER) != null) {
-			mNetwork = new NetworkListener(mCtx, interval, this);
+		
+		// If network provider, then create and start network listener
+		if (this.mLocMan.getProvider(LocationManager.NETWORK_PROVIDER) != null) {
+			this.mNetwork = new NetworkListener(ctx, time, this);
 		}
-		mAppView = appView;
+		this.mAppView = appView;
 	}
 	
+	/**
+	 * Destroy listener.
+	 */
+	public void destroy() {
+		this.stop();
+	}
+	
+	/**
+	 * Location found.  Send location back to JavaScript.
+	 * 
+	 * @param loc
+	 */
 	void success(Location loc) {
-		/*
-		 * We only need to figure out what we do when we succeed!
-		 */
 		
-		String params; 
-		/*
-		 * Build the giant string to send back to Javascript!
-		 */
-		params = loc.getLatitude() + "," + loc.getLongitude() + ", " + loc.getAltitude() + "," + loc.getAccuracy() + "," + loc.getBearing();
-		params += "," + loc.getSpeed() + "," + loc.getTime();
-		if (id != "global") {
-			mCtx.sendJavascript("navigator._geo.success(" + id + "," +  params + ");");
-		}
-		else {
-			mCtx.sendJavascript("navigator.geolocation.gotCurrentPosition(" + params + ");");
+		String params = loc.getLatitude() + "," + loc.getLongitude() + ", " + loc.getAltitude() + 
+				"," + loc.getAccuracy() + "," + loc.getBearing() +
+		 		"," + loc.getSpeed() + "," + loc.getTime();
+		
+		if (id == "global") {
 			this.stop();
 		}
+		this.ctx.sendJavascript("navigator._geo.success('" + id + "'," +  params + ");");
 	}
 	
-	void fail() {
-		// Do we need to know why? How would we handle this?
-		if (id != "global") {
-			mCtx.sendJavascript("navigator._geo.fail(" + id + ");");
-		} else {
-			mCtx.sendJavascript("navigator._geo.fail();");
-		}
+	/**
+	 * Location failed.  Send error back to JavaScript.
+	 * 
+	 * @param code			The error code
+	 * @param msg			The error message
+	 */
+	void fail(int code, String msg) {
+		this.ctx.sendJavascript("navigator._geo.fail('" + this.id + "', " + ", " + code + ", '" + msg + "');");
+		this.stop();
 	}
 	
+	/**
+	 * Start retrieving location.
+	 * 
+	 * @param interval
+	 */
 	void start(int interval) {
-		if (mGps != null) {
-			mGps.start(interval);
+		if (this.mGps != null) {
+			this.mGps.start(interval);
 		}
-		if (mNetwork != null) {
-			mNetwork.start(interval);
+		if (this.mNetwork != null) {
+			this.mNetwork.start(interval);
 		}
-		if (mNetwork == null && mGps == null) {
-			// Really, how were you going to get the location???
-			mCtx.sendJavascript("navigator._geo.fail();");
+		if (this.mNetwork == null && this.mGps == null) {
+			this.fail(POSITION_UNAVAILABLE, "No location providers available.");
 		}
 	}
 	
-	// This stops the listener
+	/**
+	 * Stop listening for location.
+	 */
 	void stop() {
-		if (mGps != null) {
-			mGps.stop();
+		if (this.mGps != null) {
+			this.mGps.stop();
 		}
-		if (mNetwork != null) {
-			mNetwork.stop();
+		if (this.mNetwork != null) {
+			this.mNetwork.stop();
 		}
 	}
 

framework/src/com/phonegap/GpsListener.java

@@ -26,81 +26,138 @@ import android.location.Location;
 import android.location.LocationManager;
 import android.location.LocationListener;
 import android.os.Bundle;
-import android.util.Log;
 
+/**
+ * This class handles requests for GPS location services.
+ *
+ */
 public class GpsListener implements LocationListener {
 	
-	private Context mCtx;
-	private Location cLoc;
-	private LocationManager mLocMan;
-	private static final String LOG_TAG = "PhoneGap";
-	private GeoListener owner;
-	private boolean hasData = false;
+	private DroidGap mCtx;						// DroidGap object
 	
-	public GpsListener(Context ctx, int interval, GeoListener m)
-	{
-		owner = m;
-		mCtx = ctx;
+	private LocationManager mLocMan;			// Location manager object
+	private GeoListener owner;					// Geolistener object (parent)
+	private boolean hasData = false;			// Flag indicates if location data is available in cLoc
+	private Location cLoc;						// Last recieved location
+	private boolean running = false;			// Flag indicates if listener is running
+	
+	/**
+	 * Constructor.  
+	 * Automatically starts listening.
+	 * 
+	 * @param ctx
+	 * @param interval
+	 * @param m
+	 */
+	public GpsListener(DroidGap ctx, int interval, GeoListener m) {
+		this.owner = m;
+		this.mCtx = ctx;
+		this.mLocMan = (LocationManager) this.mCtx.getSystemService(Context.LOCATION_SERVICE);
+		this.running = false;
 		this.start(interval);
 	}
 	
-	public Location getLocation()
-	{
-		cLoc = mLocMan.getLastKnownLocation(LocationManager.GPS_PROVIDER);
-		hasData = true;
-		return cLoc;
+	/**
+	 * Get last location.
+	 * 
+	 * @return 				Location object
+	 */
+	public Location getLocation() {
+		this.cLoc = this.mLocMan.getLastKnownLocation(LocationManager.GPS_PROVIDER);
+		if (this.cLoc != null) {
+			this.hasData = true;
+		}
+		return this.cLoc;
 	}
 	
+	/**
+	 * Called when the provider is disabled by the user.
+	 * 
+	 * @param provider
+	 */
 	public void onProviderDisabled(String provider) {
-		// TODO Auto-generated method stub
-		Log.d(LOG_TAG, "The provider " + provider + " is disabled");
-		owner.fail();
+		this.owner.fail(GeoListener.POSITION_UNAVAILABLE, "GPS provider disabled.");
 	}
 
+	/**
+	 * Called when the provider is enabled by the user.
+	 * 
+	 * @param provider
+	 */
 	public void onProviderEnabled(String provider) {
-		// TODO Auto-generated method stub
-		Log.d(LOG_TAG, "The provider "+ provider + " is enabled");
+		System.out.println("GpsListener: The provider "+ provider + " is enabled");
 	}
 
-
+	/**
+	 * Called when the provider status changes. This method is called when a 
+	 * provider is unable to fetch a location or if the provider has recently 
+	 * become available after a period of unavailability.
+	 * 
+	 * @param provider
+	 * @param status
+	 * @param extras
+	 */
 	public void onStatusChanged(String provider, int status, Bundle extras) {
-		// TODO Auto-generated method stub
-		Log.d(LOG_TAG, "The status of the provider " + provider + " has changed");
-		if(status == 0)
-		{
-			Log.d(LOG_TAG, provider + " is OUT OF SERVICE");
-			owner.fail();
+		System.out.println("GpsListener: The status of the provider " + provider + " has changed");
+		if (status == 0) {
+			System.out.println("GpsListener: " + provider + " is OUT OF SERVICE");
+			this.owner.fail(GeoListener.POSITION_UNAVAILABLE, "GPS out of service.");
 		}
-		else if(status == 1)
-		{
-			Log.d(LOG_TAG, provider + " is TEMPORARILY_UNAVAILABLE");
+		else if (status == 1) {
+			System.out.println("GpsListener: " + provider + " is TEMPORARILY_UNAVAILABLE");
 		}
-		else
-		{
-			Log.d(LOG_TAG, provider + " is Available");
+		else {
+			System.out.println("GpsListener: " + provider + " is Available");
 		}
 	}
 
-
+	/**
+	 * Called when the location has changed.
+	 * 
+	 * @param location
+	 */
 	public void onLocationChanged(Location location) {
-		Log.d(LOG_TAG, "The location has been updated!");
-		owner.success(location);
+		System.out.println("GpsListener: The location has been updated!");
+		this.hasData = true;
+		this.cLoc = location;
+		this.owner.success(location);
 	}
 
+	/**
+	 * Determine if location data is available.
+	 * 
+	 * @return
+	 */
 	public boolean hasLocation() {
-		return hasData;
+		return this.hasData;
 	}
 	
-	public void start(int interval)
-	{
-		mLocMan = (LocationManager) mCtx.getSystemService(Context.LOCATION_SERVICE);
-		mLocMan.requestLocationUpdates(LocationManager.GPS_PROVIDER, interval, 0, this);
-		cLoc = mLocMan.getLastKnownLocation(LocationManager.GPS_PROVIDER);
+	/**
+	 * Start requesting location updates.
+	 * 
+	 * @param interval
+	 */
+	public void start(int interval) {
+		if (!this.running) {
+			this.running = true;
+			this.mLocMan.requestLocationUpdates(LocationManager.GPS_PROVIDER, interval, 0, this);
+			this.getLocation();
+
+			// If GPS provider has data, then send now
+			if (this.hasData) {
+				this.owner.success(this.cLoc);
+			}
+		}
 	}
 
-	public void stop()
-	{
-		mLocMan.removeUpdates(this);
+	/**
+	 * Stop receiving location updates.
+	 */
+	public void stop() {
+		if (this.running) {
+			this.mLocMan.removeUpdates(this);
+		}
+		this.running = false;
 	}
 	
 }

framework/src/com/phonegap/NetworkListener.java

@@ -26,82 +26,129 @@ import android.location.Location;
 import android.location.LocationManager;
 import android.location.LocationListener;
 import android.os.Bundle;
-import android.util.Log;
 
 public class NetworkListener implements LocationListener {
-
-	private Context mCtx;
-	private Location cLoc;
-	private LocationManager mLocMan;
-	private static final String LOG_TAG = "PhoneGap";
-	GeoListener owner;
 	
-	public NetworkListener(Context ctx, int interval, GeoListener m)
-	{
-		owner = m;
-		mCtx = ctx;
+	private DroidGap mCtx;						// DroidGap object
+	
+	private LocationManager mLocMan;			// Location manager object
+	private GeoListener owner;					// Geolistener object (parent)
+	private boolean hasData = false;			// Flag indicates if location data is available in cLoc
+	private Location cLoc;						// Last recieved location
+	private boolean running = false;			// Flag indicates if listener is running
+
+	/**
+	 * Constructor.  
+	 * Automatically starts listening.
+	 * 
+	 * @param ctx
+	 * @param interval
+	 * @param m
+	 */
+	public NetworkListener(DroidGap ctx, int interval, GeoListener m) {
+		this.owner = m;
+		this.mCtx = ctx;
+		this.mLocMan = (LocationManager) this.mCtx.getSystemService(Context.LOCATION_SERVICE);
+		this.running = false;
 		this.start(interval);
 	}
 	
-	public Location getLocation()
-	{
-		cLoc = mLocMan.getLastKnownLocation(LocationManager.NETWORK_PROVIDER);		
-		return cLoc;
+	/**
+	 * Get last location.
+	 * 
+	 * @return 				Location object
+	 */
+	public Location getLocation() {
+		this.cLoc = this.mLocMan.getLastKnownLocation(LocationManager.NETWORK_PROVIDER);
+		if (this.cLoc != null) {
+			this.hasData = true;
+		}
+		return this.cLoc;
 	}
 
+	/**
+	 * Called when the provider is disabled by the user.
+	 * 
+	 * @param provider
+	 */
 	public void onProviderDisabled(String provider) {
-		// TODO Auto-generated method stub
-		Log.d(LOG_TAG, "The provider " + provider + " is disabled");
+		System.out.println("NetworkListener: The provider " + provider + " is disabled");
 	}
 
-
+	/**
+	 * Called when the provider is enabled by the user.
+	 * 
+	 * @param provider
+	 */
 	public void onProviderEnabled(String provider) {
-		// TODO Auto-generated method stub
-		Log.d(LOG_TAG, "The provider "+ provider + " is enabled");
+		System.out.println("NetworkListener: The provider "+ provider + " is enabled");
 	}
 
-
+	/**
+	 * Called when the provider status changes. This method is called when a 
+	 * provider is unable to fetch a location or if the provider has recently 
+	 * become available after a period of unavailability.
+	 * 
+	 * @param provider
+	 * @param status
+	 * @param extras
+	 */
 	public void onStatusChanged(String provider, int status, Bundle extras) {
-		// TODO Auto-generated method stub
-		Log.d(LOG_TAG, "The status of the provider " + provider + " has changed");
-		if(status == 0)
-		{
-			Log.d(LOG_TAG, provider + " is OUT OF SERVICE");
+		System.out.println("NetworkListener: The status of the provider " + provider + " has changed");
+		if (status == 0) {
+			System.out.println("NetworkListener: " + provider + " is OUT OF SERVICE");
 		}
-		else if(status == 1)
-		{
-			Log.d(LOG_TAG, provider + " is TEMPORARILY_UNAVAILABLE");
+		else if (status == 1) {
+			System.out.println("NetworkListener: " + provider + " is TEMPORARILY_UNAVAILABLE");
 		}
-		else
-		{
-			Log.d(LOG_TAG, provider + " is Available");
+		else {
+			System.out.println("NetworkListener: " + provider + " is Available");
 		}
 	}
 
-
-	/*
-	 * The GPS is the primary form of Geolocation in PhoneGap.  Only fire the success variables if the GPS is down
-	 * for some reason
+	/**
+	 * Called when the location has changed.
+	 * 
+	 * @param location
 	 */
 	public void onLocationChanged(Location location) {
-		Log.d(LOG_TAG, "The location has been updated!");
-		if (!owner.mGps.hasLocation())
-		{
-			owner.success(location);
+		System.out.println("NetworkListener: The location has been updated!");
+		this.hasData = true;
+		this.cLoc = location;
+		
+		// The GPS is the primary form of Geolocation in PhoneGap.  
+		// Only fire the success variables if the GPS is down for some reason.
+		if (!this.owner.mGps.hasLocation()) {
+			this.owner.success(location);
 		}
-		cLoc = location;
 	}
 	
-	public void start(int interval)
-	{
-		mLocMan = (LocationManager) mCtx.getSystemService(Context.LOCATION_SERVICE);
-		mLocMan.requestLocationUpdates(LocationManager.NETWORK_PROVIDER, interval, 0, this);
-		cLoc = mLocMan.getLastKnownLocation(LocationManager.NETWORK_PROVIDER);
+	/**
+	 * Start requesting location updates.
+	 * 
+	 * @param interval
+	 */
+	public void start(int interval)	{
+		if (!this.running) {
+			this.running = true;
+			this.mLocMan.requestLocationUpdates(LocationManager.NETWORK_PROVIDER, interval, 0, this);
+			this.getLocation();
+			
+			// If Network provider has data but GPS provider doesn't, then send ours
+			if (this.hasData && !this.owner.mGps.hasLocation()) {
+				this.owner.success(this.cLoc);
+			}
+		}
 	}
 	
-	public void stop()
-	{
-		mLocMan.removeUpdates(this);
+	/**
+	 * Stop receiving location updates.
+	 */
+	public void stop() {
+		if (this.running) {
+			this.mLocMan.removeUpdates(this);
+		}
+		this.running = false;
 	}
 	
 }

framework/src/com/phonegap/NetworkManager.java

@@ -14,6 +14,11 @@ import android.net.*;
 import android.webkit.WebView;
 
 public class NetworkManager implements Plugin {
+	
+	public static int NOT_REACHABLE = 0;
+	public static int REACHABLE_VIA_CARRIER_DATA_NETWORK = 1;
+	public static int REACHABLE_VIA_WIFI_NETWORK = 2;
+
 
     WebView webView;					// WebView object
     DroidGap ctx;						// DroidGap object
@@ -67,8 +72,8 @@ public class NetworkManager implements Plugin {
 				return new PluginResult(status, b);
 			}
 			else if (action.equals("isReachable")) {
-				boolean b = this.isReachable(args.getString(0));
-				return new PluginResult(status, b);
+				int i = this.isReachable(args.getString(0), args.getBoolean(1));
+				return new PluginResult(status, i);
 			}
 			return new PluginResult(status, result);
 		} catch (JSONException e) {
@@ -122,6 +127,11 @@ public class NetworkManager implements Plugin {
     // LOCAL METHODS
     //--------------------------------------------------------------------------
 
+    /**
+     * Determine if a network connection exists.
+     * 
+     * @return
+     */
 	public boolean isAvailable() {
 		NetworkInfo info = sockMan.getActiveNetworkInfo();
 		boolean conn = false;
@@ -131,6 +141,11 @@ public class NetworkManager implements Plugin {
 		return conn;
 	}
 	
+	/**
+	 * Determine if a WIFI connection exists.
+	 * 
+	 * @return
+	 */
 	public boolean isWifiActive() {
 		NetworkInfo info = sockMan.getActiveNetworkInfo();
 		if (info != null) {
@@ -140,18 +155,37 @@ public class NetworkManager implements Plugin {
 		return false;
 	}
 	
-	public boolean isReachable(String uri) {
+	/**
+	 * Determine if a URI is reachable over the network.
+	 * 
+	 * @param uri
+	 * @param isIpAddress
+	 * @return
+	 */
+	public int isReachable(String uri, boolean isIpAddress) {
+		int reachable = NOT_REACHABLE;
+		
 		if (uri.indexOf("http://") == -1) {
 			uri = "http://" + uri;
 		}
-		boolean reached = isAvailable();
-		try {
-			DefaultHttpClient httpclient = new DefaultHttpClient();
-			HttpGet httpget = new HttpGet(uri);
-			httpclient.execute(httpget);			
-		} catch (Exception e) { 
-			reached = false;
+
+		if (isAvailable()) {
+			try {
+				DefaultHttpClient httpclient = new DefaultHttpClient();
+				HttpGet httpget = new HttpGet(uri);
+				httpclient.execute(httpget);			
+
+				if (isWifiActive()) {
+					reachable = REACHABLE_VIA_WIFI_NETWORK;
+				}
+				else {
+					reachable = REACHABLE_VIA_CARRIER_DATA_NETWORK;
+				}
+			} catch (Exception e) { 
+				reachable = NOT_REACHABLE;
+			}
 		}
-		return reached;
+				
+		return reachable;
 	}
 }

framework/src/com/phonegap/api/PluginResult.java

@@ -63,7 +63,8 @@ public class PluginResult {
 		"Malformed url",
 		"IO error",
 		"Invalid action",
-		"JSON error"
+		"JSON error",
+		"Error"
 	};
 	
 	public enum Status {
@@ -74,6 +75,7 @@ public class PluginResult {
 		MALFORMED_URL_EXCEPTION,
 		IO_EXCEPTION,
 		INVALID_ACTION,
-		JSON_EXCEPTION
+		JSON_EXCEPTION,
+		ERROR
 	}
 }