Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/enet-1.1/docs/html/Tutorial.html @ 14

Last change on this file since 14 was 13, checked in by landauf, 17 years ago

added enet
File size: 22.0 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
3<title>enet: Tutorial</title>
4<link href="doxygen.css" rel="stylesheet" type="text/css">
5<link href="tabs.css" rel="stylesheet" type="text/css">
6</head><body>
7<!-- Generated by Doxygen 1.5.1 -->
8<div class="tabs">
9  <ul>
10    <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
11    <li><a href="modules.html"><span>Modules</span></a></li>
12    <li><a href="classes.html"><span>Data&nbsp;Structures</span></a></li>
13    <li><a href="files.html"><span>Files</span></a></li>
14    <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
15  </ul></div>
16<h1><a class="anchor" name="Tutorial">Tutorial</a></h1><a class="el" href="Tutorial.html#Initialization">Initialization</a><p>
17<a class="el" href="Tutorial.html#CreateServer">Creating an ENet server</a><p>
18<a class="el" href="Tutorial.html#CreateClient">Creating an ENet client</a><p>
19<a class="el" href="Tutorial.html#ManageHost">Managing an ENet host</a><p>
20<a class="el" href="Tutorial.html#SendingPacket">Sending a packet to an ENet peer</a><p>
21<a class="el" href="Tutorial.html#Disconnecting">Disconnecting an ENet peer</a><p>
22<a class="el" href="Tutorial.html#Connecting">Connecting to an ENet host</a><h2><a class="anchor" name="Initialization">
23Initialization</a></h2>
24Before using ENet, you must call <a class="el" href="group__global.html#g67fa85c46a1dc91f968f25fc0637c897">enet_initialize()</a> to initialize the library. Upon program exit, you should call <a class="el" href="group__global.html#gd62cf417e08a2b98d48572a336f7db25">enet_deinitialize()</a> so that the library may clean up any used resources.<p>
25<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> 
26main (<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> ** argv)
27{
28    <span class="keywordflow">if</span> (<a class="code" href="group__global.html#g67fa85c46a1dc91f968f25fc0637c897">enet_initialize</a> () != 0)
29    {
30        fprintf (stderr, <span class="stringliteral">"An error occurred while initializing ENet.\n"</span>);
31        <span class="keywordflow">return</span> EXIT_FAILURE;
32    }
33    atexit (<a class="code" href="group__global.html#gd62cf417e08a2b98d48572a336f7db25">enet_deinitialize</a>);
34    ...
35    ...
36    ...
37}
38</pre></div><h2><a class="anchor" name="CreateServer">
39Creating an ENet server</a></h2>
40Servers in ENet are constructed with <a class="el" href="group__host.html#g929df1baa1662e1eb0ae89af9ee3b339">enet_host_create()</a>. You must specify an address on which to receive data and new connections, as well as the maximum allowable numbers of connected peers. You may optionally specify the incoming and outgoing bandwidth of the server in bytes per second so that ENet may try to statically manage bandwidth resources among connected peers in addition to its dynamic throttling algorithm; specifying 0 for these two options will cause ENet to rely entirely upon its dynamic throttling algorithm to manage bandwidth.<p>
41When done with a host, the host may be destroyed with <a class="el" href="group__host.html#gcec1e9a0b528c1f9ce30544d2d5b5b79">enet_host_destroy()</a>. All connected peers to the host will be reset, and the resources used by the host will be freed.<p>
42<div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetAddress.html">ENetAddress</a> address;
43    <a class="code" href="struct__ENetHost.html">ENetHost</a> * server;
44
45    <span class="comment">/* Bind the server to the default localhost.     */</span>
46    <span class="comment">/* A specific host address can be specified by   */</span>
47    <span class="comment">/* enet_address_set_host (&amp; address, "x.x.x.x"); */</span>
48
49    address.<a class="code" href="struct__ENetAddress.html#b4a3f4fe53031a0ea366a5e8c4c04b20">host</a> = <a class="code" href="enet_8h.html#06fc87d81c62e9abb8790b6e5713c55b3d8d24eeb6e426826e88540d7c87d036">ENET_HOST_ANY</a>;
50    <span class="comment">/* Bind the server to port 1234. */</span>
51    address.<a class="code" href="struct__ENetAddress.html#d0f4850b0e76550370be06eee67bbc54">port</a> = 1234;
52
53    server = <a class="code" href="group__host.html#g929df1baa1662e1eb0ae89af9ee3b339">enet_host_create</a> (&amp; address <span class="comment">/* the address to bind the server host to */</span>,
54                                 32      <span class="comment">/* allow up to 32 clients and/or outgoing connections */</span>,
55                                  0      <span class="comment">/* assume any amount of incoming bandwidth */</span>,
56                                  0      <span class="comment">/* assume any amount of outgoing bandwidth */</span>);
57    <span class="keywordflow">if</span> (server == NULL)
58    {
59        fprintf (stderr,
60                 <span class="stringliteral">"An error occurred while trying to create an ENet server host.\n"</span>);
61        exit (EXIT_FAILURE);
62    }
63    ...
64    ...
65    ...
66    <a class="code" href="group__host.html#gcec1e9a0b528c1f9ce30544d2d5b5b79">enet_host_destroy</a>(server);
67</pre></div><h2><a class="anchor" name="CreateClient">
68Creating an ENet client</a></h2>
69Clients in ENet are similarly constructed with <a class="el" href="group__host.html#g929df1baa1662e1eb0ae89af9ee3b339">enet_host_create()</a> when no address is specified to bind the host to. Bandwidth may be specified for the client host as in the above example. The peer count controls the maximum number of connections to other server hosts that may be simultaneously open.<p>
70<div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetHost.html">ENetHost</a> * client;
71
72    client = <a class="code" href="group__host.html#g929df1baa1662e1eb0ae89af9ee3b339">enet_host_create</a> (NULL <span class="comment">/* create a client host */</span>,
73                1 <span class="comment">/* only allow 1 outgoing connection */</span>,
74                57600 / 8 <span class="comment">/* 56K modem with 56 Kbps downstream bandwidth */</span>,
75                14400 / 8 <span class="comment">/* 56K modem with 14 Kbps upstream bandwidth */</span>);
76
77    <span class="keywordflow">if</span> (client == NULL)
78    {
79        fprintf (stderr,
80                 <span class="stringliteral">"An error occurred while trying to create an ENet client host.\n"</span>);
81        exit (EXIT_FAILURE);
82    }
83    ...
84    ...
85    ...
86    <a class="code" href="group__host.html#gcec1e9a0b528c1f9ce30544d2d5b5b79">enet_host_destroy</a>(client);
87</pre></div><h2><a class="anchor" name="ManageHost">
88Managing an ENet host</a></h2>
89ENet uses a polled event model to notify the programmer of significant events. ENet hosts are polled for events with <a class="el" href="group__host.html#g6ba501b3ee576e5578c8e6d1694ebd49">enet_host_service()</a>, where an optional timeout value in milliseconds may be specified to control how long ENet will poll; if a timeout of 0 is specified, <a class="el" href="group__host.html#g6ba501b3ee576e5578c8e6d1694ebd49">enet_host_service()</a> will return immediately if there are no events to dispatch. <a class="el" href="group__host.html#g6ba501b3ee576e5578c8e6d1694ebd49">enet_host_service()</a> will return 1 if an event was dispatched within the specified timeout.<p>
90Currently there are only four types of significant events in ENet:<p>
91An event of type ENET_EVENT_TYPE_NONE is returned if no event occurred within the specified time limit. <a class="el" href="group__host.html#g6ba501b3ee576e5578c8e6d1694ebd49">enet_host_service()</a> will return 0 with this event.<p>
92An event of type ENET_EVENT_TYPE_CONNECT is returned when either a new client host has connected to the server host or when an attempt to establish a connection with a foreign host has succeeded. Only the "peer" field of the event structure is valid for this event and contains the newly connected peer.<p>
93An event of type ENET_EVENT_TYPE_RECEIVE is returned when a packet is received from a connected peer. The "peer" field contains the peer the packet was received from, "channelID" is the channel on which the packet was sent, and "packet" is the packet that was sent. The packet contained in the "packet" field must be destroyed with <a class="el" href="group__Packet.html#gb58895376ee4ade8f4e13761a44ba263">enet_packet_destroy()</a> when you are done inspecting its contents.<p>
94An event of type ENET_EVENT_TYPE_DISCONNECT is returned when a connected peer has either explicitly disconnected or timed out. Only the "peer" field of the event structure is valid for this event and contains the peer that disconnected. Only the "data" field of the peer is still valid on a disconnect event and must be explicitly reset.<p>
95<div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetEvent.html">ENetEvent</a> event;
96   
97    <span class="comment">/* Wait up to 1000 milliseconds for an event. */</span>
98    <span class="keywordflow">while</span> (<a class="code" href="group__host.html#g6ba501b3ee576e5578c8e6d1694ebd49">enet_host_service</a> (client, &amp; event, 1000) &gt; 0)
99    {
100        <span class="keywordflow">switch</span> (event.<a class="code" href="struct__ENetEvent.html#53cd59a74e46de03e8f4b3fd47822d96">type</a>)
101        {
102        <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#dc5336f0698d4336b587f083d89df414efd9fa36297e41ca4c1cbcfdeb7e4a9d">ENET_EVENT_TYPE_CONNECT</a>:
103            printf (<span class="stringliteral">"A new client connected from %x:%u.\n"</span>,
104                    event.<a class="code" href="struct__ENetEvent.html#c991d0db800bc1c70b56ad63f1670140">peer</a> -&gt; address.<a class="code" href="struct__ENetAddress.html#b4a3f4fe53031a0ea366a5e8c4c04b20">host</a>,
105                    event.<a class="code" href="struct__ENetEvent.html#c991d0db800bc1c70b56ad63f1670140">peer</a> -&gt; address.<a class="code" href="struct__ENetAddress.html#d0f4850b0e76550370be06eee67bbc54">port</a>);
106
107            <span class="comment">/* Store any relevant client information here. */</span>
108            event.<a class="code" href="struct__ENetEvent.html#c991d0db800bc1c70b56ad63f1670140">peer</a> -&gt; data = <span class="stringliteral">"Client information"</span>;
109
110            <span class="keywordflow">break</span>;
111
112        <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#dc5336f0698d4336b587f083d89df41467d928ca38b289db53ec9f56c91c5d9d">ENET_EVENT_TYPE_RECEIVE</a>:
113            printf (<span class="stringliteral">"A packet of length %u containing %s was received from %s on channel %u.\n"</span>,
114                    event.<a class="code" href="struct__ENetEvent.html#fb6303a5593fce6b9671efbc2ca1b5de">packet</a> -&gt; dataLength,
115                    event.<a class="code" href="struct__ENetEvent.html#fb6303a5593fce6b9671efbc2ca1b5de">packet</a> -&gt; data,
116                    event.<a class="code" href="struct__ENetEvent.html#c991d0db800bc1c70b56ad63f1670140">peer</a> -&gt; data,
117                    event.<a class="code" href="struct__ENetEvent.html#9d82e67a0f26c05de4b39bc839cb36ec">channelID</a>);
118
119            <span class="comment">/* Clean up the packet now that we're done using it. */</span>
120            <a class="code" href="group__Packet.html#gb58895376ee4ade8f4e13761a44ba263">enet_packet_destroy</a> (event.<a class="code" href="struct__ENetEvent.html#fb6303a5593fce6b9671efbc2ca1b5de">packet</a>);
121           
122            <span class="keywordflow">break</span>;
123           
124        <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#dc5336f0698d4336b587f083d89df4144fa47af84cf901810510aeba077a1c2f">ENET_EVENT_TYPE_DISCONNECT</a>:
125            printf (<span class="stringliteral">"%s disconected.\n"</span>, event.<a class="code" href="struct__ENetEvent.html#c991d0db800bc1c70b56ad63f1670140">peer</a> -&gt; data);
126
127            <span class="comment">/* Reset the peer's client information. */</span>
128
129            event.<a class="code" href="struct__ENetEvent.html#c991d0db800bc1c70b56ad63f1670140">peer</a> -&gt; data = NULL;
130        }
131    }
132    ...
133    ...
134    ...
135</pre></div><h2><a class="anchor" name="SendingPacket">
136Sending a packet to an ENet peer</a></h2>
137Packets in ENet are created with <a class="el" href="group__Packet.html#gac61b251aebbf9f5e5e313eca51339ea">enet_packet_create()</a>, where the size of the packet must be specified. Optionally, initial data may be specified to copy into the packet.<p>
138Certain flags may also be supplied to <a class="el" href="group__Packet.html#gac61b251aebbf9f5e5e313eca51339ea">enet_packet_create()</a> to control various packet features:<p>
139ENET_PACKET_FLAG_RELIABLE specifies that the packet must use reliable delivery. A reliable packet is guarenteed to be delivered, and a number of retry attempts will be made until an acknowledgement is received from the foreign host the packet is sent to. If a certain number of retry attempts is reached without any acknowledgement, ENet will assume the peer has disconnected and forcefully reset the connection. If this flag is not specified, the packet is assumed an unreliable packet, and no retry attempts will be made nor acknowledgements generated.<p>
140A packet may be resized (extended or truncated) with <a class="el" href="group__Packet.html#g0aee7f8c7e2d2c4b64f6d68d930155a8">enet_packet_resize()</a>.<p>
141A packet is sent to a foreign host with <a class="el" href="group__peer.html#gf082a0ae58d9c435bed75c7325cf7290">enet_peer_send()</a>. <a class="el" href="group__peer.html#gf082a0ae58d9c435bed75c7325cf7290">enet_peer_send()</a> accepts a channel id over which to send the packet to a given peer. Once the packet is handed over to ENet with <a class="el" href="group__peer.html#gf082a0ae58d9c435bed75c7325cf7290">enet_peer_send()</a>, ENet will handle its deallocation and <a class="el" href="group__Packet.html#gb58895376ee4ade8f4e13761a44ba263">enet_packet_destroy()</a> should not be used upon it.<p>
142One may also use <a class="el" href="group__host.html#g5190a63f78eb0c15bd96cda44bf423c6">enet_host_broadcast()</a> to send a packet to all connected peers on a given host over a specified channel id, as with <a class="el" href="group__peer.html#gf082a0ae58d9c435bed75c7325cf7290">enet_peer_send()</a>.<p>
143Queued packets will be sent on a call to <a class="el" href="group__host.html#g6ba501b3ee576e5578c8e6d1694ebd49">enet_host_service()</a>. Alternatively, <a class="el" href="group__host.html#gc8f53bcdbd540043f87e7d59048559fa">enet_host_flush()</a> will send out queued packets without dispatching any events.<p>
144<div class="fragment"><pre class="fragment">    <span class="comment">/* Create a reliable packet of size 7 containing "packet\0" */</span>
145    <a class="code" href="struct__ENetPacket.html">ENetPacket</a> * packet = <a class="code" href="group__Packet.html#gac61b251aebbf9f5e5e313eca51339ea">enet_packet_create</a> (<span class="stringliteral">"packet"</span>,
146                                              strlen (<span class="stringliteral">"packet"</span>) + 1,
147                                              <a class="code" href="enet_8h.html#38c59a481ed607b07d63b7bc3e88ca98ab20e7088245ab2ddb7f11dcc9433738">ENET_PACKET_FLAG_RELIABLE</a>);
148
149    <span class="comment">/* Extend the packet so and append the string "foo", so it now */</span>
150    <span class="comment">/* contains "packetfoo\0"                                      */</span>
151    <a class="code" href="group__Packet.html#g0aee7f8c7e2d2c4b64f6d68d930155a8">enet_packet_resize</a> (packet, strlen (<span class="stringliteral">"packetfoo"</span>) + 1);
152    strcpy (&amp; packet -&gt; data [strlen (<span class="stringliteral">"packet"</span>)], <span class="stringliteral">"foo"</span>);
153   
154    <span class="comment">/* Send the packet to the peer over channel id 0. */</span>
155    <span class="comment">/* One could also broadcast the packet by         */</span>
156    <span class="comment">/* enet_host_broadcast (host, 0, packet);         */</span>
157    <a class="code" href="group__peer.html#gf082a0ae58d9c435bed75c7325cf7290">enet_peer_send</a> (peer, 0, packet);
158    ...
159    ...
160    ...
161    <span class="comment">/* One could just use enet_host_service() instead. */</span>
162    <a class="code" href="group__host.html#gc8f53bcdbd540043f87e7d59048559fa">enet_host_flush</a> (host);
163</pre></div><h2><a class="anchor" name="Disconnecting">
164Disconnecting an ENet peer</a></h2>
165Peers may be gently disconnected with <a class="el" href="group__peer.html#g0e807704b6ecace5004c2cdcfbf813c2">enet_peer_disconnect()</a>. A disconnect request will be sent to the foreign host, and ENet will wait for an acknowledgement from the foreign host before finally disconnecting. An event of type ENET_EVENT_TYPE_DISCONNECT will be generated once the disconnection succeeds. Normally timeouts apply to the disconnect acknowledgement, and so if no acknowledgement is received after a length of time the peer will be forcefully disconnected.<p>
166<a class="el" href="group__peer.html#g9444dfff9574a7d21dbbdd34385a7d4d">enet_peer_reset()</a> will forcefully disconnect a peer. The foreign host will get no notification of a disconnect and will time out on the foreign host. No event is generated.<p>
167<div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetEvent.html">ENetEvent</a> event;
168   
169    <a class="code" href="group__peer.html#g0e807704b6ecace5004c2cdcfbf813c2">enet_peer_disconnect</a> (peer, 0);
170
171    <span class="comment">/* Allow up to 3 seconds for the disconnect to succeed</span>
172<span class="comment"> and drop any packets received packets.</span>
173<span class="comment">     */</span>
174    <span class="keywordflow">while</span> (<a class="code" href="group__host.html#g6ba501b3ee576e5578c8e6d1694ebd49">enet_host_service</a> (client, &amp; event, 3000) &gt; 0)
175    {
176        <span class="keywordflow">switch</span> (event.<a class="code" href="struct__ENetEvent.html#53cd59a74e46de03e8f4b3fd47822d96">type</a>)
177        {
178        <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#dc5336f0698d4336b587f083d89df41467d928ca38b289db53ec9f56c91c5d9d">ENET_EVENT_TYPE_RECEIVE</a>:
179            <a class="code" href="group__Packet.html#gb58895376ee4ade8f4e13761a44ba263">enet_packet_destroy</a> (event.<a class="code" href="struct__ENetEvent.html#fb6303a5593fce6b9671efbc2ca1b5de">packet</a>);
180            <span class="keywordflow">break</span>;
181
182        <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#dc5336f0698d4336b587f083d89df4144fa47af84cf901810510aeba077a1c2f">ENET_EVENT_TYPE_DISCONNECT</a>:
183            puts (<span class="stringliteral">"Disconnection succeeded."</span>);
184            <span class="keywordflow">return</span>;
185        ...
186        ...
187        ...
188        }
189    }
190   
191    <span class="comment">/* We've arrived here, so the disconnect attempt didn't */</span>
192    <span class="comment">/* succeed yet.  Force the connection down.             */</span>
193    <a class="code" href="group__peer.html#g9444dfff9574a7d21dbbdd34385a7d4d">enet_peer_reset</a> (peer);
194    ...
195    ...
196    ...
197</pre></div><h2><a class="anchor" name="Connecting">
198Connecting to an ENet host</a></h2>
199A connection to a foreign host is initiated with <a class="el" href="group__host.html#g04f234142512c08dd86a22b05020bd88">enet_host_connect()</a>. It accepts the address of a foreign host to connect to, and the number of channels that should be allocated for communication. If N channels are allocated for use, their channel ids will be numbered 0 through N-1. A peer representing the connection attempt is returned, or NULL if there were no available peers over which to initiate the connection. When the connection attempt succeeds, an event of type ENET_EVENT_TYPE_CONNECT will be generated. If the connection attempt times out or otherwise fails, an event of type ENET_EVENT_TYPE_DISCONNECT will be generated.<p>
200<div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetAddress.html">ENetAddress</a> address;
201    <a class="code" href="struct__ENetEvent.html">ENetEvent</a> event;
202    <a class="code" href="struct__ENetPeer.html">ENetPeer</a> *peer;
203
204    <span class="comment">/* Connect to some.server.net:1234. */</span>
205    <a class="code" href="group__Address.html#g32a6ae1ed3d7704858f237688e7384ee">enet_address_set_host</a> (&amp; address, <span class="stringliteral">"some.server.net"</span>);
206    address.<a class="code" href="struct__ENetAddress.html#d0f4850b0e76550370be06eee67bbc54">port</a> = 1234;
207
208    <span class="comment">/* Initiate the connection, allocating the two channels 0 and 1. */</span>
209    peer = <a class="code" href="group__host.html#g04f234142512c08dd86a22b05020bd88">enet_host_connect</a> (client, &amp; address, 2);   
210   
211    <span class="keywordflow">if</span> (peer == NULL)
212    {
213       fprintf (stderr,
214                <span class="stringliteral">"No available peers for initiating an ENet connection.\n"</span>);
215       exit (EXIT_FAILURE);
216    }
217   
218    <span class="comment">/* Wait up to 5 seconds for the connection attempt to succeed. */</span>
219    <span class="keywordflow">if</span> (<a class="code" href="group__host.html#g6ba501b3ee576e5578c8e6d1694ebd49">enet_host_service</a> (client, &amp; event, 5000) &gt; 0 &amp;&amp;
220        event.<a class="code" href="struct__ENetEvent.html#53cd59a74e46de03e8f4b3fd47822d96">type</a> == <a class="code" href="enet_8h.html#dc5336f0698d4336b587f083d89df414efd9fa36297e41ca4c1cbcfdeb7e4a9d">ENET_EVENT_TYPE_CONNECT</a>)
221    {
222        puts (<span class="stringliteral">"Connection to some.server.net:1234 succeeded."</span>);
223        ...
224        ...
225        ...
226    }
227    <span class="keywordflow">else</span>
228    {
229        <span class="comment">/* Either the 5 seconds are up or a disconnect event was */</span>
230        <span class="comment">/* received. Reset the peer in the event the 5 seconds   */</span>
231        <span class="comment">/* had run out without any significant event.            */</span>
232        <a class="code" href="group__peer.html#g9444dfff9574a7d21dbbdd34385a7d4d">enet_peer_reset</a> (peer);
233
234        puts (<span class="stringliteral">"Connection to some.server.net:1234 failed."</span>);
235    }
236    ...
237    ...
238    ...
239</pre></div> <hr size="1"><address style="align: right;"><small>Generated on Wed Jun 6 14:33:50 2007 for enet by&nbsp;
240<a href="http://www.doxygen.org/index.html">
241<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.1 </small></address>
242</body>
243</html>
Note: See TracBrowser for help on using the repository browser.