diff --git a/libmobile.h b/libmobile.h index 5947d4cbb53d249a7d327e49918203dace5d7b6b..7b3116f229cbdc9726db327fc49fb98b3fabd7e6 100644 --- a/libmobile.h +++ b/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