-
Jakob Olsson authoredJakob Olsson authored
libmobile.h 9.08 KiB
#ifndef LIBMOBILE_H
#define LIBMOBILE_H
#include <curl/curl.h>
#include <json-c/json.h>
#include <string.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).
*
***************************************************/
/**
* __TEMPORARILY PLACED IN THIS HEAD__
* Function: parse_apn_profiles
*
* Takes a string of APN profile configurations provided by zte-mf823 (which is in an awkward, difficult to read format)
* and transforms them into a more easily read and worked with JSON format.
*
* Parameters:
* apn_profiles - A character string containing the APN profiles.
*
* Returns:
* The newly generated JSON on success.
* NULL on failure.
*/
struct json_object *parse_apn_profiles(char *apn_profiles);
/**
* Function: mobile_connect_network
*
* Connects the dongle's network.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_connect_network(void);
/**
* Function: mobile_disconnect_network
*
* Disconnects the dongle's network.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_disconnect_network(void);
/**
* Function: mobile_delete_apn
*
* Deletes an existing APN profile from the APN list.
*
* Parameters:
* name - The name of the APN profile to be removed.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_delete_apn(char *name);
/**
* Function: mobile_enable_roaming
*
* Enables the roaming option on the dongle.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_enable_roaming(void);
/**
* Function: mobile_disable_roaming
*
* Disables the roaming option on the dongle.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_disable_roaming(void);
/**
* Function: mobile_disable_roaming
*
* Gets the current roam status of the dongle.
*
* Returns:
* A string containing the servers response in JSON format, {"roam_setting_option": "on"/"off" }
* NULL on failure.
*/
char *mobile_get_roam_status(void);
/**
* Function: mobile_get_wan_apn
*
* Gets the currently active APN profile's WAN name.
*
* Returns:
* A string containing the servers response in JSON format, {"wan_apn": "<name>" } on success.
* NULL on failure.
*/
char *mobile_get_wan_apn(void);
/**
* Function: mobile_get_pinnumber
*
* Gets the pinnumber, indicating how many tries are remaining before the SIM card is locked.
*
* Returns:
* A string containing the servers response in JSON format, {"pinnumber": {1..3} } on success.
* NULL on failure.
*/
char *mobile_get_pinnumber(void);
/**
* Function: mobile_get_pin_status
*
* Gets the pinnumber, indicating whether pin is enabled or not.
*
* Returns:
* A string containing the servers response in JSON format, {"pinnumber": {0..1} } on success.
* NULL on failure.
*/
char *mobile_get_pin_status(void);
/**
* Function: mobile_get_rssi
*
* Gets the rssi, indicating the signal strength.
*
* Returns:
* A string containing the servers response in JSON format, {"rssi": {} } on success.
* NULL on failure.
*/
char *mobile_get_rssi(void);
/**
* Function: mobile_get_modem_state
*
* Gets a variety of variables related to the modems state, i.e. network.
*
* Returns:
* A string containing the servers response in JSON format on success.
* NULL on failure.
*/
char *mobile_get_modem_state(void);
/**
* Function: mobile_get_apn_profiles
*
* Gets all available APN profile names.
*
* Returns:
* A string containing the servers response in JSON format on success.
* NULL on failure.
*/
char *mobile_get_apn_profiles(void);
/**
* Function: mobile_create_apn_profile
*
* Creates a new APN profile.
*
* Parameter:
* name - Name of the APN (and WAN) profile to create.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_create_apn_profile(char *name);
/**
* Function: mobile_set_apn_profile
*
* Sets a name APN profile to be activate.
*
* Parameter:
* name - Name of the APN profile to activate.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_set_apn_profile(char *name);
/**
* Function: mobile_enable_pin
*
* Enables pin on the SIM card.
*
* Parameter:
* pin - The current pin card of the SIM.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_enable_pin(char *pin);
/**
* Function: mobile_set_pin
*
* Sets a new pin for the SIM card.
*
* Parameter:
* current_pin - The currently active pin for the SIM card.
* new_pin - The pin code which to set as the active pin for the SIM card.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_set_pin(char *current_pin, char *new_pin);
/**
* Function: mobile_disable_pin
*
* Disables pin for the SIM card.
*
* Parameter:
* pin - Currently active pin.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_disable_pin(char *pin);
/**
* Function: mobile_post_request
*
* Function that prepares curl environment and final POST query, then executes said query.
*
* Parameter:
* query - The POST query content to execute.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_post_request(char *query);
/**
* Function: mobile_get_request
*
* Function that prepares curl environment and final GET query, then executes said query.
*
* Parameter:
* vars - A string of comma separated values which to get from the server.
*
* Returns:
* A string containing the servers response (a json string containing {"result": "success"/"failure" }),
indicating whether the server successfully executed the query.
* NULL on failure.
*/
char *mobile_get_request(char *vars);
#endif