Multi-Hackers / SocketModem

A library for talking to Multi-Tech's Cellular SocketModem Devices.

Dependents:   M2X_dev axeda_wrapper_dev MTS_M2x_Example1 MTS_Cellular_Connect_Example ... more

io/IPStack.h@46:b30547bf07d5, 2013-12-19 (annotated)

Committer:
jengbrecht
Date:
Thu Dec 19 21:48:32 2013 +0000
Revision:
46:b30547bf07d5
Parent:
45:40745c2036cf
Parent:
44:86fa8f50a1df
Child:
139:73a7d1cd2e9c
Merged, removed Axeda Wrapper

Who changed what in which revision?

UserRevisionLine numberNew contents of line
sgodinez 11:134435d8a2d5 1 #ifndef IPSTACK_H
sgodinez 11:134435d8a2d5 2 #define IPSTACK_H
sgodinez 11:134435d8a2d5 3
sgodinez 11:134435d8a2d5 4 #include <string>
sgodinez 11:134435d8a2d5 5
mfiore 39:6e94520a3217 6 namespace mts {
mfiore 40:14342c4de476 7
jengbrecht 36:bb6b293c7495 8 /** This class is a pure virtual class that should be inherited from when implementing
jengbrecht 36:bb6b293c7495 9 * a communications device with an onboard IP stack. Examples of this would be a Wi-Fi
jengbrecht 36:bb6b293c7495 10 * or Cellular radio with a built in IP stack. Typically the IP functionality in these
jengbrecht 36:bb6b293c7495 11 * devices is available through an AT or a similiar command interface. The inheriting
jengbrecht 36:bb6b293c7495 12 * class should map the device commands and functionality to the pure virtual methods provided
jengbrecht 36:bb6b293c7495 13 * here. There should also be at least one or more calls to setup the communication link
jengbrecht 36:bb6b293c7495 14 * specific paramters as an init method for example. This would do things like configure
jengbrecht 36:bb6b293c7495 15 * the APN in a cellular radio or set the ssid for a WiFi device, which cannot be accounted
jengbrecht 36:bb6b293c7495 16 * for in an abstract class like this one.
jengbrecht 27:8e6188cbcfd4 17 */
sgodinez 11:134435d8a2d5 18 class IPStack
sgodinez 11:134435d8a2d5 19 {
sgodinez 11:134435d8a2d5 20 public:
jengbrecht 36:bb6b293c7495 21 /// An enumeration for selecting the Socket Mode of TCP or UDP.
sgodinez 11:134435d8a2d5 22 enum Mode {
sgodinez 11:134435d8a2d5 23 TCP, UDP
sgodinez 11:134435d8a2d5 24 };
sgodinez 11:134435d8a2d5 25
jengbrecht 36:bb6b293c7495 26 /** This method is used to connect the IP layer and below for the interface. Required
jengbrecht 27:8e6188cbcfd4 27 * configurations and settings should be done in other calls or an init function.
jengbrecht 27:8e6188cbcfd4 28 *
jengbrecht 36:bb6b293c7495 29 * @returns true if the connection was successfully established, otherwise false.
jengbrecht 27:8e6188cbcfd4 30 */
jengbrecht 27:8e6188cbcfd4 31 virtual bool connect() = 0;
jengbrecht 27:8e6188cbcfd4 32
jengbrecht 36:bb6b293c7495 33 /** This method is used to disconnect the IP layer and below of the interface. This includes
jengbrecht 27:8e6188cbcfd4 34 * any cleanup required before another connection can be made.
jengbrecht 27:8e6188cbcfd4 35 */
sgodinez 11:134435d8a2d5 36 virtual void disconnect() = 0;
jengbrecht 27:8e6188cbcfd4 37
jengbrecht 36:bb6b293c7495 38 /** This method is used to check if the IP layer of the interface is currently connected.
jengbrecht 27:8e6188cbcfd4 39 *
jengbrecht 27:8e6188cbcfd4 40 * @returns true if currently connected, otherwise false.
jengbrecht 27:8e6188cbcfd4 41 */
sgodinez 11:134435d8a2d5 42 virtual bool isConnected() = 0;
sgodinez 11:134435d8a2d5 43
jengbrecht 27:8e6188cbcfd4 44 /** This method is used to set the local port for the UDP or TCP socket connection.
jengbrecht 27:8e6188cbcfd4 45 * The connection can be made using the open method.
jengbrecht 27:8e6188cbcfd4 46 *
jengbrecht 27:8e6188cbcfd4 47 * @param port the local port of the socket as an int.
jengbrecht 27:8e6188cbcfd4 48 */
sgodinez 11:134435d8a2d5 49 virtual bool bind(unsigned int port) = 0;
jengbrecht 36:bb6b293c7495 50
jengbrecht 27:8e6188cbcfd4 51 /** This method is used to open a socket connection with the given parameters.
jengbrecht 27:8e6188cbcfd4 52 * This socket connection is established using the devices built in IP stack.
jengbrecht 27:8e6188cbcfd4 53 *
jengbrecht 36:bb6b293c7495 54 * @param address is the address you want to connect to in the form of xxx.xxx.xxx.xxx
jengbrecht 45:40745c2036cf 55 * or a URL. If using a URL make sure the device supports DNS and is properly configured
jengbrecht 45:40745c2036cf 56 * for that mode.
jengbrecht 27:8e6188cbcfd4 57 * @param port the remote port you want to connect to.
jengbrecht 36:bb6b293c7495 58 * @param mode an enum that specifies whether this socket connection is type TCP or UDP.
jengbrecht 27:8e6188cbcfd4 59 * @returns true if the connection was successfully opened, otherwise false.
jengbrecht 27:8e6188cbcfd4 60 */
sgodinez 11:134435d8a2d5 61 virtual bool open(const std::string& address, unsigned int port, Mode mode) = 0;
jengbrecht 36:bb6b293c7495 62
jengbrecht 36:bb6b293c7495 63 /** This method is used to determine if a socket connection is currently open.
jengbrecht 27:8e6188cbcfd4 64 *
jengbrecht 27:8e6188cbcfd4 65 * @returns true if the socket is currently open, otherwise false.
jengbrecht 27:8e6188cbcfd4 66 */
sgodinez 11:134435d8a2d5 67 virtual bool isOpen() = 0;
jengbrecht 36:bb6b293c7495 68
jengbrecht 27:8e6188cbcfd4 69 /** This method is used to close a socket connection that is currently open.
jengbrecht 27:8e6188cbcfd4 70 *
jengbrecht 27:8e6188cbcfd4 71 * @returns true if successfully closed, otherwise returns false on an error.
jengbrecht 27:8e6188cbcfd4 72 */
sgodinez 17:2d7c4ea7491b 73 virtual bool close() = 0;
jengbrecht 27:8e6188cbcfd4 74
jengbrecht 36:bb6b293c7495 75 /** This method is used to read data off of a socket, assuming a valid socket
jengbrecht 36:bb6b293c7495 76 * connection is already open.
jengbrecht 36:bb6b293c7495 77 *
jengbrecht 36:bb6b293c7495 78 * @param data a pointer to the data buffer that will be filled with the read data.
jengbrecht 36:bb6b293c7495 79 * @param max the maximum number of bytes to attempt to read, typically the same as
jengbrecht 45:40745c2036cf 80 * the size of the passed in data buffer.
jengbrecht 36:bb6b293c7495 81 * @param timeout the amount of time in milliseconds to wait in trying to read the max
jengbrecht 36:bb6b293c7495 82 * number of bytes. If set to -1 the call blocks until it receives the max number of bytes
jengbrecht 36:bb6b293c7495 83 * or encounters and error.
jengbrecht 36:bb6b293c7495 84 * @returns the number of bytes read and stored in the passed in data buffer. Returns
jengbrecht 36:bb6b293c7495 85 * -1 if there was an error in reading.
jengbrecht 36:bb6b293c7495 86 */
sgodinez 11:134435d8a2d5 87 virtual int read(char* data, int max, int timeout = -1) = 0;
jengbrecht 36:bb6b293c7495 88
jengbrecht 36:bb6b293c7495 89 /** This method is used to write data to a socket, assuming a valid socket
jengbrecht 36:bb6b293c7495 90 * connection is already open.
jengbrecht 36:bb6b293c7495 91 *
jengbrecht 36:bb6b293c7495 92 * @param data a pointer to the data buffer that will be written to the socket.
jengbrecht 36:bb6b293c7495 93 * @param length the size of the data buffer to be written.
jengbrecht 36:bb6b293c7495 94 * @param timeout the amount of time in milliseconds to wait in trying to write the entire
jengbrecht 36:bb6b293c7495 95 * number of bytes. If set to -1 the call blocks until it writes all of the bytes or
jengbrecht 36:bb6b293c7495 96 * encounters and error.
jengbrecht 36:bb6b293c7495 97 * @returns the number of bytes written to the socket's write buffer. Returns
jengbrecht 36:bb6b293c7495 98 * -1 if there was an error in writing.
jengbrecht 36:bb6b293c7495 99 */
sgodinez 41:81d035fb0b6a 100 virtual int write(const char* data, int length, int timeout = -1) = 0;
sgodinez 44:86fa8f50a1df 101
jengbrecht 27:8e6188cbcfd4 102
jengbrecht 27:8e6188cbcfd4 103 /** This method is used to get the number of bytes available to read off the
jengbrecht 27:8e6188cbcfd4 104 * socket.
jengbrecht 27:8e6188cbcfd4 105 *
jengbrecht 27:8e6188cbcfd4 106 * @returns the number of bytes available, 0 if there are no bytes to read.
jengbrecht 27:8e6188cbcfd4 107 */
sgodinez 11:134435d8a2d5 108 virtual unsigned int readable() = 0;
jengbrecht 36:bb6b293c7495 109
jengbrecht 27:8e6188cbcfd4 110 /** This method is used to get the space available to write bytes to the socket.
jengbrecht 27:8e6188cbcfd4 111 *
jengbrecht 45:40745c2036cf 112 * @returns the number of bytes that can be written, 0 if unable to write.
jengbrecht 27:8e6188cbcfd4 113 */
sgodinez 11:134435d8a2d5 114 virtual unsigned int writeable() = 0;
jengbrecht 27:8e6188cbcfd4 115
jengbrecht 36:bb6b293c7495 116 /** This method is used to reset the device that provides the communications
jengbrecht 36:bb6b293c7495 117 * capability. Note that you may have to wait some time after reset before the
jengbrecht 36:bb6b293c7495 118 * device can be used.
jengbrecht 27:8e6188cbcfd4 119 */
sgodinez 11:134435d8a2d5 120 virtual void reset() = 0;
sgodinez 11:134435d8a2d5 121 };
sgodinez 11:134435d8a2d5 122
mfiore 39:6e94520a3217 123 }
mfiore 39:6e94520a3217 124
sgodinez 11:134435d8a2d5 125 #endif /* IPSTACK_H */