IPStack.h

00001 /* Universal Socket Modem Interface Library
00002 * Copyright (c) 2013 Multi-Tech Systems
00003 *
00004 * Licensed under the Apache License, Version 2.0 (the "License");
00005 * you may not use this file except in compliance with the License.
00006 * You may obtain a copy of the License at
00007 *
00008 *     http://www.apache.org/licenses/LICENSE-2.0
00009 *
00010 * Unless required by applicable law or agreed to in writing, software
00011 * distributed under the License is distributed on an "AS IS" BASIS,
00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013 * See the License for the specific language governing permissions and
00014 * limitations under the License.
00015 */
00016 
00017 #ifndef IPSTACK_H
00018 #define IPSTACK_H
00019 
00020 #include <string>
00021 
00022 namespace mts {
00023     
00024 /** This class is a pure virtual class that should be inherited from when implementing
00025 * a communications device with an onboard IP stack.  Examples of this would be a Wi-Fi
00026 * or Cellular radio with a built in IP stack. Typically the IP functionality in these
00027 * devices is available through an AT or a similiar command interface. The inheriting
00028 * class should map the device commands and functionality to the pure virtual methods provided
00029 * here. There should also be at least one or more calls to setup the communication link
00030 * specific paramters as an init method for example.  This would do things like configure
00031 * the APN in a cellular radio or set the ssid for a WiFi device, which cannot be accounted
00032 * for in an abstract class like this one.
00033 */
00034 class IPStack
00035 {
00036 public:
00037     /// An enumeration for selecting the Socket Mode of TCP or UDP.
00038     enum Mode {
00039         TCP, UDP
00040     };
00041 
00042     /** This method is used to connect the IP layer and below for the interface. Required
00043     * configurations and settings should be done in other calls or an init function.
00044     *
00045     * @returns true if the connection was successfully established, otherwise false.
00046     */
00047     virtual bool connect() = 0;
00048 
00049     /** This method is used to disconnect the IP layer and below of the interface. This includes
00050     * any cleanup required before another connection can be made.
00051     */
00052     virtual void disconnect() = 0;
00053 
00054     /** This method is used to check if the IP layer of the interface is currently connected.
00055     *
00056     * @returns true if currently connected, otherwise false.
00057     */
00058     virtual bool isConnected() = 0;
00059 
00060     /** This method is used to set the local port for the UDP or TCP socket connection.
00061     * The connection can be made using the open method.
00062     *
00063     * @param port the local port of the socket as an int.
00064     */
00065     virtual bool bind(unsigned int port) = 0;
00066 
00067     /** This method is used to open a socket connection with the given parameters.
00068     * This socket connection is established using the devices built in IP stack.
00069     * Currently TCP is the only supported mode.
00070     *
00071     * @param address is the address you want to connect to in the form of xxx.xxx.xxx.xxx
00072     * or a URL. If using a URL make sure the device supports DNS and is properly configured
00073     * for that mode.
00074     * @param port the remote port you want to connect to.
00075     * @param mode an enum that specifies whether this socket connection is type TCP or UDP.
00076     * Currently only TCP is supported.
00077     * @returns true if the connection was successfully opened, otherwise false.
00078     */
00079     virtual bool open(const std::string& address, unsigned int port, Mode mode) = 0;
00080 
00081     /** This method is used to determine if a socket connection is currently open.
00082     *
00083     * @returns true if the socket is currently open, otherwise false.
00084     */
00085     virtual bool isOpen() = 0;
00086 
00087     /** This method is used to close a socket connection that is currently open.
00088     *
00089     * @returns true if successfully closed, otherwise returns false on an error.
00090     */
00091     virtual bool close() = 0;
00092 
00093     /** This method is used to read data off of a socket, assuming a valid socket
00094     * connection is already open.
00095     *
00096     * @param data a pointer to the data buffer that will be filled with the read data.
00097     * @param max the maximum number of bytes to attempt to read, typically the same as
00098     * the size of the passed in data buffer.
00099     * @param timeout the amount of time in milliseconds to wait in trying to read the max
00100     * number of bytes. If set to -1 the call blocks until it receives the max number of bytes
00101     * or encounters and error.
00102     * @returns the number of bytes read and stored in the passed in data buffer. Returns
00103     * -1 if there was an error in reading.
00104     */
00105     virtual int read(char* data, int max, int timeout = -1) = 0;
00106 
00107     /** This method is used to write data to a socket, assuming a valid socket
00108     * connection is already open.
00109     *
00110     * @param data a pointer to the data buffer that will be written to the socket.
00111     * @param length the size of the data buffer to be written.
00112     * @param timeout the amount of time in milliseconds to wait in trying to write the entire
00113     * number of bytes. If set to -1 the call blocks until it writes all of the bytes or 
00114     * encounters and error.
00115     * @returns the number of bytes written to the socket's write buffer. Returns
00116     * -1 if there was an error in writing.
00117     */
00118     virtual int write(const char* data, int length, int timeout = -1) = 0;
00119 
00120 
00121     /** This method is used to get the number of bytes available to read off the
00122     * socket.
00123     *
00124     * @returns the number of bytes available, 0 if there are no bytes to read.
00125     */
00126     virtual unsigned int readable() = 0;
00127 
00128     /** This method is used to get the space available to write bytes to the socket.
00129     *
00130     * @returns the number of bytes that can be written, 0 if unable to write.
00131     */
00132     virtual unsigned int writeable() = 0;
00133 
00134     /** This method is used to reset the device that provides the communications
00135     * capability. Note that you may have to wait some time after reset before the
00136     * device can be used.
00137     */
00138     virtual void reset() = 0;
00139 };
00140 
00141 }
00142 
00143 #endif /* IPSTACK_H */