/src/middleware/enet/docs/Tutorial.html

https://bitbucket.org/vivkin/gam3b00bs/ · HTML · 261 lines · 234 code · 26 blank · 1 comment · 0 complexity · 5d3a2b8a91c3196ddf7a7f32f846074b MD5 · raw file 

    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    2. 

  2. <html xmlns="http://www.w3.org/1999/xhtml">
    3. 

  3. <head>
    4. 

  4. <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
    5. 

  5. <title>enet: Tutorial</title>
    6. 

  6. <link href="tabs.css" rel="stylesheet" type="text/css"/>
    7. 

  7. <link href="doxygen.css" rel="stylesheet" type="text/css"/>
    8. 

  8. </head>
    9. 

  9. <body>
    10. 

  10. <!-- Generated by Doxygen 1.7.1 -->
    11. 

  11. <div class="navigation" id="top">
    12. 

  12.   <div class="tabs">
    13. 

  13.     <ul class="tablist">
    14. 

  14.       <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
    15. 

  15.       <li class="current"><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
    16. 

  16.       <li><a href="modules.html"><span>Modules</span></a></li>
    17. 

  17.       <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
    18. 

  18.       <li><a href="files.html"><span>Files</span></a></li>
    19. 

  19.     </ul>
    20. 

  20.   </div>
    21. 

  21. </div>
    22. 

  22. <div class="header">
    23. 

  23.   <div class="headertitle">
    24. 

  24. <h1>Tutorial </h1>  </div>
    25. 

  25. </div>
    26. 

  26. <div class="contents">
    27. 

  27. <p><a class="el" href="Tutorial.html#Initialization">Initialization</a></p>
    28. 

  28. <p><a class="el" href="Tutorial.html#CreateServer">Creating an ENet server</a></p>
    29. 

  29. <p><a class="el" href="Tutorial.html#CreateClient">Creating an ENet client</a></p>
    30. 

  30. <p><a class="el" href="Tutorial.html#ManageHost">Managing an ENet host</a></p>
    31. 

  31. <p><a class="el" href="Tutorial.html#SendingPacket">Sending a packet to an ENet peer</a></p>
    32. 

  32. <p><a class="el" href="Tutorial.html#Disconnecting">Disconnecting an ENet peer</a></p>
    33. 

  33. <p><a class="el" href="Tutorial.html#Connecting">Connecting to an ENet host</a></p>
    34. 

  34. <h2><a class="anchor" id="Initialization"></a>
    35. 

  35. Initialization</h2>
    36. 

  36. <p>You should include the file &lt;<a class="el" href="enet_8h.html" title="ENet public header file.">enet/enet.h</a>&gt; when using ENet. Do not include &lt;<a class="el" href="enet_8h.html" title="ENet public header file.">enet.h</a>&gt; without the directory prefix, as this may cause file name conflicts on some systems.</p>
    37. 

  37. <p>Before using ENet, you must call <a class="el" href="group__global.html#ga67fa85c46a1dc91f968f25fc0637c897" title="Initializes ENet globally.">enet_initialize()</a> to initialize the library. Upon program exit, you should call <a class="el" href="group__global.html#gad62cf417e08a2b98d48572a336f7db25" title="Shuts down ENet globally.">enet_deinitialize()</a> so that the library may clean up any used resources.</p>
    38. 

  38. <div class="fragment"><pre class="fragment"><span class="preprocessor">#include &lt;<a class="code" href="enet_8h.html" title="ENet public header file.">enet/enet.h</a>&gt;</span>
    39. 

  39. 

  40. <span class="keywordtype">int</span> 
    41. 

  41. main (<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> ** argv) 
    42. 

  42. {
    43. 

  43.     <span class="keywordflow">if</span> (<a class="code" href="group__global.html#ga67fa85c46a1dc91f968f25fc0637c897" title="Initializes ENet globally.">enet_initialize</a> () != 0)
    44. 

  44.     {
    45. 

  45.         fprintf (stderr, <span class="stringliteral">&quot;An error occurred while initializing ENet.\n&quot;</span>);
    46. 

  46.         <span class="keywordflow">return</span> EXIT_FAILURE;
    47. 

  47.     }
    48. 

  48.     atexit (<a class="code" href="group__global.html#gad62cf417e08a2b98d48572a336f7db25" title="Shuts down ENet globally.">enet_deinitialize</a>);
    49. 

  49.     ...
    50. 

  50.     ...
    51. 

  51.     ...
    52. 

  52. }
    53. 

  53. </pre></div><h2><a class="anchor" id="CreateServer"></a>
    54. 

  54. Creating an ENet server</h2>
    55. 

  55. <p>Servers in ENet are constructed with <a class="el" href="group__host.html#ga5567a95d7a45521dc9cba93a9066c940" title="Creates a host for communicating to peers.">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>
    56. 

  56. <p>When done with a host, the host may be destroyed with <a class="el" href="group__host.html#gacec1e9a0b528c1f9ce30544d2d5b5b79" title="Destroys the host and all resources associated with it.">enet_host_destroy()</a>. All connected peers to the host will be reset, and the resources used by the host will be freed.</p>
    57. 

  57. <div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetAddress.html" title="Portable internet address structure.">ENetAddress</a> address;
    58. 

  58.     <a class="code" href="struct__ENetHost.html" title="An ENet host for communicating with peers.">ENetHost</a> * server;
    59. 

  59. 

  60.     <span class="comment">/* Bind the server to the default localhost.     */</span>
    61. 

  61.     <span class="comment">/* A specific host address can be specified by   */</span>
    62. 

  62.     <span class="comment">/* enet_address_set_host (&amp; address, &quot;x.x.x.x&quot;); */</span>
    63. 

  63. 

  64.     address.host = ENET_HOST_ANY;
    65. 

  65.     <span class="comment">/* Bind the server to port 1234. */</span>
    66. 

  66.     address.port = 1234;
    67. 

  67. 

  68.     server = <a class="code" href="group__host.html#ga5567a95d7a45521dc9cba93a9066c940" title="Creates a host for communicating to peers.">enet_host_create</a> (&amp; address <span class="comment">/* the address to bind the server host to */</span>, 
    69. 

  69.                                  32      <span class="comment">/* allow up to 32 clients and/or outgoing connections */</span>,
    70. 

  70.                                   2      <span class="comment">/* allow up to 2 channels to be used, 0 and 1 */</span>,
    71. 

  71.                                   0      <span class="comment">/* assume any amount of incoming bandwidth */</span>,
    72. 

  72.                                   0      <span class="comment">/* assume any amount of outgoing bandwidth */</span>);
    73. 

  73.     <span class="keywordflow">if</span> (server == NULL)
    74. 

  74.     {
    75. 

  75.         fprintf (stderr, 
    76. 

  76.                  <span class="stringliteral">&quot;An error occurred while trying to create an ENet server host.\n&quot;</span>);
    77. 

  77.         exit (EXIT_FAILURE);
    78. 

  78.     }
    79. 

  79.     ...
    80. 

  80.     ...
    81. 

  81.     ...
    82. 

  82.     <a class="code" href="group__host.html#gacec1e9a0b528c1f9ce30544d2d5b5b79" title="Destroys the host and all resources associated with it.">enet_host_destroy</a>(server);
    83. 

  83. </pre></div><h2><a class="anchor" id="CreateClient"></a>
    84. 

  84. Creating an ENet client</h2>
    85. 

  85. <p>Clients in ENet are similarly constructed with <a class="el" href="group__host.html#ga5567a95d7a45521dc9cba93a9066c940" title="Creates a host for communicating to peers.">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>
    86. 

  86. <div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetHost.html" title="An ENet host for communicating with peers.">ENetHost</a> * client;
    87. 

  87. 

  88.     client = <a class="code" href="group__host.html#ga5567a95d7a45521dc9cba93a9066c940" title="Creates a host for communicating to peers.">enet_host_create</a> (NULL <span class="comment">/* create a client host */</span>,
    89. 

  89.                 1 <span class="comment">/* only allow 1 outgoing connection */</span>,
    90. 

  90.                 2 <span class="comment">/* allow up 2 channels to be used, 0 and 1 */</span>,
    91. 

  91.                 57600 / 8 <span class="comment">/* 56K modem with 56 Kbps downstream bandwidth */</span>,
    92. 

  92.                 14400 / 8 <span class="comment">/* 56K modem with 14 Kbps upstream bandwidth */</span>);
    93. 

  93. 

  94.     <span class="keywordflow">if</span> (client == NULL)
    95. 

  95.     {
    96. 

  96.         fprintf (stderr, 
    97. 

  97.                  <span class="stringliteral">&quot;An error occurred while trying to create an ENet client host.\n&quot;</span>);
    98. 

  98.         exit (EXIT_FAILURE);
    99. 

  99.     }
    100. 

  100.     ...
    101. 

  101.     ...
    102. 

  102.     ...
    103. 

  103.     <a class="code" href="group__host.html#gacec1e9a0b528c1f9ce30544d2d5b5b79" title="Destroys the host and all resources associated with it.">enet_host_destroy</a>(client);
    104. 

  104. </pre></div><h2><a class="anchor" id="ManageHost"></a>
    105. 

  105. Managing an ENet host</h2>
    106. 

  106. <p>ENet 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#ga6ba501b3ee576e5578c8e6d1694ebd49" title="Waits for events on the host specified and shuttles packets between the host and its peers...">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#ga6ba501b3ee576e5578c8e6d1694ebd49" title="Waits for events on the host specified and shuttles packets between the host and its peers...">enet_host_service()</a> will return immediately if there are no events to dispatch. <a class="el" href="group__host.html#ga6ba501b3ee576e5578c8e6d1694ebd49" title="Waits for events on the host specified and shuttles packets between the host and its peers...">enet_host_service()</a> will return 1 if an event was dispatched within the specified timeout.</p>
    107. 

  107. <p>Currently there are only four types of significant events in ENet:</p>
    108. 

  108. <p>An 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#ga6ba501b3ee576e5578c8e6d1694ebd49" title="Waits for events on the host specified and shuttles packets between the host and its peers...">enet_host_service()</a> will return 0 with this event.</p>
    109. 

  109. <p>An 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>
    110. 

  110. <p>An 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#gab58895376ee4ade8f4e13761a44ba263" title="Destroys the packet and deallocates its data.">enet_packet_destroy()</a> when you are done inspecting its contents.</p>
    111. 

  111. <p>An 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>
    112. 

  112. <div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetEvent.html" title="An ENet event as returned by enet_host_service().">ENetEvent</a> event;
    113. 

  113.     
    114. 

  114.     <span class="comment">/* Wait up to 1000 milliseconds for an event. */</span>
    115. 

  115.     <span class="keywordflow">while</span> (<a class="code" href="group__host.html#ga6ba501b3ee576e5578c8e6d1694ebd49" title="Waits for events on the host specified and shuttles packets between the host and its peers...">enet_host_service</a> (client, &amp; event, 1000) &gt; 0)
    116. 

  116.     {
    117. 

  117.         <span class="keywordflow">switch</span> (event.<a class="code" href="struct__ENetEvent.html#a53cd59a74e46de03e8f4b3fd47822d96" title="type of the event">type</a>)
    118. 

  118.         {
    119. 

  119.         <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#a3cf937b5cf72510493e0a7a2b71d3755aefd9fa36297e41ca4c1cbcfdeb7e4a9d" title="a connection request initiated by enet_host_connect has completed.">ENET_EVENT_TYPE_CONNECT</a>:
    120. 

  120.             printf (<span class="stringliteral">&quot;A new client connected from %x:%u.\n&quot;</span>, 
    121. 

  121.                     event.<a class="code" href="struct__ENetEvent.html#ac991d0db800bc1c70b56ad63f1670140" title="peer that generated a connect, disconnect or receive event">peer</a> -&gt; address.host,
    122. 

  122.                     event.<a class="code" href="struct__ENetEvent.html#ac991d0db800bc1c70b56ad63f1670140" title="peer that generated a connect, disconnect or receive event">peer</a> -&gt; address.port);
    123. 

  123. 

  124.             <span class="comment">/* Store any relevant client information here. */</span>
    125. 

  125.             <span class="keyword">event</span>.peer -&gt; data = <span class="stringliteral">&quot;Client information&quot;</span>;
    126. 

  126. 

  127.             <span class="keywordflow">break</span>;
    128. 

  128. 

  129.         <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#a3cf937b5cf72510493e0a7a2b71d3755a67d928ca38b289db53ec9f56c91c5d9d" title="a packet has been received from a peer.">ENET_EVENT_TYPE_RECEIVE</a>:
    130. 

  130.             printf (<span class="stringliteral">&quot;A packet of length %u containing %s was received from %s on channel %u.\n&quot;</span>,
    131. 

  131.                     event.<a class="code" href="struct__ENetEvent.html#afb6303a5593fce6b9671efbc2ca1b5de" title="packet associated with the event, if appropriate">packet</a> -&gt; dataLength,
    132. 

  132.                     event.<a class="code" href="struct__ENetEvent.html#afb6303a5593fce6b9671efbc2ca1b5de" title="packet associated with the event, if appropriate">packet</a> -&gt; data,
    133. 

  133.                     event.<a class="code" href="struct__ENetEvent.html#ac991d0db800bc1c70b56ad63f1670140" title="peer that generated a connect, disconnect or receive event">peer</a> -&gt; data,
    134. 

  134.                     event.<a class="code" href="struct__ENetEvent.html#a9d82e67a0f26c05de4b39bc839cb36ec" title="channel on the peer that generated the event, if appropriate">channelID</a>);
    135. 

  135. 

  136.             <span class="comment">/* Clean up the packet now that we&#39;re done using it. */</span>
    137. 

  137.             <a class="code" href="group__Packet.html#gab58895376ee4ade8f4e13761a44ba263" title="Destroys the packet and deallocates its data.">enet_packet_destroy</a> (event.<a class="code" href="struct__ENetEvent.html#afb6303a5593fce6b9671efbc2ca1b5de" title="packet associated with the event, if appropriate">packet</a>);
    138. 

  138.             
    139. 

  139.             <span class="keywordflow">break</span>;
    140. 

  140.            
    141. 

  141.         <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#a3cf937b5cf72510493e0a7a2b71d3755a4fa47af84cf901810510aeba077a1c2f" title="a peer has disconnected.">ENET_EVENT_TYPE_DISCONNECT</a>:
    142. 

  142.             printf (<span class="stringliteral">&quot;%s disconected.\n&quot;</span>, event.<a class="code" href="struct__ENetEvent.html#ac991d0db800bc1c70b56ad63f1670140" title="peer that generated a connect, disconnect or receive event">peer</a> -&gt; data);
    143. 

  143. 

  144.             <span class="comment">/* Reset the peer&#39;s client information. */</span>
    145. 

  145. 

  146.             <span class="keyword">event</span>.peer -&gt; data = NULL;
    147. 

  147.         }
    148. 

  148.     }
    149. 

  149.     ...
    150. 

  150.     ...
    151. 

  151.     ...
    152. 

  152. </pre></div><h2><a class="anchor" id="SendingPacket"></a>
    153. 

  153. Sending a packet to an ENet peer</h2>
    154. 

  154. <p>Packets in ENet are created with <a class="el" href="group__Packet.html#gaac61b251aebbf9f5e5e313eca51339ea" title="Creates a packet that may be sent to a peer.">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>
    155. 

  155. <p>Certain flags may also be supplied to <a class="el" href="group__Packet.html#gaac61b251aebbf9f5e5e313eca51339ea" title="Creates a packet that may be sent to a peer.">enet_packet_create()</a> to control various packet features:</p>
    156. 

  156. <p>ENET_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>
    157. 

  157. <p>A packet may be resized (extended or truncated) with <a class="el" href="group__Packet.html#ga0aee7f8c7e2d2c4b64f6d68d930155a8" title="Attempts to resize the data in the packet to length specified in the dataLength parameter.">enet_packet_resize()</a>.</p>
    158. 

  158. <p>A packet is sent to a foreign host with <a class="el" href="group__peer.html#gaf082a0ae58d9c435bed75c7325cf7290" title="Queues a packet to be sent.">enet_peer_send()</a>. <a class="el" href="group__peer.html#gaf082a0ae58d9c435bed75c7325cf7290" title="Queues a packet to be sent.">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#gaf082a0ae58d9c435bed75c7325cf7290" title="Queues a packet to be sent.">enet_peer_send()</a>, ENet will handle its deallocation and <a class="el" href="group__Packet.html#gab58895376ee4ade8f4e13761a44ba263" title="Destroys the packet and deallocates its data.">enet_packet_destroy()</a> should not be used upon it.</p>
    159. 

  159. <p>One may also use <a class="el" href="group__host.html#ga5190a63f78eb0c15bd96cda44bf423c6" title="Queues a packet to be sent to all peers associated with the host.">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#gaf082a0ae58d9c435bed75c7325cf7290" title="Queues a packet to be sent.">enet_peer_send()</a>.</p>
    160. 

  160. <p>Queued packets will be sent on a call to <a class="el" href="group__host.html#ga6ba501b3ee576e5578c8e6d1694ebd49" title="Waits for events on the host specified and shuttles packets between the host and its peers...">enet_host_service()</a>. Alternatively, <a class="el" href="group__host.html#gac8f53bcdbd540043f87e7d59048559fa" title="Sends any queued packets on the host specified to its designated peers.">enet_host_flush()</a> will send out queued packets without dispatching any events.</p>
    161. 

  161. <div class="fragment"><pre class="fragment">    <span class="comment">/* Create a reliable packet of size 7 containing &quot;packet\0&quot; */</span>
    162. 

  162.     <a class="code" href="struct__ENetPacket.html" title="ENet packet structure.">ENetPacket</a> * packet = <a class="code" href="group__Packet.html#gaac61b251aebbf9f5e5e313eca51339ea" title="Creates a packet that may be sent to a peer.">enet_packet_create</a> (<span class="stringliteral">&quot;packet&quot;</span>, 
    163. 

  163.                                               strlen (<span class="stringliteral">&quot;packet&quot;</span>) + 1, 
    164. 

  164.                                               <a class="code" href="enet_8h.html#a9d1fc0ce6da0a057f18bd8b9c762003daab20e7088245ab2ddb7f11dcc9433738" title="packet must be received by the target peer and resend attempts should be made until the packet is del...">ENET_PACKET_FLAG_RELIABLE</a>);
    165. 

  165. 

  166.     <span class="comment">/* Extend the packet so and append the string &quot;foo&quot;, so it now */</span>
    167. 

  167.     <span class="comment">/* contains &quot;packetfoo\0&quot;                                      */</span>
    168. 

  168.     <a class="code" href="group__Packet.html#ga0aee7f8c7e2d2c4b64f6d68d930155a8" title="Attempts to resize the data in the packet to length specified in the dataLength parameter.">enet_packet_resize</a> (packet, strlen (<span class="stringliteral">&quot;packetfoo&quot;</span>) + 1);
    169. 

  169.     strcpy (&amp; packet -&gt; data [strlen (<span class="stringliteral">&quot;packet&quot;</span>)], <span class="stringliteral">&quot;foo&quot;</span>);
    170. 

  170.     
    171. 

  171.     <span class="comment">/* Send the packet to the peer over channel id 0. */</span>
    172. 

  172.     <span class="comment">/* One could also broadcast the packet by         */</span>
    173. 

  173.     <span class="comment">/* enet_host_broadcast (host, 0, packet);         */</span>
    174. 

  174.     <a class="code" href="group__peer.html#gaf082a0ae58d9c435bed75c7325cf7290" title="Queues a packet to be sent.">enet_peer_send</a> (peer, 0, packet);
    175. 

  175.     ...
    176. 

  176.     ...
    177. 

  177.     ...
    178. 

  178.     <span class="comment">/* One could just use enet_host_service() instead. */</span>
    179. 

  179.     <a class="code" href="group__host.html#gac8f53bcdbd540043f87e7d59048559fa" title="Sends any queued packets on the host specified to its designated peers.">enet_host_flush</a> (host);
    180. 

  180. </pre></div><h2><a class="anchor" id="Disconnecting"></a>
    181. 

  181. Disconnecting an ENet peer</h2>
    182. 

  182. <p>Peers may be gently disconnected with <a class="el" href="group__peer.html#ga0e807704b6ecace5004c2cdcfbf813c2" title="Request a disconnection from a peer.">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>
    183. 

  183. <p><a class="el" href="group__peer.html#ga9444dfff9574a7d21dbbdd34385a7d4d" title="Forcefully disconnects a peer.">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>
    184. 

  184. <div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetEvent.html" title="An ENet event as returned by enet_host_service().">ENetEvent</a> event;
    185. 

  185.     
    186. 

  186.     <a class="code" href="group__peer.html#ga0e807704b6ecace5004c2cdcfbf813c2" title="Request a disconnection from a peer.">enet_peer_disconnect</a> (peer, 0);
    187. 

  187. 

  188.     <span class="comment">/* Allow up to 3 seconds for the disconnect to succeed</span>
    189. 

  189. <span class="comment"> and drop any packets received packets.</span>
    190. 

  190. <span class="comment">     */</span>
    191. 

  191.     <span class="keywordflow">while</span> (<a class="code" href="group__host.html#ga6ba501b3ee576e5578c8e6d1694ebd49" title="Waits for events on the host specified and shuttles packets between the host and its peers...">enet_host_service</a> (client, &amp; event, 3000) &gt; 0)
    192. 

  192.     {
    193. 

  193.         <span class="keywordflow">switch</span> (event.<a class="code" href="struct__ENetEvent.html#a53cd59a74e46de03e8f4b3fd47822d96" title="type of the event">type</a>)
    194. 

  194.         {
    195. 

  195.         <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#a3cf937b5cf72510493e0a7a2b71d3755a67d928ca38b289db53ec9f56c91c5d9d" title="a packet has been received from a peer.">ENET_EVENT_TYPE_RECEIVE</a>:
    196. 

  196.             <a class="code" href="group__Packet.html#gab58895376ee4ade8f4e13761a44ba263" title="Destroys the packet and deallocates its data.">enet_packet_destroy</a> (event.<a class="code" href="struct__ENetEvent.html#afb6303a5593fce6b9671efbc2ca1b5de" title="packet associated with the event, if appropriate">packet</a>);
    197. 

  197.             <span class="keywordflow">break</span>;
    198. 

  198. 

  199.         <span class="keywordflow">case</span> <a class="code" href="enet_8h.html#a3cf937b5cf72510493e0a7a2b71d3755a4fa47af84cf901810510aeba077a1c2f" title="a peer has disconnected.">ENET_EVENT_TYPE_DISCONNECT</a>:
    200. 

  200.             puts (<span class="stringliteral">&quot;Disconnection succeeded.&quot;</span>);
    201. 

  201.             <span class="keywordflow">return</span>;
    202. 

  202.         ...
    203. 

  203.         ...
    204. 

  204.         ...
    205. 

  205.         }
    206. 

  206.     }
    207. 

  207.     
    208. 

  208.     <span class="comment">/* We&#39;ve arrived here, so the disconnect attempt didn&#39;t */</span>
    209. 

  209.     <span class="comment">/* succeed yet.  Force the connection down.             */</span>
    210. 

  210.     <a class="code" href="group__peer.html#ga9444dfff9574a7d21dbbdd34385a7d4d" title="Forcefully disconnects a peer.">enet_peer_reset</a> (peer);
    211. 

  211.     ...
    212. 

  212.     ...
    213. 

  213.     ...
    214. 

  214. </pre></div><h2><a class="anchor" id="Connecting"></a>
    215. 

  215. Connecting to an ENet host</h2>
    216. 

  216. <p>A connection to a foreign host is initiated with <a class="el" href="group__host.html#ga23b3ac206326b84f42fa91673f12fca9" title="Initiates a connection to a foreign host.">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>
    217. 

  217. <div class="fragment"><pre class="fragment">    <a class="code" href="struct__ENetAddress.html" title="Portable internet address structure.">ENetAddress</a> address;
    218. 

  218.     <a class="code" href="struct__ENetEvent.html" title="An ENet event as returned by enet_host_service().">ENetEvent</a> event;
    219. 

  219.     <a class="code" href="struct__ENetPeer.html" title="An ENet peer which data packets may be sent or received from.">ENetPeer</a> *peer;
    220. 

  220. 

  221.     <span class="comment">/* Connect to some.server.net:1234. */</span>
    222. 

  222.     <a class="code" href="group__Address.html#ga32a6ae1ed3d7704858f237688e7384ee" title="Attempts to resolve the host named by the parameter hostName and sets the host field in the address p...">enet_address_set_host</a> (&amp; address, <span class="stringliteral">&quot;some.server.net&quot;</span>);
    223. 

  223.     address.port = 1234;
    224. 

  224. 

  225.     <span class="comment">/* Initiate the connection, allocating the two channels 0 and 1. */</span>
    226. 

  226.     peer = <a class="code" href="group__host.html#ga23b3ac206326b84f42fa91673f12fca9" title="Initiates a connection to a foreign host.">enet_host_connect</a> (client, &amp; address, 2, 0);    
    227. 

  227.     
    228. 

  228.     <span class="keywordflow">if</span> (peer == NULL)
    229. 

  229.     {
    230. 

  230.        fprintf (stderr, 
    231. 

  231.                 <span class="stringliteral">&quot;No available peers for initiating an ENet connection.\n&quot;</span>);
    232. 

  232.        exit (EXIT_FAILURE);
    233. 

  233.     }
    234. 

  234.     
    235. 

  235.     <span class="comment">/* Wait up to 5 seconds for the connection attempt to succeed. */</span>
    236. 

  236.     <span class="keywordflow">if</span> (<a class="code" href="group__host.html#ga6ba501b3ee576e5578c8e6d1694ebd49" title="Waits for events on the host specified and shuttles packets between the host and its peers...">enet_host_service</a> (client, &amp; event, 5000) &gt; 0 &amp;&amp;
    237. 

  237.         event.<a class="code" href="struct__ENetEvent.html#a53cd59a74e46de03e8f4b3fd47822d96" title="type of the event">type</a> == <a class="code" href="enet_8h.html#a3cf937b5cf72510493e0a7a2b71d3755aefd9fa36297e41ca4c1cbcfdeb7e4a9d" title="a connection request initiated by enet_host_connect has completed.">ENET_EVENT_TYPE_CONNECT</a>)
    238. 

  238.     {
    239. 

  239.         puts (<span class="stringliteral">&quot;Connection to some.server.net:1234 succeeded.&quot;</span>);
    240. 

  240.         ...
    241. 

  241.         ...
    242. 

  242.         ...
    243. 

  243.     }
    244. 

  244.     <span class="keywordflow">else</span>
    245. 

  245.     {
    246. 

  246.         <span class="comment">/* Either the 5 seconds are up or a disconnect event was */</span>
    247. 

  247.         <span class="comment">/* received. Reset the peer in the event the 5 seconds   */</span>
    248. 

  248.         <span class="comment">/* had run out without any significant event.            */</span>
    249. 

  249.         <a class="code" href="group__peer.html#ga9444dfff9574a7d21dbbdd34385a7d4d" title="Forcefully disconnects a peer.">enet_peer_reset</a> (peer);
    250. 

  250. 

  251.         puts (<span class="stringliteral">&quot;Connection to some.server.net:1234 failed.&quot;</span>);
    252. 

  252.     }
    253. 

  253.     ...
    254. 

  254.     ...
    255. 

  255.     ...
    256. 

  256. </pre></div> </div>
    257. 

  257. <hr class="footer"/><address class="footer"><small>Generated on Wed Feb 9 2011 21:31:05 for enet by&nbsp;
    258. 

  258. <a href="http://www.doxygen.org/index.html">
    259. 

  259. <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
    260. 

  260. </body>
    261. 

  261. </html>
    262.