summaryrefslogtreecommitdiffstats
path: root/src/OSSupport/Network.h
blob: cb5badaebf984a2ae12467f8195dc14ed4bac08d (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

// Network.h

// Declares the classes used for the Network API





#pragma once





/** Interface that provides the methods available on a single TCP connection. */
class cTCPLink
{
	friend class cNetwork;

public:
	class cCallbacks
	{
	public:
		// Force a virtual destructor for all descendants:
		virtual ~cCallbacks() {}

		/** Called when there's data incoming from the remote peer. */
		virtual void OnReceivedData(cTCPLink & a_Link, const char * a_Data, size_t a_Length) = 0;

		/** Called when the remote end closes the connection.
		The link is still available for connection information query (IP / port).
		Sending data on the link is not an error, but the data won't be delivered. */
		virtual void OnRemoteClosed(cTCPLink & a_Link) = 0;

		/** Called when an error is detected on the connection. */
		virtual void OnError(cTCPLink & a_Link, int a_ErrorCode) = 0;
	};
	typedef SharedPtr<cCallbacks> cCallbacksPtr;


	// Force a virtual destructor for all descendants:
	virtual ~cTCPLink() {}

	/** Queues the specified data for sending to the remote peer.
	Returns true on success, false on failure. Note that this success or failure only reports the queue status, not the actual data delivery. */
	virtual bool Send(const void * a_Data, size_t a_Length) = 0;

	/** Queues the specified data for sending to the remote peer.
	Returns true on success, false on failure. Note that this success or failure only reports the queue status, not the actual data delivery. */
	bool Send(const AString & a_Data)
	{
		return Send(a_Data.data(), a_Data.size());
	}

	/** Returns the IP address of the local endpoint of the connection. */
	virtual AString GetLocalIP(void) const = 0;

	/** Returns the port used by the local endpoint of the connection. */
	virtual UInt16 GetLocalPort(void) const = 0;

	/** Returns the IP address of the remote endpoint of the connection. */
	virtual AString GetRemoteIP(void) const = 0;

	/** Returns the port used by the remote endpoint of the connection. */
	virtual UInt16 GetRemotePort(void) const = 0;

	/** Closes the link gracefully.
	The link will send any queued outgoing data, then it will send the FIN packet.
	The link will still receive incoming data from remote until the remote closes the connection. */
	virtual void Shutdown(void) = 0;

	/** Drops the connection without any more processing.
	Sends the RST packet, queued outgoing and incoming data is lost. */
	virtual void Close(void) = 0;

protected:
	/** Callbacks to be used for the various situations. */
	cCallbacksPtr m_Callbacks;


	/** Creates a new link, with the specified callbacks. */
	cTCPLink(cCallbacksPtr a_Callbacks);
};





/** Interface that provides the methods available on a listening server socket. */
class cServerHandle
{
	friend class cNetwork;
public:

	// Force a virtual destructor for all descendants:
	virtual ~cServerHandle() {}

	/** Stops the server, no more incoming connections will be accepted.
	All current connections will be shut down (cTCPLink::Shutdown()). */
	virtual void Close(void) = 0;

	/** Returns true if the server has been started correctly and is currently listening for incoming connections. */
	virtual bool IsListening(void) const = 0;
};
typedef SharedPtr<cServerHandle> cServerHandlePtr;





class cNetwork
{
public:
	/** Callbacks used for connecting to other servers as a client. */
	class cConnectCallbacks
	{
	public:
		// Force a virtual destructor for all descendants:
		virtual ~cConnectCallbacks() {}

		/** Called when the Connect call succeeds.
		Provides the newly created link that can be used for communication. */
		virtual void OnSuccess(cTCPLink & a_Link) = 0;

		/** Called when the Connect call fails. */
		virtual void OnError(int a_ErrorCode) = 0;
	};
	typedef SharedPtr<cConnectCallbacks> cConnectCallbacksPtr;


	/** Callbacks used when listening for incoming connections as a server. */
	class cListenCallbacks
	{
	public:
		// Force a virtual destructor for all descendants:
		virtual ~cListenCallbacks() {}

		/** Called when the TCP server created with Listen() accepts an incoming connection.
		Provides the newly created Link that can be used for communication. */
		virtual void OnAccepted(cTCPLink & a_Link) = 0;

		/** Called when the socket fails to listen on the specified port. */
		virtual void OnError(int a_ErrorCode, const AString & a_ErrorMsg) = 0;
	};
	typedef SharedPtr<cListenCallbacks> cListenCallbacksPtr;


	/** Callbacks used when resolving names to IPs. */
	class cResolveNameCallbacks
	{
	public:
		// Force a virtual destructor for all descendants:
		virtual ~cResolveNameCallbacks() {}

		/** Called when the hostname is successfully resolved into an IP address.
		May be called multiple times if an address resolves to multiple addresses.
		a_IP may be either an IPv4 or an IPv6 address with their proper formatting. */
		virtual void OnNameResolved(const AString & a_Name, const AString & a_IP) = 0;

		/** Called when an error is encountered while resolving.
		If an error is reported, the OnFinished() callback is not called. */
		virtual void OnError(int a_ErrorCode) = 0;

		/** Called when all the addresses resolved have been reported via the OnNameResolved() callback.
		Only called if there was no error reported. */
		virtual void OnFinished(void) = 0;
	};
	typedef SharedPtr<cResolveNameCallbacks> cResolveNameCallbacksPtr;


	/** Queues a TCP connection to be made to the specified host.
	Calls one the connection callbacks (success, error) when the connection is successfully established, or upon failure.
	The a_LinkCallbacks is passed to the newly created cTCPLink.
	Returns true if queueing was successful, false on failure to queue.
	Note that the return value doesn't report the success of the actual connection; the connection is established asynchronously in the background. */
	static bool Connect(
		const AString & a_Host,
		const UInt16 a_Port,
		cConnectCallbacksPtr a_ConnectCallbacks,
		cTCPLink::cCallbacksPtr a_LinkCallbacks
	);


	/** Opens up the specified port for incoming connections.
	Calls an OnAccepted callback for each incoming connection.
	A cTCPLink with the specified link callbacks is created for each connection.
	Returns a cServerHandle that can be used to query the operation status and close the server. */
	static cServerHandlePtr Listen(
		const UInt16 a_Port,
		cListenCallbacksPtr a_ListenCallbacks,
		cTCPLink::cCallbacksPtr a_LinkCallbacks
	);


	/** Queues a DNS query to resolve the specified hostname to IP address.
	Calls one of the callbacks when the resolving succeeds, or when it fails.
	Returns true if queueing was successful, false if not.
	Note that the return value doesn't report the success of the actual lookup; the lookup happens asynchronously on the background. */
	static bool HostnameToIP(
		const AString & a_Hostname,
		cResolveNameCallbacksPtr a_Callbacks
	);


	/** Queues a DNS query to resolve the specified IP address to a hostname.
	Calls one of the callbacks when the resolving succeeds, or when it fails.
	Returns true if queueing was successful, false if not.
	Note that the return value doesn't report the success of the actual lookup; the lookup happens asynchronously on the background. */
	static bool IPToHostName(
		const AString & a_IP,
		cResolveNameCallbacksPtr a_Callbacks
	);
};