For bug fixes
Fork of MTS-Socket by
IPStack.h@18:119547e27ff1, 2014-10-21 (annotated)
- Committer:
- Vanger
- Date:
- Tue Oct 21 17:27:23 2014 +0000
- Revision:
- 18:119547e27ff1
- Parent:
- 2:ebc6129de4e8
Added buffer clear flag for close() calls to allow for closing sockets without clearing the data buffers.
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
mfiore | 0:eef30dbe1130 | 1 | #ifndef IPSTACK_H |
mfiore | 0:eef30dbe1130 | 2 | #define IPSTACK_H |
mfiore | 0:eef30dbe1130 | 3 | |
Mike Fiore |
1:096f484f3ae6 | 4 | #include <string> |
Mike Fiore |
1:096f484f3ae6 | 5 | #include "CommInterface.h" |
Mike Fiore |
1:096f484f3ae6 | 6 | |
Mike Fiore |
1:096f484f3ae6 | 7 | /** This class is a pure virtual class that should be inherited from when implementing |
Mike Fiore |
1:096f484f3ae6 | 8 | * a communications device with an onboard IP stack. Examples of this would be a Wi-Fi |
Mike Fiore |
1:096f484f3ae6 | 9 | * or Cellular radio. The inheriting class should map the device commands and functionality |
Mike Fiore |
1:096f484f3ae6 | 10 | * to the pure virtual methods provided here. There should also be at least one or more calls |
Mike Fiore |
1:096f484f3ae6 | 11 | * to setup the communication link specific paramters as an init method for example. This |
Mike Fiore |
1:096f484f3ae6 | 12 | * would do things like configure the APN in a cellular radio or set the ssid for a WiFi device, |
Mike Fiore |
1:096f484f3ae6 | 13 | * which cannot be accounted for in an abstract class like this one. Note that to provide physical |
Mike Fiore |
1:096f484f3ae6 | 14 | * connection management methods this class inherits from CommInterface. |
Mike Fiore |
1:096f484f3ae6 | 15 | */ |
Mike Fiore |
1:096f484f3ae6 | 16 | class IPStack : public CommInterface |
Mike Fiore |
1:096f484f3ae6 | 17 | { |
Mike Fiore |
1:096f484f3ae6 | 18 | public: |
Mike Fiore |
1:096f484f3ae6 | 19 | /// An enumeration for selecting the Socket Mode of TCP or UDP. |
Mike Fiore |
1:096f484f3ae6 | 20 | enum Mode { |
Mike Fiore |
1:096f484f3ae6 | 21 | TCP, UDP |
Mike Fiore |
1:096f484f3ae6 | 22 | }; |
Mike Fiore |
1:096f484f3ae6 | 23 | |
Mike Fiore |
1:096f484f3ae6 | 24 | /** This method is used to set the local port for the UDP or TCP socket connection. |
Mike Fiore |
1:096f484f3ae6 | 25 | * The connection can be made using the open method. |
Mike Fiore |
1:096f484f3ae6 | 26 | * |
Mike Fiore |
1:096f484f3ae6 | 27 | * @param port the local port of the socket as an int. |
Mike Fiore |
1:096f484f3ae6 | 28 | */ |
Mike Fiore |
1:096f484f3ae6 | 29 | virtual bool bind(unsigned int port) = 0; |
Mike Fiore |
1:096f484f3ae6 | 30 | |
Mike Fiore |
1:096f484f3ae6 | 31 | /** This method is used to open a socket connection with the given parameters. |
Mike Fiore |
1:096f484f3ae6 | 32 | * |
Mike Fiore |
1:096f484f3ae6 | 33 | * @param address is the address you want to connect to in the form of xxx.xxx.xxx.xxx |
Mike Fiore |
1:096f484f3ae6 | 34 | * or a URL. If using a URL make sure the device supports DNS and is properly configured |
Mike Fiore |
1:096f484f3ae6 | 35 | * for that mode. |
Mike Fiore |
1:096f484f3ae6 | 36 | * @param port the remote port you want to connect to. |
Mike Fiore |
1:096f484f3ae6 | 37 | * @param mode an enum that specifies whether this socket connection is type TCP or UDP. |
Mike Fiore |
1:096f484f3ae6 | 38 | * @returns true if the connection was successfully opened, otherwise false. |
Mike Fiore |
1:096f484f3ae6 | 39 | */ |
Mike Fiore |
1:096f484f3ae6 | 40 | virtual bool open(const std::string& address, unsigned int port, Mode mode) = 0; |
Mike Fiore |
1:096f484f3ae6 | 41 | |
Mike Fiore |
1:096f484f3ae6 | 42 | /** This method is used to determine if a socket connection is currently open. |
Mike Fiore |
1:096f484f3ae6 | 43 | * |
Mike Fiore |
1:096f484f3ae6 | 44 | * @returns true if the socket is currently open, otherwise false. |
Mike Fiore |
1:096f484f3ae6 | 45 | */ |
Mike Fiore |
1:096f484f3ae6 | 46 | virtual bool isOpen() = 0; |
Mike Fiore |
1:096f484f3ae6 | 47 | |
Mike Fiore |
1:096f484f3ae6 | 48 | /** This method is used to close a socket connection that is currently open. |
Mike Fiore |
1:096f484f3ae6 | 49 | * |
Mike Fiore |
1:096f484f3ae6 | 50 | * @returns true if successfully closed, otherwise returns false on an error. |
Mike Fiore |
1:096f484f3ae6 | 51 | */ |
Vanger | 18:119547e27ff1 | 52 | virtual bool close(bool clearBuffer) = 0; |
Mike Fiore |
1:096f484f3ae6 | 53 | |
Mike Fiore |
1:096f484f3ae6 | 54 | /** This method is used to read data off of a socket, assuming a valid socket |
Mike Fiore |
1:096f484f3ae6 | 55 | * connection is already open. |
Mike Fiore |
1:096f484f3ae6 | 56 | * |
Mike Fiore |
1:096f484f3ae6 | 57 | * @param data a pointer to the data buffer that will be filled with the read data. |
Mike Fiore |
1:096f484f3ae6 | 58 | * @param max the maximum number of bytes to attempt to read, typically the same as |
Mike Fiore |
1:096f484f3ae6 | 59 | * the size of the passed in data buffer. |
Mike Fiore |
1:096f484f3ae6 | 60 | * @param timeout the amount of time in milliseconds to wait in trying to read the max |
Mike Fiore |
1:096f484f3ae6 | 61 | * number of bytes. If set to -1 the call blocks until it receives the max number of bytes |
Mike Fiore |
1:096f484f3ae6 | 62 | * or encounters and error. |
Mike Fiore |
1:096f484f3ae6 | 63 | * @returns the number of bytes read and stored in the passed in data buffer. Returns |
Mike Fiore |
1:096f484f3ae6 | 64 | * -1 if there was an error in reading. |
Mike Fiore |
1:096f484f3ae6 | 65 | */ |
Mike Fiore |
1:096f484f3ae6 | 66 | virtual int read(char* data, int max, int timeout = -1) = 0; |
Mike Fiore |
1:096f484f3ae6 | 67 | |
Mike Fiore |
1:096f484f3ae6 | 68 | /** This method is used to write data to a socket, assuming a valid socket |
Mike Fiore |
1:096f484f3ae6 | 69 | * connection is already open. |
Mike Fiore |
1:096f484f3ae6 | 70 | * |
Mike Fiore |
1:096f484f3ae6 | 71 | * @param data a pointer to the data buffer that will be written to the socket. |
Mike Fiore |
1:096f484f3ae6 | 72 | * @param length the size of the data buffer to be written. |
Mike Fiore |
1:096f484f3ae6 | 73 | * @param timeout the amount of time in milliseconds to wait in trying to write the entire |
Mike Fiore |
1:096f484f3ae6 | 74 | * number of bytes. If set to -1 the call blocks until it writes all of the bytes or |
Mike Fiore |
1:096f484f3ae6 | 75 | * encounters and error. |
Mike Fiore |
1:096f484f3ae6 | 76 | * @returns the number of bytes written to the socket's write buffer. Returns |
Mike Fiore |
1:096f484f3ae6 | 77 | * -1 if there was an error in writing. |
Mike Fiore |
1:096f484f3ae6 | 78 | */ |
Mike Fiore |
1:096f484f3ae6 | 79 | virtual int write(const char* data, int length, int timeout = -1) = 0; |
Mike Fiore |
1:096f484f3ae6 | 80 | |
Mike Fiore |
1:096f484f3ae6 | 81 | /** This method is used to get the number of bytes available to read off the |
Mike Fiore |
1:096f484f3ae6 | 82 | * socket. |
Mike Fiore |
1:096f484f3ae6 | 83 | * |
Mike Fiore |
1:096f484f3ae6 | 84 | * @returns the number of bytes available, 0 if there are no bytes to read. |
Mike Fiore |
1:096f484f3ae6 | 85 | */ |
Mike Fiore |
1:096f484f3ae6 | 86 | virtual unsigned int readable() = 0; |
Mike Fiore |
1:096f484f3ae6 | 87 | |
Mike Fiore |
1:096f484f3ae6 | 88 | /** This method is used to get the space available to write bytes to the socket. |
Mike Fiore |
1:096f484f3ae6 | 89 | * |
Mike Fiore |
1:096f484f3ae6 | 90 | * @returns the number of bytes that can be written, 0 if unable to write. |
Mike Fiore |
1:096f484f3ae6 | 91 | */ |
Mike Fiore |
1:096f484f3ae6 | 92 | virtual unsigned int writeable() = 0; |
Mike Fiore |
1:096f484f3ae6 | 93 | |
Mike Fiore |
1:096f484f3ae6 | 94 | /** This method is used test network connectivity by pinging a server. |
Mike Fiore |
1:096f484f3ae6 | 95 | * |
Mike Fiore |
1:096f484f3ae6 | 96 | * @param address the address of the server in format xxx.xxx.xxx.xxx. The |
Mike Fiore |
1:096f484f3ae6 | 97 | * default 8.8.8.8 which is Google's DNS Server. |
Mike Fiore |
1:096f484f3ae6 | 98 | * @returns true if the ping was successful, otherwise false. |
Mike Fiore |
1:096f484f3ae6 | 99 | */ |
Mike Fiore |
1:096f484f3ae6 | 100 | virtual bool ping(const std::string& address = "8.8.8.8") = 0; |
Mike Fiore |
1:096f484f3ae6 | 101 | |
Mike Fiore |
1:096f484f3ae6 | 102 | /** This method is used to get the IP address of the device, which can be |
Mike Fiore |
1:096f484f3ae6 | 103 | * set either statically or via DHCP after connecting to a network. |
Mike Fiore |
1:096f484f3ae6 | 104 | * |
Mike Fiore |
1:096f484f3ae6 | 105 | * @returns the devices IP address. |
Mike Fiore |
1:096f484f3ae6 | 106 | */ |
Mike Fiore |
1:096f484f3ae6 | 107 | virtual std::string getDeviceIP() = 0; |
Mike Fiore |
1:096f484f3ae6 | 108 | |
Mike Fiore |
1:096f484f3ae6 | 109 | /** This method is used to set the IP address or puts the module in DHCP mode. |
Mike Fiore |
1:096f484f3ae6 | 110 | * |
Mike Fiore |
1:096f484f3ae6 | 111 | * @param address the IP address you want to use in the form of xxx.xxx.xxx.xxx or DHCP |
Mike Fiore |
1:096f484f3ae6 | 112 | * if you want to use DHCP. The default is DHCP. |
Mike Fiore |
1:096f484f3ae6 | 113 | * @returns true if successful, otherwise returns false. |
Mike Fiore |
1:096f484f3ae6 | 114 | */ |
Mike Fiore |
1:096f484f3ae6 | 115 | virtual bool setDeviceIP(std::string address = "DHCP") = 0; |
Mike Fiore |
1:096f484f3ae6 | 116 | }; |
Mike Fiore |
1:096f484f3ae6 | 117 | |
Mike Fiore |
1:096f484f3ae6 | 118 | #endif /* IPSTACK_H */ |