1 /* 2 Copyright (c) 2007-2019 by Jakob Schröter <js@camaya.net> 3 This file is part of the gloox library. http://camaya.net/gloox 4 5 This software is distributed under a license. The full license 6 agreement can be found in the file LICENSE in this distribution. 7 This software may not be copied, modified, sold or distributed 8 other than expressed in the named license agreement. 9 10 This software is distributed without any warranty. 11 */ 12 13 14 15 #ifndef CONNECTIONBASE_H__ 16 #define CONNECTIONBASE_H__ 17 18 #include "gloox.h" 19 #include "connectiondatahandler.h" 20 21 #include <string> 22 23 namespace gloox 24 { 25 26 /** 27 * @brief An abstract base class for a connection. 28 * 29 * You should not need to use this class directly. 30 * 31 * @author Jakob Schröter <js@camaya.net> 32 * @since 0.9 33 */ 34 class GLOOX_API ConnectionBase 35 { 36 public: 37 /** 38 * Constructor. 39 * @param cdh An object derived from @ref ConnectionDataHandler that will receive 40 * received data. 41 */ ConnectionBase(ConnectionDataHandler * cdh)42 ConnectionBase( ConnectionDataHandler* cdh ) 43 : m_handler( cdh ), m_state( StateDisconnected ), m_port( -1 ) 44 {} 45 46 /** 47 * Virtual destructor. 48 */ ~ConnectionBase()49 virtual ~ConnectionBase() { cleanup(); } 50 51 /** 52 * Used to initiate the connection. 53 * @return Returns the connection state. 54 */ 55 virtual ConnectionError connect() = 0; 56 57 /** 58 * Use this periodically to receive data from the socket. 59 * @param timeout The timeout to use for select in microseconds. Default of -1 means blocking. 60 * @return The state of the connection. 61 */ 62 virtual ConnectionError recv( int timeout = -1 ) = 0; 63 64 /** 65 * Use this function to send a string of data over the wire. The function returns only after 66 * all data has been sent. 67 * @param data The data to send. 68 * @return @b True if the data has been sent (no guarantee of receipt), @b false 69 * in case of an error. 70 */ 71 virtual bool send( const std::string& data ) = 0; 72 73 /** 74 * Use this function to put the connection into 'receive mode', i.e. this function returns only 75 * when the connection is terminated. 76 * @return Returns a value indicating the disconnection reason. 77 */ 78 virtual ConnectionError receive() = 0; 79 80 /** 81 * Disconnects an established connection. NOOP if no active connection exists. 82 */ 83 virtual void disconnect() = 0; 84 85 /** 86 * This function is called after a disconnect to clean up internal state. It is also called by 87 * ConnectionBase's destructor. 88 */ cleanup()89 virtual void cleanup() {} 90 91 /** 92 * Returns the current connection state. 93 * @return The state of the connection. 94 */ state()95 ConnectionState state() const { return m_state; } 96 97 /** 98 * Use this function to register a new ConnectionDataHandler. There can be only one 99 * ConnectionDataHandler at any one time. 100 * @param cdh The new ConnectionDataHandler. 101 */ registerConnectionDataHandler(ConnectionDataHandler * cdh)102 void registerConnectionDataHandler( ConnectionDataHandler* cdh ) { m_handler = cdh; } 103 104 /** 105 * Sets the server to connect to. 106 * @param server The server to connect to. Either IP or fully qualified domain name. 107 * @param port The port to connect to. 108 */ 109 void setServer( const std::string &server, int port = -1 ) { m_server = server; m_port = port; } 110 111 /** 112 * Returns the currently set server/IP. 113 * @return The server host/IP. 114 */ server()115 const std::string& server() const { return m_server; } 116 117 /** 118 * Returns the currently set port. 119 * @return The server port. 120 */ port()121 int port() const { return m_port; } 122 123 /** 124 * Returns the local port. 125 * @return The local port. 126 */ localPort()127 virtual int localPort() const { return -1; } 128 129 /** 130 * Returns the locally bound IP address. 131 * @return The locally bound IP address. 132 */ localInterface()133 virtual const std::string localInterface() const { return EmptyString; } 134 135 /** 136 * Returns current connection statistics. 137 * @param totalIn The total number of bytes received. 138 * @param totalOut The total number of bytes sent. 139 */ 140 virtual void getStatistics( long int &totalIn, long int &totalOut ) = 0; 141 142 /** 143 * This function returns a new instance of the current ConnectionBase-derived object. 144 * The idea is to be able to 'clone' ConnectionBase-derived objects without knowing of 145 * what type they are exactly. 146 * @return A new Connection* instance. 147 */ 148 virtual ConnectionBase* newInstance() const = 0; 149 150 protected: 151 /** A handler for incoming data and connect/disconnect events. */ 152 ConnectionDataHandler* m_handler; 153 154 /** Holds the current connection state. */ 155 ConnectionState m_state; 156 157 /** Holds the server's name/address. */ 158 std::string m_server; 159 160 /** Holds the port to connect to. */ 161 int m_port; 162 163 }; 164 165 } 166 167 #endif // CONNECTIONBASE_H__ 168