Diff: wifi/Wifi.h

Revision:

103:da58d27c15d7

Parent:

95:4fdf968b5b37

Child:

106:358972176b89

diff -r 9d96b4391151 -r da58d27c15d7 wifi/Wifi.h
--- a/wifi/Wifi.h	Mon Dec 30 22:54:55 2013 +0000
+++ b/wifi/Wifi.h	Mon Dec 30 23:55:43 2013 +0000
@@ -4,26 +4,69 @@
 #include "IPStack.h"
 #include "MTSBufferedIO.h"
 #include "mbed.h"
-#include "Cellular.h"
 #include <string>
-#include <vector>
 
 using namespace mts;
 
 class Wifi : public IPStack
 {
 public:
+    ///An enumeration for all the supported WiFi security types.
     enum SecurityType {
         NONE, WEP64, WEP128, WPA, WPA2
     };
 
+    /** Destructs a Wifi object and frees all related resources.
+    */
     ~Wifi();
 
+    /** This static function is used to create or get a reference to a
+    * Wifi object. Wifi uses the singleton pattern, which means
+    * that you can only have one existing at a time. The first time you
+    * call getInstance this method creates a new uninitialized Wifi
+    * object and returns it. All future calls to this method will return
+    * a reference to the instance created during the first call. Note that
+    * you must call init on the returned instance before mnaking any other
+    * calls. If using this class's bindings to any of the Socket package
+    * classes like TCPSocketConnection, you must call this method and the
+    * init method on the returned object first, before even creating the
+    * other objects.
+    *
+    * @returns a reference to the single Wifi obect that has been created.
+    */
     static Wifi* getInstance();
+
+    /** This method initializes the object with the underlying Wifi module
+    * interface to use. Note that this function MUST be called before
+    * any other calls will function correctly on a Wifi object. Also
+    * note that MTSBufferedIO is abstract, so you must use one of
+    * its inherited classes like MTSSerial or MTSSerialFlowControl.
+    *
+    * @param io the buffered io interface that is attached to the wifi
+    * radio module.
+    * @returns true if the init was successful, otherwise false.
+    */
     bool init(MTSBufferedIO* io);
 
+    /** This method establishes a network connection on the Wif radio module.
+    * Note that before calling you NEED to first set the network information
+    * including WiFi SSID and optional security key using the setNetwork
+    * method.
+    *
+    * @returns true if the connection was successfully established, otherwise
+    * false on an error.
+    */
     virtual bool connect();
+
+    /** This method is used to stop a previously established Wifi network connection.
+    */
     virtual void disconnect();
+
+    /** This method is used to check if the radio currently has a Wifi network
+    * connection established.
+    *
+    * @returns true if a network connection exists, otherwise false.
+    */
     virtual bool isConnected();
 
     // TCP and UDP Socket related commands
@@ -42,11 +85,49 @@
     std::string sendCommand(std::string command, int timeoutMillis, std::string response = "", char esc = CR);
     Code sendBasicCommand(std::string command, int timeoutMillis, char esc = CR);
 
-    Code setNetwork(const std::string& ssid, const std::string& key, SecurityType type);
+    /** This method is used to set the network information details. This method must be
+    * called before connect, which establishes the WiFi network connection.
+    *
+    * @param ssid the SSID for the network you want to attached to.
+    * @param type the type of security used on the network. The default is NONE.
+    * @param key the security key for the network. The default is no key.
+    */
+    Code setNetwork(const std::string& ssid, SecurityType type = NONE, const std::string& key = "");
+
+    /** This method is used to set the DNS which enables the use of URLs instead
+    * of IP addresses when making a socket connection.
+    *
+    * @param the DNS server address as a string in form xxx.xxx.xxx.xxx.
+    * @returns the standard AT Code enumeration.
+    */
     Code setDNS(const std::string& dnsName);
+
+    /** A method for getting the signal strength of the Wifi module. This method allows
+    * you to get the signal strength in dBm. If you get a result of 99 the signal strength
+    * is not known or there was an error in reading it. Note that you cannot read the signal
+    * strength unless you are already attached to a Wifi network.
+    *
+    * @returns an integer representing the signal strength in dBm.
+    */
     int getSignalStrength();
-    
+
+    /** This method is used test network connectivity by pinging a server.
+    *
+    * @param address the address of the server in format xxx.xxx.xxx.xxx.
+    * @returns true if the ping was successful, otherwise false.
+    */
     bool ping(const std::string& address = "8.8.8.8");
+
+    /** This method is used to set whether the device is in command mode or data mode.
+    * In command mode you are able to send configuration and status commands while
+    * data mode is used for sending data when you have an open socket connection.
+    * Note that for all other methods in this class the change is handled automatically.
+    * Only use this methodif you want to send your own commands that are not already
+    * supported and need to make sure that you are in command mode.
+    *
+    * @param on if true sets to command mode, otherwise to data mode.
+    * @returns true if the change was successful, otherwise false.
+    */
     bool setCmdMode(bool on);
 
 private:
@@ -64,7 +145,7 @@
     std::string local_address; //Holds the local address for socket connections.
     unsigned int host_port; //Holds the remote port for socket connections.
     std::string host_address; //Holds the remote address for socket connections.
-    bool cmdOn;
+    bool cmdOn; //Determines whether the device is in command mode or not
 
     Wifi(); //Private constructor, use the getInstance() method.
     Wifi(MTSBufferedIO* io); //Private constructor, use the getInstance() method.