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@36:bb6b293c7495, 2013-12-19 (annotated)

Committer:
jengbrecht
Date:
Thu Dec 19 16:47:26 2013 +0000
Revision:
36:bb6b293c7495
Parent:
27:8e6188cbcfd4
Child:
40:14342c4de476
Child:
45:40745c2036cf
Added a ton more documentation to most of the headers files. Also removed the capacity and available functions from MTSBufferedIO in favor of readable and writeable. Removed the single available method call from the cellular class.

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