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