Diff: cellular/Cellular.h

Revision:

56:e5e5351f14b3

Parent:

43:3cacf019ed7d

Child:

62:83ccef1e94db

--- a/cellular/Cellular.h	Thu Dec 19 22:11:16 2013 +0000
+++ b/cellular/Cellular.h	Fri Dec 20 20:26:46 2013 +0000
@@ -7,7 +7,8 @@
 #include <string>
 #include <vector>
 
-namespace mts {
+namespace mts
+{
 
 #define PINGDELAY 3 //Time to wait on each ping for a response before timimg out (seconds)
 #define PINGNUM 4 //Number of pings to try on ping command
@@ -34,7 +35,7 @@
 * providing a common set of commands for communication devices that have an onboard
 * IP Stack. It is also integrated with the standard Mbed Sockets package and can therefore
 * be used seamlessly with clients and services built on top of this interface already within
-* the Mbed library.
+* the mbed library.
 *
 * All of the following examples use the Pin Names for the Freedom KL46Z board coupled with
 * the SocketModem Shield Arduino compatible board. Please chage Pin Names accordingly to
@@ -52,22 +53,23 @@
 *
 * main() {
 *   //Wait for radio to boot up
-*   wait(15);
+*   wait(20);
 *
 *   //Setup serial interface to radio
 *   MTSSerialFlowControl* serial = new MTSSerialFlowControl(PTD3, PTD2, PTA12, PTC8);
 *   serial->baud(115200);
 *
 *   //Setup Cellular class
-*   Cellular* cellular = Cellular::getInstance(serial);
+*   Cellular* cellular = Cellular::getInstance();
+*   cellualr->init(serial);
 *
 *   //Run status and configuration commands
 *   printf("Start Status and Configuration Example\n\r");
-*   printf("test: %s\n\r", CodeNames[cellular->test()]);
+*   printf("test: %s\n\r", Cellular::getCodeNames(cellular->test()));
 *   printf("Phone Number: %s\n\r", cellular->getPhoneNumber());
 *   printf("Signal Strength: %d\n\r", cellular->getSignalStrength());
-*   printf("Registration State: %s\n\r", RegistrationNames[cellular->getRegistration()]);
-*   printf("Send Basic Command (AT): %s\n\r", CodeNames[cellular->sendBasicCommand("AT", 1000)]);
+*   printf("Registration State: %s\n\r", Cellular::getRegistrationNames(cellular->getRegistration()));
+*   printf("Send Basic Command (AT): %s\n\r", Cellular::getCodeNames(cellular->sendBasicCommand("AT", 1000)));
 *   printf("Send Command (AT+CSQ): %s\n\r", sendCommand("AT+CSQ", 1000));
 *
 *   printf("End Program\n\r");
@@ -95,7 +97,8 @@
 *   serial->baud(115200);
 *
 *   //Setup Cellular class
-*   Cellular* cellular = Cellular::getInstance(serial);
+*   Cellular* cellular = Cellular::getInstance();
+*   cellular->init(serial);
 *
 *   //Start Test
 *   printf("Start Network Connectivity Example\n\r");
@@ -147,9 +150,14 @@
         NOT_REGISTERED, REGISTERED, SEARCHING, DENIED, UNKNOWN, ROAMING
     };
 
+    /** This structure contains the data for an SMS message.
+    */
     struct Sms {
+        /// Message Phone Number
         std::string phoneNumber;
+        /// Message Body
         std::string message;
+        /// Message Timestamp
         std::string timestamp;
     };
 
@@ -157,8 +165,33 @@
     */
     ~Cellular();
 
+    /** This static function is used to create or get a reference to a
+    * Cellular object. Cellular 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 Cellular
+    * 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'e 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 Cellular obect that has been created.
+    */
     static Cellular* getInstance();
-    static Cellular* getInstance(MTSBufferedIO* io);
+    
+    /** This method initializes the object with the underlying radio
+    * interface to use. Note that this function MUST be called before
+    * any other calls will function correctly on an Cellular 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 cellular
+    * radio.
+    * @returns true if the init was successful, otherwise false.
+    */
+    bool init(MTSBufferedIO* io);
 
     // Radio link related commands
     /** This method establishes a data connection on the cellular radio.
@@ -181,7 +214,7 @@
     * @returns true if a data connection exists, otherwise false.
     */
     virtual bool isConnected();
-    
+
     // TCP and UDP Socket related commands
     // For behavior of the following methods refer to IPStack.h documentation
     virtual bool bind(unsigned int port);
@@ -290,6 +323,17 @@
     * @returns true if the ping was successful, otherwise false.
     */
     bool ping(const std::string& address = "8.8.8.8");
+
+    /** This method can be used to trade socket functionality for performance.
+    * In order to enable a socket connection to be closed by the client side programtically,
+    * this class must process all read and write data on the socket to guard the special
+    * escape character used to close an open socket connection. It is recommened that you
+    * use the default of true unless the overhead of these operations is too significant.
+    *
+    * @param enabled set to true if you want the socket closeable, otherwise false. The default
+    * is true.
+    * @returns the standard AT Code enumeration.
+    */
     Code setSocketCloseable(bool enabled = true);  //ETX closes socket (ETX and DLE in payload are escaped with DLE)
 
     /** This method is used to send an SMS message. Note that you cannot send an
@@ -309,13 +353,43 @@
     */
     Code sendSMS(const Sms& sms);
 
-    /**
+    /** This method retrieves all of the SMS messages currently available for
+    * this phone number.
     *
+    * @returns a vector of existing SMS messages each as an Sms struct.
     */
     std::vector<Cellular::Sms> getReceivedSms();
+
+    /** This method can be used to remove/delete all received SMS messages
+    * even if they have never been retrieved or read.
+    *
+    * @returns the standard AT Code enumeration.
+    */
     Code deleteAllReceivedSms();
+
+    /** This method can be used to remove/delete all received SMS messages
+    * that have been retrieved by the user through the getReceivedSms method.
+    * Messages that have not been retrieved yet will be unaffected.
+    *
+    * @returns the standard AT Code enumeration.
+    */
     Code deleteOnlyReceivedReadSms();
 
+    /** A static method for getting a string representation for the Code
+    * enumeration.
+    *
+    * @param code a Code enumeration.
+    * @returns the enumeration name as a string.
+    */
+    static std::string getCodeNames(Code code);
+
+    /** A static method for getting a string representation for the Registration
+    * enumeration.
+    *
+    * @param code a Registration enumeration.
+    * @returns the enumeration name as a string.
+    */
+    static std::string getRegistrationNames(Registration registration);
 
 private:
     static Cellular* instance; //Static pointer to the single Cellular object.
@@ -326,15 +400,15 @@
     bool pppConnected; //Specifies if a PPP session is currently connected.
     std::string apn; //A string that holds the APN for the radio.
 
-    Mode mode;
+    Mode mode; //The current socket Mode.
     bool socketOpened; //Specifies if a Socket is presently opened.
     bool socketCloseable; //Specifies is a Socket can be closed.
     unsigned int local_port; //Holds the local port for socket connections.
     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.
-    DigitalIn* dcd;
-    DigitalOut* dtr;
+    DigitalIn* dcd; //Maps to the radios dcd signal
+    DigitalOut* dtr; //Maps to the radios dtr signal
 
     Cellular(); //Private constructor, use the getInstance() method.
     Cellular(MTSBufferedIO* io); //Private constructor, use the getInstance() method.