extended documentation with introductionary section on how to use and how to extend library

libmobile.h

@@ -6,6 +6,41 @@
 #include <libubox/blobmsg.h>
 #include <libubus.h>
 
+/***************************************************
+ * Libmobile - A 4G Dongle library
+ *
+ * Libmobile provides a library to perform basic functionality for a 4G dongle through
+ * the use of HTTP GET/POST.
+ *
+ * All library calls will prepare the GET or POST query, and send the request to the dongle.
+ * The response from the server is parsed through a callback, <write_func>. The dongle's response
+ * is then returned. For POST requests the dongle responds with {"result": "success"} on a
+ * successful query execution, and with {"result": failure"} on an unsuccessful query execution,
+ * note that an unsuccessful query execution can mean a variety of things such as: incorrect pin,
+ * wrong input format, value already set, etc. For a GET request the variable's requested for with
+ * their corresponding values are returned, important to note that even variables that are not
+ * available within the system will be returned, but with no value set. The return string for all
+ * calls is the servers response pointed to by a char pointer.
+ *
+ *
+ * How to extend libmobile
+ *
+ * To extend this library add a new function with the corresponding documentation. The naming scheme
+ * should follow the format <mobile_get_{variables}> for GET requests and <mobile_{action_performed}>
+ * for POST requests. The structure of the calls are that the <mobile_...> functions prepare the query,
+ * for GET this means providing the variables to request from the dongle, provided as an input to
+ * <mobile_get_request>, for POST this means providing the POSTFIELDS argument query to the method
+ * <mobile_post_request>. The dongle's response is parsed through a callback, a pointer is then returned
+ * pointing to the response.
+ *
+ ***************************************************/
+
+/***************************************************
+ * IMPORTANT NOTE
+ *
+ * The library calls will allocate memory for the dongle's response and return the pointer to this memory,
+ * the caller is then responsible for freeing this memory by calling free(returned_pointer).
+ ***************************************************/
 
 /**
  * Function: write_to_ubus