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@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?

UserRevisionLine numberNew 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 */