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@141:571e0ef6c8dc, 2014-01-04 (annotated)
- Committer:
- kranjan
- Date:
- Sat Jan 04 05:28:45 2014 +0000
- Revision:
- 141:571e0ef6c8dc
- Parent:
- 139:73a7d1cd2e9c
Added licensing header to all files in the library
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
kranjan | 141:571e0ef6c8dc | 1 | /* Universal Socket Modem Interface Library |
kranjan | 141:571e0ef6c8dc | 2 | * Copyright (c) 2013 Multi-Tech Systems |
kranjan | 141:571e0ef6c8dc | 3 | * |
kranjan | 141:571e0ef6c8dc | 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
kranjan | 141:571e0ef6c8dc | 5 | * you may not use this file except in compliance with the License. |
kranjan | 141:571e0ef6c8dc | 6 | * You may obtain a copy of the License at |
kranjan | 141:571e0ef6c8dc | 7 | * |
kranjan | 141:571e0ef6c8dc | 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
kranjan | 141:571e0ef6c8dc | 9 | * |
kranjan | 141:571e0ef6c8dc | 10 | * Unless required by applicable law or agreed to in writing, software |
kranjan | 141:571e0ef6c8dc | 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
kranjan | 141:571e0ef6c8dc | 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
kranjan | 141:571e0ef6c8dc | 13 | * See the License for the specific language governing permissions and |
kranjan | 141:571e0ef6c8dc | 14 | * limitations under the License. |
kranjan | 141:571e0ef6c8dc | 15 | */ |
kranjan | 141:571e0ef6c8dc | 16 | |
sgodinez | 11:134435d8a2d5 | 17 | #ifndef IPSTACK_H |
sgodinez | 11:134435d8a2d5 | 18 | #define IPSTACK_H |
sgodinez | 11:134435d8a2d5 | 19 | |
sgodinez | 11:134435d8a2d5 | 20 | #include <string> |
sgodinez | 11:134435d8a2d5 | 21 | |
mfiore | 39:6e94520a3217 | 22 | namespace mts { |
mfiore | 40:14342c4de476 | 23 | |
jengbrecht | 36:bb6b293c7495 | 24 | /** This class is a pure virtual class that should be inherited from when implementing |
jengbrecht | 36:bb6b293c7495 | 25 | * a communications device with an onboard IP stack. Examples of this would be a Wi-Fi |
jengbrecht | 36:bb6b293c7495 | 26 | * or Cellular radio with a built in IP stack. Typically the IP functionality in these |
jengbrecht | 36:bb6b293c7495 | 27 | * devices is available through an AT or a similiar command interface. The inheriting |
jengbrecht | 36:bb6b293c7495 | 28 | * class should map the device commands and functionality to the pure virtual methods provided |
jengbrecht | 36:bb6b293c7495 | 29 | * here. There should also be at least one or more calls to setup the communication link |
jengbrecht | 36:bb6b293c7495 | 30 | * specific paramters as an init method for example. This would do things like configure |
jengbrecht | 36:bb6b293c7495 | 31 | * the APN in a cellular radio or set the ssid for a WiFi device, which cannot be accounted |
jengbrecht | 36:bb6b293c7495 | 32 | * for in an abstract class like this one. |
jengbrecht | 27:8e6188cbcfd4 | 33 | */ |
sgodinez | 11:134435d8a2d5 | 34 | class IPStack |
sgodinez | 11:134435d8a2d5 | 35 | { |
sgodinez | 11:134435d8a2d5 | 36 | public: |
jengbrecht | 36:bb6b293c7495 | 37 | /// An enumeration for selecting the Socket Mode of TCP or UDP. |
sgodinez | 11:134435d8a2d5 | 38 | enum Mode { |
sgodinez | 11:134435d8a2d5 | 39 | TCP, UDP |
sgodinez | 11:134435d8a2d5 | 40 | }; |
sgodinez | 11:134435d8a2d5 | 41 | |
jengbrecht | 36:bb6b293c7495 | 42 | /** This method is used to connect the IP layer and below for the interface. Required |
jengbrecht | 27:8e6188cbcfd4 | 43 | * configurations and settings should be done in other calls or an init function. |
jengbrecht | 27:8e6188cbcfd4 | 44 | * |
jengbrecht | 36:bb6b293c7495 | 45 | * @returns true if the connection was successfully established, otherwise false. |
jengbrecht | 27:8e6188cbcfd4 | 46 | */ |
jengbrecht | 27:8e6188cbcfd4 | 47 | virtual bool connect() = 0; |
jengbrecht | 27:8e6188cbcfd4 | 48 | |
jengbrecht | 36:bb6b293c7495 | 49 | /** This method is used to disconnect the IP layer and below of the interface. This includes |
jengbrecht | 27:8e6188cbcfd4 | 50 | * any cleanup required before another connection can be made. |
jengbrecht | 27:8e6188cbcfd4 | 51 | */ |
sgodinez | 11:134435d8a2d5 | 52 | virtual void disconnect() = 0; |
jengbrecht | 27:8e6188cbcfd4 | 53 | |
jengbrecht | 36:bb6b293c7495 | 54 | /** This method is used to check if the IP layer of the interface is currently connected. |
jengbrecht | 27:8e6188cbcfd4 | 55 | * |
jengbrecht | 27:8e6188cbcfd4 | 56 | * @returns true if currently connected, otherwise false. |
jengbrecht | 27:8e6188cbcfd4 | 57 | */ |
sgodinez | 11:134435d8a2d5 | 58 | virtual bool isConnected() = 0; |
sgodinez | 11:134435d8a2d5 | 59 | |
jengbrecht | 27:8e6188cbcfd4 | 60 | /** This method is used to set the local port for the UDP or TCP socket connection. |
jengbrecht | 27:8e6188cbcfd4 | 61 | * The connection can be made using the open method. |
jengbrecht | 27:8e6188cbcfd4 | 62 | * |
jengbrecht | 27:8e6188cbcfd4 | 63 | * @param port the local port of the socket as an int. |
jengbrecht | 27:8e6188cbcfd4 | 64 | */ |
sgodinez | 11:134435d8a2d5 | 65 | virtual bool bind(unsigned int port) = 0; |
jengbrecht | 36:bb6b293c7495 | 66 | |
jengbrecht | 27:8e6188cbcfd4 | 67 | /** This method is used to open a socket connection with the given parameters. |
jengbrecht | 27:8e6188cbcfd4 | 68 | * This socket connection is established using the devices built in IP stack. |
jengbrecht | 139:73a7d1cd2e9c | 69 | * Currently TCP is the only supported mode. |
jengbrecht | 27:8e6188cbcfd4 | 70 | * |
jengbrecht | 36:bb6b293c7495 | 71 | * @param address is the address you want to connect to in the form of xxx.xxx.xxx.xxx |
jengbrecht | 45:40745c2036cf | 72 | * or a URL. If using a URL make sure the device supports DNS and is properly configured |
jengbrecht | 45:40745c2036cf | 73 | * for that mode. |
jengbrecht | 27:8e6188cbcfd4 | 74 | * @param port the remote port you want to connect to. |
jengbrecht | 36:bb6b293c7495 | 75 | * @param mode an enum that specifies whether this socket connection is type TCP or UDP. |
jengbrecht | 139:73a7d1cd2e9c | 76 | * Currently only TCP is supported. |
jengbrecht | 27:8e6188cbcfd4 | 77 | * @returns true if the connection was successfully opened, otherwise false. |
jengbrecht | 27:8e6188cbcfd4 | 78 | */ |
sgodinez | 11:134435d8a2d5 | 79 | virtual bool open(const std::string& address, unsigned int port, Mode mode) = 0; |
jengbrecht | 36:bb6b293c7495 | 80 | |
jengbrecht | 36:bb6b293c7495 | 81 | /** This method is used to determine if a socket connection is currently open. |
jengbrecht | 27:8e6188cbcfd4 | 82 | * |
jengbrecht | 27:8e6188cbcfd4 | 83 | * @returns true if the socket is currently open, otherwise false. |
jengbrecht | 27:8e6188cbcfd4 | 84 | */ |
sgodinez | 11:134435d8a2d5 | 85 | virtual bool isOpen() = 0; |
jengbrecht | 36:bb6b293c7495 | 86 | |
jengbrecht | 27:8e6188cbcfd4 | 87 | /** This method is used to close a socket connection that is currently open. |
jengbrecht | 27:8e6188cbcfd4 | 88 | * |
jengbrecht | 27:8e6188cbcfd4 | 89 | * @returns true if successfully closed, otherwise returns false on an error. |
jengbrecht | 27:8e6188cbcfd4 | 90 | */ |
sgodinez | 17:2d7c4ea7491b | 91 | virtual bool close() = 0; |
jengbrecht | 27:8e6188cbcfd4 | 92 | |
jengbrecht | 36:bb6b293c7495 | 93 | /** This method is used to read data off of a socket, assuming a valid socket |
jengbrecht | 36:bb6b293c7495 | 94 | * connection is already open. |
jengbrecht | 36:bb6b293c7495 | 95 | * |
jengbrecht | 36:bb6b293c7495 | 96 | * @param data a pointer to the data buffer that will be filled with the read data. |
jengbrecht | 36:bb6b293c7495 | 97 | * @param max the maximum number of bytes to attempt to read, typically the same as |
jengbrecht | 45:40745c2036cf | 98 | * the size of the passed in data buffer. |
jengbrecht | 36:bb6b293c7495 | 99 | * @param timeout the amount of time in milliseconds to wait in trying to read the max |
jengbrecht | 36:bb6b293c7495 | 100 | * number of bytes. If set to -1 the call blocks until it receives the max number of bytes |
jengbrecht | 36:bb6b293c7495 | 101 | * or encounters and error. |
jengbrecht | 36:bb6b293c7495 | 102 | * @returns the number of bytes read and stored in the passed in data buffer. Returns |
jengbrecht | 36:bb6b293c7495 | 103 | * -1 if there was an error in reading. |
jengbrecht | 36:bb6b293c7495 | 104 | */ |
sgodinez | 11:134435d8a2d5 | 105 | virtual int read(char* data, int max, int timeout = -1) = 0; |
jengbrecht | 36:bb6b293c7495 | 106 | |
jengbrecht | 36:bb6b293c7495 | 107 | /** This method is used to write data to a socket, assuming a valid socket |
jengbrecht | 36:bb6b293c7495 | 108 | * connection is already open. |
jengbrecht | 36:bb6b293c7495 | 109 | * |
jengbrecht | 36:bb6b293c7495 | 110 | * @param data a pointer to the data buffer that will be written to the socket. |
jengbrecht | 36:bb6b293c7495 | 111 | * @param length the size of the data buffer to be written. |
jengbrecht | 36:bb6b293c7495 | 112 | * @param timeout the amount of time in milliseconds to wait in trying to write the entire |
jengbrecht | 36:bb6b293c7495 | 113 | * number of bytes. If set to -1 the call blocks until it writes all of the bytes or |
jengbrecht | 36:bb6b293c7495 | 114 | * encounters and error. |
jengbrecht | 36:bb6b293c7495 | 115 | * @returns the number of bytes written to the socket's write buffer. Returns |
jengbrecht | 36:bb6b293c7495 | 116 | * -1 if there was an error in writing. |
jengbrecht | 36:bb6b293c7495 | 117 | */ |
sgodinez | 41:81d035fb0b6a | 118 | virtual int write(const char* data, int length, int timeout = -1) = 0; |
sgodinez | 44:86fa8f50a1df | 119 | |
jengbrecht | 27:8e6188cbcfd4 | 120 | |
jengbrecht | 27:8e6188cbcfd4 | 121 | /** This method is used to get the number of bytes available to read off the |
jengbrecht | 27:8e6188cbcfd4 | 122 | * socket. |
jengbrecht | 27:8e6188cbcfd4 | 123 | * |
jengbrecht | 27:8e6188cbcfd4 | 124 | * @returns the number of bytes available, 0 if there are no bytes to read. |
jengbrecht | 27:8e6188cbcfd4 | 125 | */ |
sgodinez | 11:134435d8a2d5 | 126 | virtual unsigned int readable() = 0; |
jengbrecht | 36:bb6b293c7495 | 127 | |
jengbrecht | 27:8e6188cbcfd4 | 128 | /** This method is used to get the space available to write bytes to the socket. |
jengbrecht | 27:8e6188cbcfd4 | 129 | * |
jengbrecht | 45:40745c2036cf | 130 | * @returns the number of bytes that can be written, 0 if unable to write. |
jengbrecht | 27:8e6188cbcfd4 | 131 | */ |
sgodinez | 11:134435d8a2d5 | 132 | virtual unsigned int writeable() = 0; |
jengbrecht | 27:8e6188cbcfd4 | 133 | |
jengbrecht | 36:bb6b293c7495 | 134 | /** This method is used to reset the device that provides the communications |
jengbrecht | 36:bb6b293c7495 | 135 | * capability. Note that you may have to wait some time after reset before the |
jengbrecht | 36:bb6b293c7495 | 136 | * device can be used. |
jengbrecht | 27:8e6188cbcfd4 | 137 | */ |
sgodinez | 11:134435d8a2d5 | 138 | virtual void reset() = 0; |
sgodinez | 11:134435d8a2d5 | 139 | }; |
sgodinez | 11:134435d8a2d5 | 140 | |
mfiore | 39:6e94520a3217 | 141 | } |
mfiore | 39:6e94520a3217 | 142 | |
sgodinez | 11:134435d8a2d5 | 143 | #endif /* IPSTACK_H */ |