From e73794a5cc1f1c78485cce4282f5b2ecef549fe2 Mon Sep 17 00:00:00 2001 From: Markus Doits Date: Thu, 20 Jan 2011 11:55:36 +0000 Subject: [PATCH] Add javadoc on public things Small other changes, too. --- .../thialfihar/android/apg/utils/ApgCon.java | 334 +++++++++++++++++- 1 file changed, 320 insertions(+), 14 deletions(-) diff --git a/src/org/thialfihar/android/apg/utils/ApgCon.java b/src/org/thialfihar/android/apg/utils/ApgCon.java index ac94f27be..296c966a5 100644 --- a/src/org/thialfihar/android/apg/utils/ApgCon.java +++ b/src/org/thialfihar/android/apg/utils/ApgCon.java @@ -18,11 +18,12 @@ import org.thialfihar.android.apg.IApgService; /** * This class can be used by other projects to simplify connecting to the * APG-Service. Kind of wrapper of for AIDL. + * * It is not used in this project. */ public class ApgCon { - public class call_async extends AsyncTask { + private class call_async extends AsyncTask { @Override protected Void doInBackground(String... arg) { @@ -86,6 +87,17 @@ public class ApgCon { CALL_NOT_KNOWN, // apg service does not know what to do } + /** + * Constructor + * + *

+ * Creates a new ApgCon object and searches for the right APG version on + * initialization. If not found, errors are printed to the error log. + *

+ * + * @param ctx + * the running context + */ public ApgCon(Context ctx) { Log.v(TAG, "EncryptionService created"); mContext = ctx; @@ -153,6 +165,20 @@ public class ApgCon { return true; } + /** + * Disconnects ApgCon from Apg + * + *

+ * This should be called whenever all work with APG is done (e.g. everything + * you wanted to encrypt is encrypted), since connections with AIDL should + * not be upheld indefinitely. + *

+ * + *

+ * Also, if you destroy you end using your ApgCon-instance, this must be + * called or else the connection to APG is leaked + *

+ */ public void disconnect() { Log.v(TAG, "disconnecting apgService"); if (apgService != null) { @@ -171,20 +197,66 @@ public class ApgCon { return true; } + /** + * Calls a function from APG's AIDL-interface + * + *

+ * After you have set up everything with {@link #set_arg(String, String)} + * (and variants), you can call a function from the AIDL-interface. This + * will + *

    + *
  • start connection to the remote interface (if not already connected)
    • + *
  • call the passed function with all set up parameters synchronously
    • + *
  • set up everything to retrieve the result and/or warnings/errors
    • + *
+ *

+ * + *

+ * Note your thread will be blocked during execution - if you want to call + * the function asynchronously, see {@link #call_async(String)}. + *

+ * + * @param function + * a remote function to call + * @return true, if call successful (= no errors), else false + * + * @see #call_async(String) + * @see #set_arg(String, String) + */ public boolean call(String function) { return this.call(function, args, result); } + /** + * Calls a function from remote interface asynchronously + * + *

+ * This does exactly the same as {@link #call(String)}, but asynchronously. + * While connection to APG and work are done in background, your thread can + * go on executing. + *

+ * + *

+ * To see whether the task is finished, you have to possibilities: + *

    + *
  • In your thread, poll {@link #is_running()}
    • + *
  • Supply a callback with {@link #set_callback(Object, String)}
    • + *
+ *

+ * + * @param function + * a remote function to call + * + * @see #call(String) + * @see #is_running() + * @see #set_callback(Object, String) + */ public void call_async(String function) { async_running = true; new call_async().execute(function); } - public boolean call(String function, Bundle pArgs) { - return this.call(function, pArgs, result); - } - - public boolean call(String function, Bundle pArgs, Bundle pReturn) { + private boolean call(String function, Bundle pArgs, Bundle pReturn) { error_list.clear(); warning_list.clear(); @@ -220,30 +292,106 @@ public class ApgCon { } + /** + * Set a string argument for APG + * + *

+ * This defines a string argument for APG's AIDL-interface. + *

+ * + *

+ * To know what key-value-pairs are possible (or required), take a look into + * the IApgService.aidl + *

+ * + *

+ * Note, that the parameters are not deleted after a call, so you have to + * reset ({@link #clear_args()}) them manually if you want to. + *

+ * + * + * @param key + * the key + * @param val + * the value + * + * @see #clear_args() + */ public void set_arg(String key, String val) { args.putString(key, val); } + /** + * Set a string-array argument for APG + * + *

+ * If the AIDL-parameter is an {@literal ArrayList}, you have to use + * this function. + *

+ * + * + * 
+     * set_arg("a key", new String[]{ "entry 1", "entry 2" });
+     *
+ * + * + * @param key + * the key + * @param vals + * the value + * + * @see #set_arg(String, String) + */ public void set_arg(String key, String vals[]) { ArrayList list = new ArrayList(); for (String val : vals) { list.add(val); } - set_arg(key, list); - } - - public void set_arg(String key, ArrayList vals) { - args.putStringArrayList(key, vals); + args.putStringArrayList(key, list); } + /** + * Set up a boolean argument for APG + * + * @param key + * the key + * @param vals + * the value + * + * @see #set_arg(String, String) + */ public void set_arg(String key, boolean val) { args.putBoolean(key, val); } + /** + * Set up a int argument for APG + * + * @param key + * the key + * @param vals + * the value + * + * @see #set_arg(String, String) + */ public void set_arg(String key, int val) { args.putInt(key, val); } + /** + * Set up a int-array argument for APG + *

+ * If the AIDL-parameter is an {@literal ArrayList}, you have to + * use this function. + *

+ * + * @param key + * the key + * @param vals + * the value + * + * @see #set_arg(String, String) + */ public void set_arg(String key, int vals[]) { ArrayList list = new ArrayList(); for (int val : vals) { @@ -252,14 +400,50 @@ public class ApgCon { args.putIntegerArrayList(key, list); } + /** + * Clears all arguments + * + *

+ * Anything the has been set up with the various + * {@link #set_arg(String, String)} functions, is cleared. + *

+ *

+ * Note, that any warning, error, callback, result etc. is not cleared with + * this. + *

+ * + * @see #reset() + */ public void clear_args() { args.clear(); } + /** + * Return the object associated with the key + * + * @param key + * the object's key you want to return + * @return an object at position key, or null if not set + */ public Object get_arg(String key) { return args.get(key); } + /** + * Iterates through the errors + * + *

+ * With this method, you can iterate through all errors. The errors are only + * returned once and deleted immediately afterwards, so you can only return + * each error once. + *

+ * + * @return a human readable description of a error that happened, or null if + * no more errors + * + * @see #has_next_error() + * @see #clear_errors() + */ public String get_next_error() { if (error_list.size() != 0) return error_list.remove(0); @@ -267,10 +451,32 @@ public class ApgCon { return null; } + /** + * Check, if there are any new errors + * + * @return true, if there are unreturned errors, false otherwise + * + * @see #get_next_error() + */ public boolean has_next_error() { return error_list.size() != 0; } + /** + * Iterates through the warnings + * + *

+ * With this method, you can iterate through all warnings. The warnings are + * only returned once and deleted immediately afterwards, so you can only + * return each warning once. + *

+ * + * @return a human readable description of a warning that happened, or null + * if no more warnings + * + * @see #has_next_warning() + * @see #clear_warnings() + */ public String get_next_warning() { if (warning_list.size() != 0) return warning_list.remove(0); @@ -278,22 +484,68 @@ public class ApgCon { return null; } + /** + * Check, if there are any new warnings + * + * @return true, if there are unreturned warnings, false otherwise + * + * @see #get_next_warning() + */ public boolean has_next_warning() { return warning_list.size() != 0; } + /** + * Get the result + * + *

+ * This gets your result. After doing anything with APG, you get the output + * with this function + *

+ *

+ * Note, that when your last remote call is unsuccessful, the result will + * still have the same value like the last successful call (or null, if no + * call was successful). To ensure you do not work with old call's results, + * either be sure to {@link #reset()} (or at least {@link #clear_result()}) + * your instance before each new call or always check that + * {@link #has_next_error()} is false. + *

+ * + * @return the result of the last {@link #call(String)} or + * {@link #call_asinc(String)}. + * + * @see #reset() + * @see #clear_result() + */ public String get_result() { return result.getString("RESULT"); } + /** + * Clears all unfetched errors + * + * @see #get_next_error() + * @see #has_next_error() + */ public void clear_errors() { error_list.clear(); } + /** + * Clears all unfetched warnings + * + * @see #get_next_warning() + * @see #has_next_warning() + */ public void clear_warnings() { warning_list.clear(); } + /** + * Clears the last result + * + * @see #get_result() + */ public void clear_result() { result.clear(); } @@ -301,14 +553,19 @@ public class ApgCon { /** * Set a callback object and method * - *

After an async execution is finished, obj.meth() will be called. You can + *

+ * After an async execution is finished, obj.meth() will be called. You can * use this in order to get notified, when encrypting/decrypting of long * data finishes and do not have to poll {@link #is_running()} in your * thread. Note, that if the call of the method fails for whatever reason, * you won't get notified in any way - so you still should check - * {@link #is_running()} from time to time.

+ * {@link #is_running()} from time to time. + *

* - *

It produces a warning fetchable with {@link #get_next_warning()} when the callback fails.

+ *

+ * It produces a warning fetchable with {@link #get_next_warning()} when the + * callback fails. + *

* * 
      * 
@@ -366,18 +623,67 @@ public class ApgCon {
         callback_method = meth;
     }
 
+    /**
+     * Clears any callback object
+     * 
+     * @see #set_callback(Object, String)
+     */
     public void clear_callback_object() {
         callback_object = null;
     }
 
+    /**
+     * Clears any callback method
+     * 
+     * @see #set_callback(Object, String)
+     */
     public void clear_callback_method() {
         callback_method = null;
     }
 
+    /**
+     * Clears any callback method and object
+     * 
+     * @see #set_callback(Object, String)
+     */
+    public void clear_callback() {
+        clear_callback_object();
+        clear_callback_method();
+    }
+
+    /**
+     * Checks, whether an async execution is running
+     * 
+     * 

+     * If you started something with {@link #call_async(String)}, this will
+     * return true if the task is still running
+     * 

+     * 
+     * @return true, if an async task is still running, false otherwise
+     * 
+     * @see #call_async(String)
+     */
     public boolean is_running() {
         return async_running;
     }
 
+    /**
+     * Completely resets your instance
+     * 
+     * 

+     * This currently resets everything in this instance. Errors, warnings,
+     * results, callbacks, ... are removed. Any connection to the remote
+     * interface is upheld, though.
+     * 

+     * 
+     * 

+     * Note, that when an async execution ({@link #call_async(String)}) is
+     * running, it's result, warnings etc. will still be evaluated (which might
+     * be not what you want). Also mind, that any callback you set is also
+     * reseted, so on finishing the async execution any defined callback will
+     * NOT BE TRIGGERED.
+     * 

+     */
     public void reset() {
         clear_errors();
         clear_warnings();