Debian Codegraph @

Documentation/Overview/network_overview.xml

raw
1 <xml>
2 <head>
3 <title>Network API overview</title>
4 </head>
5 <body>
6
7 <p>This document explains how to write network games with ClanLib's network
8 model:</p>
9
10 <ul>
11 <li>Sockets, low-level sockets wrapped into nice c++ classes.</li>
12 <li>NetSession, a networking engine.</li>
13 <li>NetObjects, dynamic object replication for the networking engine.</li>
14 <li>NetVariables, a object variables serialization system.</li>
15 <li>Browse, system that allows games to register themselves to a browse master.</li>
16 </ul>
17
18 <h3>ClanLib Sockets, low-level sockets</h3>
19
20 <p>The lowest level is <codelink>CL_Socket</codelink>. This is platform independent
21 version of the system level socket functions, encapsulated in a class for your
22 convience. A simple example:</p>
23
24 <code>
25 /* Gets clanlib.org's index.html page: */
26 try
27 {
28 std::string request_msg = "GET index.html HTTP/1.0\n\n";
29 CL_Socket sock(CL_Socket::tcp);
30 sock.connect(CL_IPAddress("clanlib.org", "80"));
31 sock.send(request_msg);
32 while (true)
33 {
34 char buffer[16*1024+1];
35 int received = sock.recv(buffer, 16*1024);
36 if (received == 0) break; // end of stream. server closed connection.
37 buffer[received] = 0;
38 std::cout << buffer;
39 }
40 std::cout << std::endl;
41 }
42 catch (CL_Error err)
43 {
44 std::cout << "Why wont things never work as planned? " << err.message.c_str() << std::endl;
45 }
46 </code>
47
48 <p>The <codelink>CL_BufferedSocket</codelink> class is not completely implemented
49 and should not be used. I'm not even anymore sure it was a good idea and it might
50 be pending for removal.</p>
51
52 <h4>EventTriggers:</h4>
53
54 <p>Additionally to this, <codelink>CL_Socket</codelink> can use the
55 <codelink>CL_EventTrigger</codelink> and <codelink>CL_EventListener</codelink>
56 to wait for socket data. A small example:</p>
57
58 <code>
59 void wait_for_socket_data(CL_Socket &sock, int timeout)
60 {
61 CL_EventTrigger *read_trigger = sock.get_read_trigger();
62 read_trigger->wait(timeout);
63 }
64
65 void wait_for_sockets(std::list<CL_Socket> &sockets, int timeout)
66 {
67 CL_EventListener listener;
68 std::list<CL_Socket>::iterator it;
69 for (it = sockets.begin(); it != sockets.end(); it++)
70 {
71 CL_Socket &sock = *it;
72 listener.add_trigger(sock.get_read_trigger();
73 }
74 listener.wait(timeout);
75 }
76 </code>
77
78 <h4>OutputSources:</h4>
79 <p><codelink>CL_OutputSource_Socket</codelink> is a <codelink>CL_OutputSource</codelink>
80 compatible wrapper for <codelink>CL_Socket</codelink>. It can be mixed with
81 <codelink>CL_Socket</codelink> since the <codelink>CL_Socket</codelink> class reference
82 counts the handle to the system level socket. A small example of its usage:</p>
83
84 <code>
85 void send_init_handshake(CL_Socket &sock)
86 {
87 CL_OutputSource_Socket output(sock);
88
89 // output.set_big_endian_mode(); // ha! as if that actually worked...
90 output.write_string("Yo dude! You've entered the 1337 socket owned by Cl4nL1b");
91
92 output.write_int(42);
93 }
94 </code>
95
96 <p>You will find a similar <codelink>CL_InputSource_Socket</codelink> for
97 reading from sockets.</p>
98
99 <p>That was the lowest level socket support. It doesnt do much except save you
100 from the trouble of setting up some annoying C structs and filling them with
101 data.</p>
102
103 <h3>The ClanLib networking engine</h3>
104
105 <p>ClanLib features a networking engine called NetSession. It is built on top
106 of the lower level socket interface in ClanLib, so its all up to the game
107 developer which level API is prefered. The NetSession engine provides the
108 following core features:</p>
109
110 <ul>
111
112 <li>Single socket firewall & NAT friendly channeling system. It will not use a
113 dozen of ports, forcing firewall admins to open a wide range of ports, and
114 it should work flawlessly through NAT internet connected systems.</li>
115
116 <li>Simple but powerful channel system to seperate different types of network
117 communication in the game.</li>
118
119 <li>Connection oriented stream communication support (like TCP sockets), and
120 connectionless communication (like UDP sockets) support.</li>
121
122 <li>Recognition of players that have left the server and now rejoining it -
123 allowing a game to restore scores for people lagging out of server or for
124 other reason left the server to return again.</li>
125
126 <li>Flexible server/client relationship in a netsession, allowing a game to
127 easilly implement server travelling (often used by mass-multiplayer online
128 game servers). Server travelling means to have a client seamlessly connect
129 to a new server as it reaches the border boundary of the map that a game
130 server controls.</li>
131
132 <li>Threadding model that both give you the option to run everything in one
133 single thread, or to spread things over multiple worker threads.
134 TODO: Explain more whats threaded in clanNetwork</li>
135
136 <li>And most important of all, its simple and easy to understand. Most stuff
137 is done completely automatically. :)</li>
138
139 </ul>
140
141 <h4>CL_NetSession:</h4>
142
143 <p>So what is a CL_NetSession exactly?</p>
144
145 <ol>
146
147 <li>Its a container for computers connected to or from the computer.</li>
148
149 <li>A set of signals being invoked when accepting new computers into the
150 system, leaving the system, and rejoining the system.</li>
151
152 <li>Signals that are being invoked when a new stream connection is made, or a
153 netpacket is received.</li>
154
155 </ol>
156
157 <p>When a netsession is initially constructed, it will not listen for incoming
158 computers on any ports, nor will it connect to any remote system. It can
159 become a server, a client or any kind of combination you prefer.</p>
160
161 <p>There are two ways a new computer can enter a netsession. Either
162 CL_NetSession::start_listen() is called, making it accept connecting
163 computers on the specified port, or CL_NetSession::connect() is called,
164 making the netsession connect to an other computer.</p>
165
166 <p>There is nothing that prevents you from mixing those two calls. Eg. to have
167 a Peer To Peer network model, or to make servers connect to other servers.
168 Its also no problem to make a client connect to two different servers at the
169 same time, or to disconnect from them again.</p>
170
171 <pre>
172 // Connect to a server
173 CL_NetSession netsession("MyGame");
174 CL_NetComputer server = netsession.connect(CL_IPAddress("myserver.coolgames.com", "4322"));
175
176 ...
177
178 // Start a server which listens to incoming connections:
179 CL_NetSession netsession("MyGame");
180 slots.connect(netsession.sig_computer_connected(), this, &Server::on_connect);
181 slots.connect(netsession.sig_computer_disconnected(), this, &Server::on_disconnect);
182 netsession.start_listen("4322");
183
184 ...
185
186 void Server::on_connect(CL_NetComputer &computer)
187 {
188 std::cout << "A computer connected from " << computer.get_address().get_address() << std::endl;;
189 }
190
191 void Server::on_disconnect(CL_NetComputer &computer)
192 {
193 std::cout << "Computer " << computer.get_address().get_address() << "disconnected" << std::endl;
194 }
195 </pre>
196
197 <h4>CL_NetComputer:</h4>
198
199 <p>When a computer enters the system, it is represented by a CL_NetComputer
200 handle. The signal CL_NetSession::sig_computer_connected() is emitted when a
201 new computer enters the system.</p>
202
203 <p>If the incoming computer is already known to the system,
204 CL_NetSession::sig_computer_reconnected() is emitted instead. A reconnecting
205 computer can only be recognized if not all original CL_NetComputer handles
206 to it has been destroyed. This allows the application to control for how
207 long time an earlier computer can be recognized by the system. For instance,
208 if a game wants to remember old computers for ten minutes, it could store
209 the CL_NetComputer handle when being emitted by
210 CL_NetSession::sig_computer_disconnected(). After the 10 minutes timeout, it
211 just need to destroy the instance it kept, and the netsession will forget
212 about the previous connected computer.</p>
213
214 <h4>CL_NetPacket:</h4>
215
216 <p>To send a message to an other computer, the most simple approach is to
217 construct a netpacket, fill it with data, and send it to one or more
218 computers (via CL_NetComputer::send() or CL_NetGroup::send()).</p>
219
220 <pre>
221 CL_NetPacket msg;
222 msg.output.write_string(player->name);
223 msg.output.write_int32(player->x);
224 msg.output.write_int32(player->y);
225 msg.output.write_bool8(player->running);
226 destination_computer.send("Players", msg);
227 </pre>
228
229 <p>This is the connectionless sending approach. The message can be sent
230 reliably (via TCP) or unreliable (via UDP). Netpackets are perfect for short
231 messages where the latency (ping) should be kept at a minimum.</p>
232
233 <p>When sending a netpacket, you have to point out what channel you want to
234 send it to. This allows you to seperate the different types of communication
235 in your application. If a game features a lobby, the messages sent between
236 players in the lobby could use a channel name of "lobby". Player name stuff
237 might be sent to "playerinfo" and so forth.</p>
238
239 <p>The netpacket channel is used when a netpacket is received. For each channel
240 in the application, there exist a signal in CL_NetSession that gets emitted.
241 To hook up a receive function to the eg. the "lobby" channel, use
242 CL_NetSession::sig_netpacket_receive() with "lobby" as the parameter. That
243 will return the signal for that channel.</p>
244
245 <pre>
246 slot = netsession.sig_netpacket_receive("Login").connect(this, &Login::on_netpacket));
247
248 ...
249
250 void Login::on_netpacket(CL_NetPacket &packet, CL_NetComputer &computer)
251 {
252 std::string user = packet.input.read_string();
253 std::string password = packet.input.read_string();
254 ...
255 </pre>
256
257 <h4>CL_NetStream:</h4>
258
259 <p>It is also possible to make connection oriented connections to a computer.
260 This is often practical if there needs to a higher level of communication
261 between the two computers.</p>
262
263 <p>Imagine a game server that just did a map switch. The game supports
264 automatic downloads of map files that are not available on the client. This
265 is easiest implemented with a netstream. The server first has to tell the
266 client about a file, then the client has to check if the file already exist
267 locally, if not, it should report back and ask for the download. Then the
268 server has to start sending the entire file, which may be several megs in
269 size.</p>
270
271 <p>There's a lot of 'ping-pong' communication here, where each end need to know
272 what they talked about earlier. Connectionless communication (netpackets)
273 become very unpleasant and annoying to use in this kind of communication,
274 but with streams its very simple:</p>
275
276 <pre>
277 // Client version:
278 CL_NetStream stream("download channel", server_netcomputer);
279 int num_files = stream.input.read_int32();
280 for (int i=0; i&lt;num_files; i++)
281 {
282 std::string filename = stream.input.read_string();
283 if (file_exist(filename))
284 {
285 stream.output.write_bool8(false); // dont send file.
286 }
287 else
288 {
289 stream.output.write_bool8(true); // send file.
290 download_and_store_file(stream);
291 }
292 }
293 </pre>
294
295 <p>Simple, eh? What's the catch? The catch is that those calls are blocking.
296 The code will stop up and wait for the server to answer, and if the
297 connection is slow, we have to wait for the sends to complete as well.</p>
298
299 <p>The solution to that problem is threadding. Construct a worker thread to do
300 the communcation, and let the main game thread continue its run. Of course
301 this means you'll have to do threadsafe code, but trust me, in most cases
302 its far easier and nice than to start trying to store states between
303 received netpackets.</p>
304
305 <p>When a stream connection is made, CL_NetSession::sig_netstream_connect() is
306 emitted on the receiving computer. ClanNetwork will not create a new thread
307 for you when emitting this function, so if you want to thread your stream
308 communcation, you'll have to create a thread in your slot function yourself.</p>
309
310
311 <h3>NetObjects</h3>
312
313 <p>On top of the netsession network engine, ClanLib provides a system to
314 replicate objects to client machines. This system is called netobjects, and
315 consist of three classes: CL_NetObject_Controller, CL_NetObject_Server and
316 CL_NetObject_Client.</p>
317
318 <p>The idea of the netobjects is that a CL_NetObject_Server object can send
319 messages to a CL_NetObject_Client object, which is present on one or more
320 client machines. These client objects can also send messages back to the
321 server object.</p>
322
323 <p>Netobjects operate over a netsession netpacket channel, which means that
324 both the server and clients need to instantiate a CL_NetObject_Controller
325 object. This object is responsible for receiving messages and dispatch them
326 to the proper netobjects.</p>
327
328 <p>In order to construct a server side netobject, simply construct an instance
329 of CL_NetObject_Server. Notice that the object will NOT immidiately be
330 replicated to clients. This will first happen when you send a message to the
331 clients.</p>
332
333 <p>When a server object sends a message, the receiving client machine's
334 controller will look to see if there exist any CL_NetObject_Client for the
335 object. If there do not, the controller will create a new
336 CL_NetObject_Client object and signal CL_NetController:sig_create_object().</p>
337
338 <p>The application is supposed to hook itself into this signal and read the
339 message received. If the application keeps the CL_NetObject_Client handle
340 around, future messages sent to this object will cause
341 CL_NetObject_Client::sig_received_message() to be emitted. If the
342 application do not keep the handle, or if it later on destroys it, any
343 future messages sent to the object will cause sig_create_object() to be
344 invoked again.</p>
345
346 <p>Let's look at this again. When a server sends an initial message to the
347 client, the client get the opportunity to create a client version of the
348 object. If the game is a 3D shooter, where objects are only replicated to
349 the client when within visible range, it is possible for the client to
350 destroy the object when not visible any more. Next time the object comes
351 within visible range, sig_create_object will be invoked again, and client
352 recreates the object.</p>
353
354 <p>Another example. Our netobject can have different kinds of messages. One of
355 the messages is a "full update", including all information needed to
356 construct the object. Then it has some "position update" messages that only
357 include the new position of the object. Lets assume the first message, the
358 full update, gets lost in package loss. Now the object sends a position
359 update to the client. Since the client never got the original full update,
360 sig_create_object is emitted, and the function do not have the information
361 needed to create the object. The application can use the netobject handle in
362 sig_create_object to send a message back to the server object, and in this
363 message it asks for a full update. No object was created, so we do not keep
364 the netobject handle. When the server receives the message, it sends back a
365 full update, and sig_create_object is again invoked on the client. This time
366 we do have the information needed to replicate, and we construct our object.</p>
367
368 <pre>
369 class ServerObject
370 {
371 int x, y, shield;
372 CL_NetObject_Server netobj;
373 CL_Slot slot;
374
375 ServerObject(CL_NetObject_Controller *controller)
376 : netobj(controller)
377 {
378 slot = netobj.sig_received_message(0).connect(
379 this, &ServerObject::on_received_pos_update);
380 }
381
382 void on_received_pos_update(
383 CL_NetComputer &computer, CL_NetPacket &packet)
384 {
385 x = packet.input.read_int32();
386 y = packet.input.read_int32();
387 }
388
389 void send_update(CL_NetComputer &comp)
390 {
391 CL_NetPacket packet;
392 packet.output.write_int32(x);
393 packet.output.write_int32(y);
394 packet.output.write_int32(shield);
395 netobj.send(comp, 0, packet);
396 }
397 };
398
399 class ClientObject
400 {
401 int x, y;
402 CL_NetObject_Client netobj;
403 CL_Slot slot;
404
405 ClientObject(CL_NetObject_Client &netobj, CL_NetPacket &packet)
406 : netobj(netobj)
407 {
408 slot = netobj.sig_received_message(0).connect(
409 this, &ClientObject::on_received_update);
410
411 on_received_update(packet);
412 }
413
414 void on_received_update(CL_NetPacket &packet)
415 {
416 x = packet.input.read_int32();
417 y = packet.input.read_int32();
418 shield = packet.input.read_int32();
419 }
420
421 void send_pos_update()
422 {
423 CL_NetPacket packet;
424 packet.output.write_int32(x);
425 packet.output.write_int32(y);
426 netobj.send(0, packet);
427 }
428 };
429
430 class ClientWorld
431 {
432 public:
433 CL_NetObject_Controller controller;
434 CL_Slot slot;
435 std::list<ClientObject *> objects;
436
437 ClientWorld(CL_NetSession &netsession)
438 : controller("netobj_channel", netsession)
439 {
440 slot = controller.sig_create_object().connect(
441 this, &ClientWorld::on_create_object);
442 }
443
444 void on_create_object(
445 CL_NetObject_Client &netobj, int msgtype, CL_NetPacket &packet)
446 {
447 if (msgtype != 0)
448 {
449 // not a update message. we can only create object
450 // based on an update message.
451 return;
452 }
453
454 objects.push_back(new ClientObject(netobj, packet));
455 }
456 };
457 </pre>
458
459 </body>
460 </xml>