IPStack.h

00001 #ifndef IPSTACK_H
00002 #define IPSTACK_H
00003 
00004 #include <string>
00005 #include "CommInterface.h"
00006 
00007 /** This class is a pure virtual class that should be inherited from when implementing
00008 * a communications device with an onboard IP stack.  Examples of this would be a Wi-Fi
00009 * or Cellular radio. The inheriting class should map the device commands and functionality
00010 * to the pure virtual methods provided here. There should also be at least one or more calls
00011 * to setup the communication link specific paramters as an init method for example. This
00012 * would do things like configure the APN in a cellular radio or set the ssid for a WiFi device,
00013 * which cannot be accounted for in an abstract class like this one. Note that to provide physical
00014 * connection management methods this class inherits from CommInterface.
00015 */
00016 class IPStack : public CommInterface
00017 {
00018 public:
00019     /// An enumeration for selecting the Socket Mode of TCP or UDP.
00020     enum Mode {
00021         TCP, UDP
00022     };
00023 
00024     /** This method is used to set the local port for the UDP or TCP socket connection.
00025     * The connection can be made using the open method.
00026     *
00027     * @param port the local port of the socket as an int.
00028     */
00029     virtual bool bind(unsigned int port) = 0;
00030 
00031     /** This method is used to open a socket connection with the given parameters.
00032     *
00033     * @param address is the address you want to connect to in the form of xxx.xxx.xxx.xxx
00034     * or a URL. If using a URL make sure the device supports DNS and is properly configured
00035     * for that mode.
00036     * @param port the remote port you want to connect to.
00037     * @param mode an enum that specifies whether this socket connection is type TCP or UDP.
00038     * @returns true if the connection was successfully opened, otherwise false.
00039     */
00040     virtual bool open(const std::string& address, unsigned int port, Mode mode) = 0;
00041 
00042     /** This method is used to determine if a socket connection is currently open.
00043     *
00044     * @returns true if the socket is currently open, otherwise false.
00045     */
00046     virtual bool isOpen() = 0;
00047 
00048     /** This method is used to close a socket connection that is currently open.
00049     *
00050     * @returns true if successfully closed, otherwise returns false on an error.
00051     */
00052     virtual bool close(bool clearBuffer) = 0;
00053 
00054     /** This method is used to read data off of a socket, assuming a valid socket
00055     * connection is already open.
00056     *
00057     * @param data a pointer to the data buffer that will be filled with the read data.
00058     * @param max the maximum number of bytes to attempt to read, typically the same as
00059     * the size of the passed in data buffer.
00060     * @param timeout the amount of time in milliseconds to wait in trying to read the max
00061     * number of bytes. If set to -1 the call blocks until it receives the max number of bytes
00062     * or encounters and error.
00063     * @returns the number of bytes read and stored in the passed in data buffer. Returns
00064     * -1 if there was an error in reading.
00065     */
00066     virtual int read(char* data, int max, int timeout = -1) = 0;
00067 
00068     /** This method is used to write data to a socket, assuming a valid socket
00069     * connection is already open.
00070     *
00071     * @param data a pointer to the data buffer that will be written to the socket.
00072     * @param length the size of the data buffer to be written.
00073     * @param timeout the amount of time in milliseconds to wait in trying to write the entire
00074     * number of bytes. If set to -1 the call blocks until it writes all of the bytes or
00075     * encounters and error.
00076     * @returns the number of bytes written to the socket's write buffer. Returns
00077     * -1 if there was an error in writing.
00078     */
00079     virtual int write(const char* data, int length, int timeout = -1) = 0;
00080 
00081     /** This method is used to get the number of bytes available to read off the
00082     * socket.
00083     *
00084     * @returns the number of bytes available, 0 if there are no bytes to read.
00085     */
00086     virtual unsigned int readable() = 0;
00087 
00088     /** This method is used to get the space available to write bytes to the socket.
00089     *
00090     * @returns the number of bytes that can be written, 0 if unable to write.
00091     */
00092     virtual unsigned int writeable() = 0;
00093 
00094     /** This method is used test network connectivity by pinging a server.
00095     *
00096     * @param address the address of the server in format xxx.xxx.xxx.xxx. The
00097     * default 8.8.8.8 which is Google's DNS Server.
00098     * @returns true if the ping was successful, otherwise false.
00099     */
00100     virtual bool ping(const std::string& address = "8.8.8.8") = 0;
00101 
00102     /** This method is used to get the IP address of the device, which can be
00103     * set either statically or via DHCP after connecting to a network.
00104     *
00105     * @returns the devices IP address.
00106     */
00107     virtual std::string getDeviceIP() = 0;
00108 
00109     /** This method is used to set the IP address or puts the module in DHCP mode.
00110     *
00111     * @param address the IP address you want to use in the form of xxx.xxx.xxx.xxx or DHCP
00112     * if you want to use DHCP. The default is DHCP.
00113     * @returns true if successful, otherwise returns false.
00114     */
00115     virtual bool setDeviceIP(std::string address = "DHCP") = 0;
00116 };
00117 
00118 #endif /* IPSTACK_H */