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
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
// Copyright (C) 2006 Davis E. King (davis@dlib.net)
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_SOCKETS_EXTENSIONs_ABSTRACT_
#ifdef DLIB_SOCKETS_EXTENSIONs_ABSTRACT_
#include <memory>
#include <string>
#include "sockets_kernel_abstract.h"
#include "../error.h"
namespace dlib
{
// ----------------------------------------------------------------------------------------
class invalid_network_address : public dlib::error
{
/*!
WHAT THIS OBJECT REPRESENTS
This is the exception thrown by network_address's constructor if the
input is invalid.
!*/
};
// ----------------------------------------------------------------------------------------
struct network_address
{
/*!
WHAT THIS OBJECT REPRESENTS
This object is simply a container for two things:
- A host machine address which is either an IP address or DNS name
for a machine.
- A port number.
Together, these things define a machine and port on that machine.
!*/
network_address(
);
/*!
ensures
- host_address == ""
- #port == 0
!*/
network_address(
const std::string& full_address
);
/*!
ensures
- interprets full_address as a network address of the form:
host_address:port
and assigns each part into #host_address and #port. For example,
network_address("localhost:80") would result in a network_address
object where host_address was "localhost" and port was 80.
throws
- invalid_network_address
This exception is thrown if the full_address string can't be
interpreted as a valid network address.
!*/
network_address (
const char* full_address
);
/*!
requires
- full_address == a valid pointer to a null terminated string
ensures
- Invoking this constructor is equivalent to performing
network_address(std::string(full_address))
!*/
network_address(
const std::string& host_address_,
const unsigned short port_
);
/*!
ensures
- #host_address == host_address_
- #port == port_
!*/
std::string host_address;
unsigned short port;
};
// ----------------------------------------------------------------------------------------
inline bool operator < (
const network_address& a,
const network_address& b
);
/*!
ensures
- provides a total ordering over network_address objects so you can use them in
the standard associative containers. The ordering is defined such that if
you sorted network addresses they would sort first on the host_address string
and then, for network_address objects with equal host_address, they would
sort on the port number
!*/
inline bool operator== (
const network_address& a,
const network_address& b
);
/*!
ensures
- returns true if a and b contain exactly the same address and false otherwise.
That is, the following must be true for this function to return true:
- a.host_address == b.host_address
- a.port == b.port
Note that this means that two addresses which are logically equivalent but
written differently will not compare equal. For example, suppose example.com
has the IP address 10.1.1.1. Then network_address("10.1.1.1:80") and
network_address("example.com:80") really refer to the same network resource
but will nevertheless not compare equal since.
!*/
inline bool operator != (
const network_address& a,
const network_address& b
);
/*!
ensures
- returns !(a == b)
!*/
// ----------------------------------------------------------------------------------------
void serialize(
const network_address& item,
std::ostream& out
);
/*!
ensures
- provides serialization support
!*/
void deserialize(
network_address& item,
std::istream& in
);
/*!
ensures
- provides deserialization support
!*/
std::ostream& operator<< (
std::ostream& out,
const network_address& item
);
/*!
ensures
- writes the given network_address to the output stream. The format is the
host_address, then a colon, then the port number. So for example:
cout << network_address("localhost", 80);
would print:
localhost:80
- returns #out
!*/
std::istream& operator>> (
std::istream& in,
network_address& item
);
/*!
ensures
- reads a network_address from the given input stream. The expected format is
the same as the one used to print them by the above operator<<() routine.
- returns #in
- if (there is an error reading the network_address) then
- #in.good() == false
!*/
// ----------------------------------------------------------------------------------------
connection* connect (
const std::string& host_or_ip,
unsigned short port
);
/*!
ensures
- returns a connection object that is connected to the given host at the
given port
throws
- dlib::socket_error
This exception is thrown if there is some problem that prevents us from
creating the connection
- std::bad_alloc
!*/
// ----------------------------------------------------------------------------------------
connection* connect (
const network_address& addr
);
/*!
ensures
- returns connect(addr.host_address, addr_port);
!*/
// ----------------------------------------------------------------------------------------
connection* connect (
const std::string& host_or_ip,
unsigned short port,
unsigned long timeout
);
/*!
ensures
- returns a connection object that is connected to the given host at the
given port.
- blocks for at most timeout milliseconds
throws
- dlib::socket_error
This exception is thrown if there is some problem that prevents us from
creating the connection or if timeout milliseconds elapses before the
connect is successful.
- std::bad_alloc
!*/
// ----------------------------------------------------------------------------------------
bool is_ip_address (
std::string ip
);
/*!
ensures
- if (ip is a valid ip address) then
- returns true
- else
- returns false
!*/
// ----------------------------------------------------------------------------------------
void close_gracefully (
connection* con,
unsigned long timeout = 500
);
/*!
requires
- con == a valid pointer to a connection object or 0
ensures
- This function does nothing if con == 0, otherwise it performs the following:
- performs a graceful close of the given connection and if it takes longer
than timeout milliseconds to complete then forces the connection closed.
- Specifically, a graceful close means that the outgoing part of con is
closed (a FIN is sent) and then we wait for the other end to to close
their end of the connection. This way any data still on its way to
the other end of the connection will be received properly.
- This function will block until the graceful close is completed or we
timeout.
- calls "delete con;". Thus con is no longer a valid pointer after this
function has finished.
throws
- std::bad_alloc or dlib::thread_error
If either of these exceptions are thrown con will still be closed via
"delete con;"
!*/
// ----------------------------------------------------------------------------------------
void close_gracefully (
std::unique_ptr<connection>& con,
unsigned long timeout = 500
);
/*!
requires
- con == a valid pointer to a connection object or con.get() == 0
ensures
- This function does nothing if con.get() == 0, otherwise it performs the
following:
- performs a graceful close of the given connection and if it takes longer
than timeout milliseconds to complete then forces the connection closed.
- Specifically, a graceful close means that the outgoing part of con is
closed (a FIN is sent) and then we wait for the other end to to close
their end of the connection. This way any data still on its way to
the other end of the connection will be received properly.
- This function will block until the graceful close is completed or we
timeout.
- #con.get() == 0. Thus con is no longer a valid pointer after this
function has finished.
throws
- std::bad_alloc or dlib::thread_error
If either of these exceptions are thrown con will still be closed and
deleted (i.e. #con.get() == 0).
!*/
// ----------------------------------------------------------------------------------------
}
#endif // DLIB_SOCKETS_EXTENSIONs_ABSTRACT_
|
