WiFi: Update comments for a functions

Doxygen comments are reworked to be more understandable, functions that
not API's marked as internal.

Change-Id: I649c930201147a1c13038e5c7289d02229807db7
Signed-off-by: Milan Srdinko <msrdinko@alps.cz>

1 files changed, 162 insertions, 54 deletions

diff --git a/binding-wifi/wifi-api.c b/binding-wifi/wifi-api.c
index 02ff106..1c0954e 100644
--- a/binding-wifi/wifi-api.c
+++ b/binding-wifi/wifi-api.c
@@ -14,7 +14,7 @@
 */
 
 /**
- * file
+ * \file
  *
  * \brief Implementation of WiFi Binder for AGL's App Framework
  *
@@ -34,8 +34,8 @@
 
 
 
-static int need_password_flag = 0;
-static int password_not_correct_flag = 0;
+static int need_passkey_flag = 0;
+static int passkey_not_correct_flag = 0;
 
 char *passkey;
 callback ptr_my_callback;
@@ -45,12 +45,12 @@ GSList *wifi_list = NULL;
 
 
 /**
- * \brief Read out the passkey from the use and pass it to Agent
+ * \brief Input the passkey for connection to AP.
  *
- * \todo Since I do not know how to subscribe for the events from framework,
- *  it is necessary first to register the password http://IP_ADDRESS:PORT/api/wifi-manager/security?passkey=mypassword.
- *  Then this function is called automatically.
+ * \param[in] passkey pasword for the network
  *
+ * The user should first subscribe for the event 'passkey' and then provide passkey
+ * when this event has been received.
  *
  * */
 void wifi_passkey(struct afb_req request) {
@@ -58,7 +58,7 @@ void wifi_passkey(struct afb_req request) {
 
     const char *passkey_from_user;
 
-    /* retrieves the argument, expects password string */
+    /* retrieves the argument, expects passkey string */
     passkey_from_user = afb_req_value(request, "passkey");
 
     NOTICE(afbitf, "Passkey inserted: %s\n", passkey_from_user);
@@ -70,7 +70,7 @@ void wifi_passkey(struct afb_req request) {
 
         registerPasskey(passkey);
     } else {
-        NOTICE(afbitf, "Please enter the password first\n");
+        NOTICE(afbitf, "Please enter the passkey first\n");
 
     }
 }
@@ -86,7 +86,12 @@ struct event
 
 static struct event *events = 0;
 
-/* searchs the event of tag */
+/**
+ * \internal
+ * \brief Helper function that searches for a specific event.
+ *
+ * \param[in] tag of the event
+ */
 static struct event *event_get(const char *tag)
 {
     struct event *e = events;
@@ -95,34 +100,53 @@ static struct event *event_get(const char *tag)
     return e;
 }
 
-static int event_push(struct json_object *args, const char *tag)
+/**
+ * \internal
+ * \brief Helper function that actually pushes the event.
+ *
+ * \param[in] tag of the event
+ * \param[in] *args json object that contains data for the event
+ *
+ */
+static int do_event_push(struct json_object *args, const char *tag)
 {
     struct event *e;
     e = event_get(tag);
     return e ? afb_event_push(e->event, json_object_get(args)) : -1;
 }
 
+/**
+ * \internal
+ * \brief Pushes the event of 'tag' with the 'data
+ *
+ * \param[in] tag
+ * \param[in] data
+ *
+ */
 static void eventpush (struct afb_req request)
 {
     const char *tag = afb_req_value(request, "tag");
     const char *data = afb_req_value(request, "data");
-    ///data = "mojedata";
     json_object *object = data ? json_tokener_parse(data) : NULL;
 
     if (tag == NULL)
         afb_req_fail(request, "failed", "bad arguments");
-    else if (0 > event_push(object, tag))
+    else if (0 > do_event_push(object, tag))
         afb_req_fail(request, "failed", "push error");
     else
         afb_req_success(request, NULL, NULL);
 }
 
 /**
- * \brief Notify user that password is necessary
+ *
+ * \brief Notify user that passkey is necessary.
+ *
+ * \param[in] number additional integer data produced by Agent
+ * \param[in] asciidata additional ascii data produced by Agent
  *
  * This function is called from the registered agent on RequestInput() call.
  *
- * */
+ */
 void ask_for_passkey(int number, const char* asciidata) {
     NOTICE(afbitf, "Passkey for %s network needed.", asciidata);
     NOTICE(afbitf, "Sending event.");
@@ -136,16 +160,20 @@ void ask_for_passkey(int number, const char* asciidata) {
     json_object_object_add(jresp, "data2", string);
 
 
-    event_push(jresp, "password");
+    do_event_push(jresp, "passkey");
 }
 
 /**
- * \brief Notify GUI that wifi list has changed
+ * \internal
+ * \brief Notify GUI that wifi list has changed.
  *
- * This function is called from the registered agent on RequestInput() call.
- * \todo Subscribe for this event from GUI.
+ * \param[in] number number of event that caused the callback
+ * \param[in] asciidata additional data, e.g "BSSRemoved"
  *
- * */
+ * User should first subscribe for the event 'networkList' and then wait for this event.
+ * When notification comes, update the list if networks by scan_result call.
+ *
+ */
 void wifiListChanged(int number, const char* asciidata) {
 
     //WARNING(afbitf, "wifiListChanged, reason:%d, %s",number, asciidata );
@@ -159,7 +187,7 @@ void wifiListChanged(int number, const char* asciidata) {
     json_object_object_add(jresp, "data1", int1);
     json_object_object_add(jresp, "data2", string);
 
-    event_push(jresp, "networkList");
+    do_event_push(jresp, "networkList");
 
 
 
@@ -167,14 +195,15 @@ void wifiListChanged(int number, const char* asciidata) {
 
 
 /**
- * \brief initialize the binder and activates the WiFi HW, should be called first
+ * \brief Initializes the binder and activates the WiFi HW, should be called first.
  *
- * This will fail if
- * 	- agent for handling password requests cannot be registered
- * 	- some error is returned from connman
+ * \param[in] request no specific data needed
  *
+ * \return result of the request, either "success" or "failed" with description of error
  *
- * \return result of the request, either "success" or "failed" with description
+ * This will fail if
+ * 	- agent for handling passkey requests cannot be registered
+ * 	- some error is returned from connman
  */
 static void wifi_activate(struct afb_req request) /*AFB_SESSION_CHECK*/
 {
@@ -211,14 +240,16 @@ static void wifi_activate(struct afb_req request) /*AFB_SESSION_CHECK*/
 }
 
 /**
- * \brief deinitialize the binder and activates the WiFi HW
+ * \brief Deinitializes the binder and deactivates the WiFi HW.
+ *
+ * \param[in] request no specific data needed
+ *
+ * \return result of the request, either "success" or "failed" with description of error
  *
  * This will fail if
- * 	- agent for handling password requests cannot be unregistered
+ * 	- agent for handling passkey requests cannot be unregistered
  * 	- some error is returned from connman
  *
- *
- * \return result of the request, either "success" or "failed" with description
  */
 static void wifi_deactivate(struct afb_req request) /*AFB_SESSION_CHECK*/
 {
@@ -243,9 +274,14 @@ static void wifi_deactivate(struct afb_req request) /*AFB_SESSION_CHECK*/
 }
 
 /**
- * \brief starts scan
+ * \brief Starts scan for access points.
  *
- * \return result of the request, either "success" or "failed" with description
+ * \param[in] request no specific data needed
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ *
+ * User should first subscribe for the event 'networkList' and then wait for event to come.
+ * When notification comes, update the list of networks by scan_result call.
  */
 void wifi_scan(struct afb_req request) /*AFB_SESSION_NONE*/
 {
@@ -264,10 +300,14 @@ void wifi_scan(struct afb_req request) /*AFB_SESSION_NONE*/
 }
 
 /**
- * \brief return network list
+ * \brief Return network list.
  *
+ * \param[in] request no specific data needed
  *
- * \return result of the request, either "success" or "failed" with description
+ * \return result of the request, either "success" or "failed" with description of error \n
+ * 		   result is array of following json objects: Number, Strength, ESSID, Security, IPAddress, State.
+ * 		   E.g. {"Number":0,"Strength":82,"ESSID":"wifidata02","Security":"ieee8021x","IPAddress":"unsigned","State":"idle"}, or \n
+ * 		   {"Number":1,"Strength":51,"ESSID":"ALCZM","Security":"WPA-PSK","IPAddress":"192.168.1.124","State":"ready"}
  */
 void wifi_scanResult(struct afb_req request) /*AFB_SESSION_CHECK*/
 {
@@ -362,12 +402,16 @@ void wifi_scanResult(struct afb_req request) /*AFB_SESSION_CHECK*/
 }
 
 /**
- * \brief connects to network
+ * \brief Connects to a specific network.
+ *
+ * \param[in] request Number of network to connect to.
+ *
+ * \return result of the request, either "success" or "failed" with description of error
  *
- * \param[in] request number of network to connect to
+ * Specify number of network to connect to obtained by scan_result().
+ * User should first subscribe for the event 'passkey', if passkey
+ * is needed for connection this event is pushed.
  *
- *	 specify number of network to connect to obtained by scan_result() like this,
- *	 http://IP_ADDRESS:PORT/api/wifi-manager/connect?network=1
  */
 void wifi_connect(struct afb_req request) {
 
@@ -414,25 +458,26 @@ void wifi_connect(struct afb_req request) {
 	if (error == NULL)
 		afb_req_success(request, NULL, NULL);
 
-	else if (password_not_correct_flag) {
-		need_password_flag = 0;
-		password_not_correct_flag = 0;
-		afb_req_fail(request, "password-incorrect", NULL);
-	} else if (need_password_flag) {
-		need_password_flag = 0;
-		afb_req_fail(request, "need-password", NULL);
+	else if (passkey_not_correct_flag) {
+		need_passkey_flag = 0;
+		passkey_not_correct_flag = 0;
+		afb_req_fail(request, "passkey-incorrect", NULL);
+	} else if (need_passkey_flag) {
+		need_passkey_flag = 0;
+		afb_req_fail(request, "need-passkey", NULL);
 
 	} else
 		afb_req_fail(request, "failed", error->message);
 }
 
 /**
- * \brief disconnect from network
+ * \brief Disconnects from a network.
  *
  * \param[in] request number of network to disconnect from
  *
- *	 specify number of network to disconnect from obtained by scan_result() like this,
- *	 http://IP_ADDRESS:PORT/api/wifi-manager/discnnect?network=1
+ * \return result of the request, either "success" or "failed" with description of error
+ *
+ * Specify number of network to disconnect from obtained by scan_result().
  */
 void wifi_disconnect(struct afb_req request) {
 
@@ -482,9 +527,11 @@ void wifi_disconnect(struct afb_req request) {
 }
 
 /**
- * \brief return  current status of connection
+ * \brief Return current status of a connection.
+ *
+ * \param[in] request no specific data needed
  *
- * \return result of the request, either "success" or "failed" with description
+ * \return result of the request, either "success" with status or "failed" with description of error
  */
 void wifi_status(struct afb_req request) {
 	int error = 0;
@@ -525,8 +572,14 @@ void wifi_reconnect() {
 
 
 
-
-/* deletes the event of tag */
+/**
+ * \internal
+ * \brief Helper functions that actually delete the tag.
+ *
+ * \param[in] tag tag to delete
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ */
 static int event_del(const char *tag)
 {
     struct event *e, **p;
@@ -546,7 +599,15 @@ static int event_del(const char *tag)
     return 0;
 }
 
-/* creates the event of tag */
+/**
+ * \internal
+ * \brief Helper functions that actually creates event of the tag.
+ *
+ * \param[in] tag tag to add
+ * \param[in] name name to add
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ */
 static int event_add(const char *tag, const char *name)
 {
     struct event *e;
@@ -570,6 +631,13 @@ static int event_add(const char *tag, const char *name)
     return 0;
 }
 
+/**
+ * \brief Creates event of the tag.
+ *
+ * \param[in] request tag and name of the event
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ */
 static void eventadd (struct afb_req request)
 {
     const char *tag = afb_req_value(request, "tag");
@@ -585,6 +653,13 @@ static void eventadd (struct afb_req request)
         afb_req_success(request, NULL, NULL);
 }
 
+/**
+ * \brief Deletes the event of tag.
+ *
+ * \param[in] request tag to delete
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ */
 static void eventdel (struct afb_req request)
 {
     const char *tag = afb_req_value(request, "tag");
@@ -597,6 +672,15 @@ static void eventdel (struct afb_req request)
         afb_req_success(request, NULL, NULL);
 }
 
+
+/**
+ * \internal
+ * \brief Helper functions to subscribe for the event of tag.
+ *
+ * \param[in] request tag to subscribe for
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ */
 static int event_subscribe(struct afb_req request, const char *tag)
 {
     struct event *e;
@@ -604,6 +688,14 @@ static int event_subscribe(struct afb_req request, const char *tag)
     return e ? afb_req_subscribe(request, e->event) : -1;
 }
 
+/**
+ * \internal
+ * \brief Helper functions to unsubscribe for the event of tag.
+ *
+ * \param[in] request tag to unsubscribe for
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ */
 static int event_unsubscribe(struct afb_req request, const char *tag)
 {
     struct event *e;
@@ -611,6 +703,14 @@ static int event_unsubscribe(struct afb_req request, const char *tag)
     return e ? afb_req_unsubscribe(request, e->event) : -1;
 }
 
+
+/**
+ * \brief Subscribes for the event of tag.
+ *
+ * \param[in] request tag to subscribe for
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ */
 static void eventsub (struct afb_req request)
 {
     const char *tag = afb_req_value(request, "tag");
@@ -623,6 +723,14 @@ static void eventsub (struct afb_req request)
         afb_req_success(request, NULL, NULL);
 }
 
+
+/**
+ * \brief Unsubscribes for the event of tag.
+ *
+ * \param[in] request tag to unsubscribe for
+ *
+ * \return result of the request, either "success" or "failed" with description of error
+ */
 static void eventunsub (struct afb_req request)
 {
     const char *tag = afb_req_value(request, "tag");
@@ -643,7 +751,7 @@ static const struct afb_verb_desc_v1 binding_verbs[] = {
 /* VERB'S NAME     			SESSION MANAGEMENT          	FUNCTION TO CALL  					SHORT DESCRIPTION */
 { .name = "activate", 	  .session = AFB_SESSION_NONE, .callback = wifi_activate, 	.info = "Activate Wi-Fi" },
 { .name = "deactivate",   .session = AFB_SESSION_NONE, .callback = wifi_deactivate, .info ="Deactivate Wi-Fi" },
-{ .name = "scan", 		  .session = AFB_SESSION_NONE, .callback = wifi_scan, 		.info = "Scanning Wi-Fi" },
+{ .name = "scan", 		  .session = AFB_SESSION_NONE, .callback = wifi_scan, 		.info ="Scanning Wi-Fi" },
 { .name = "scan_result",  .session = AFB_SESSION_NONE, .callback = wifi_scanResult,	.info = "Get scan result Wi-Fi" },
 { .name = "connect", 	  .session = AFB_SESSION_NONE, .callback = wifi_connect, 	.info ="Connecting to Access Point" },
 { .name = "status", 	  .session = AFB_SESSION_NONE, .callback = wifi_status, 	.info ="Check connection status" },