Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/trunk/src/enet/enet.h @ 135

Last change on this file since 135 was 135, checked in by bknecht, 16 years ago

merged back network and xml branch
File size: 17.4 KB
Line 
1/**
2 @file  enet.h
3 @brief ENet public header file
4*/
5#ifndef __ENET_ENET_H__
6#define __ENET_ENET_H__
7
8#ifdef __cplusplus
9extern "C"
10{
11#endif
12
13#include <stdlib.h>
14
15#ifdef WIN32
16#include "enet/win32.h"
17#else
18#include "enet/unix.h"
19#endif
20
21#include "enet/types.h"
22#include "enet/protocol.h"
23#include "enet/list.h"
24#include "enet/callbacks.h"
25
26typedef enum
27{
28   ENET_VERSION = 1
29} ENetVersion;
30
31typedef enum
32{
33   ENET_SOCKET_TYPE_STREAM   = 1,
34   ENET_SOCKET_TYPE_DATAGRAM = 2
35} ENetSocketType;
36
37typedef enum
38{
39   ENET_SOCKET_WAIT_NONE    = 0,
40   ENET_SOCKET_WAIT_SEND    = (1 << 0),
41   ENET_SOCKET_WAIT_RECEIVE = (1 << 1)
42} ENetSocketWait;
43
44enum
45{
46   ENET_HOST_ANY       = 0,            /**< specifies the default server host */
47   ENET_HOST_BROADCAST = 0xFFFFFFFF,   /**< specifies a subnet-wide broadcast */
48
49   ENET_PORT_ANY       = 0             /**< specifies that a port should be automatically chosen */
50};
51
52/**
53 * Portable internet address structure.
54 *
55 * The host must be specified in network byte-order, and the port must be in host
56 * byte-order. The constant ENET_HOST_ANY may be used to specify the default
57 * server host. The constant ENET_HOST_BROADCAST may be used to specify the
58 * broadcast address (255.255.255.255).  This makes sense for enet_host_connect,
59 * but not for enet_host_create.  Once a server responds to a broadcast, the
60 * address is updated from ENET_HOST_BROADCAST to the server's actual IP address.
61 */
62typedef struct _ENetAddress
63{
64   enet_uint32 host;
65   enet_uint16 port;
66} ENetAddress;
67
68/**
69 * Packet flag bit constants.
70 *
71 * The host must be specified in network byte-order, and the port must be in
72 * host byte-order. The constant ENET_HOST_ANY may be used to specify the
73 * default server host.
74 
75   @sa ENetPacket
76*/
77typedef enum
78{
79   /** packet must be received by the target peer and resend attempts should be
80     * made until the packet is delivered */
81   ENET_PACKET_FLAG_RELIABLE    = (1 << 0),
82   /** packet will not be sequenced with other packets
83     * not supported for reliable packets
84     */
85   ENET_PACKET_FLAG_UNSEQUENCED = (1 << 1),
86   /** packet will not allocate data, and user must supply it instead */
87   ENET_PACKET_FLAG_NO_ALLOCATE = (1 << 2)
88} ENetPacketFlag;
89
90struct _ENetPacket;
91typedef void (ENET_CALLBACK * ENetPacketFreeCallback) (struct _ENetPacket *);
92
93/**
94 * ENet packet structure.
95 *
96 * An ENet data packet that may be sent to or received from a peer. The shown
97 * fields should only be read and never modified. The data field contains the
98 * allocated data for the packet. The dataLength fields specifies the length
99 * of the allocated data.  The flags field is either 0 (specifying no flags),
100 * or a bitwise-or of any combination of the following flags:
101 *
102 *    ENET_PACKET_FLAG_RELIABLE - packet must be received by the target peer
103 *    and resend attempts should be made until the packet is delivered
104 *
105 *    ENET_PACKET_FLAG_UNSEQUENCED - packet will not be sequenced with other packets
106 *    (not supported for reliable packets)
107 *
108 *    ENET_PACKET_FLAG_NO_ALLOCATE - packet will not allocate data, and user must supply it instead
109 
110   @sa ENetPacketFlag
111 */
112typedef struct _ENetPacket
113{
114   size_t                   referenceCount;  /**< internal use only */
115   enet_uint32              flags;           /**< bitwise-or of ENetPacketFlag constants */
116   enet_uint8 *             data;            /**< allocated data for packet */
117   size_t                   dataLength;      /**< length of data */
118   ENetPacketFreeCallback   freeCallback;    /**< function to be called when the packet is no longer in use */
119} ENetPacket;
120
121typedef struct _ENetAcknowledgement
122{
123   ENetListNode acknowledgementList;
124   enet_uint32  sentTime;
125   ENetProtocol command;
126} ENetAcknowledgement;
127
128typedef struct _ENetOutgoingCommand
129{
130   ENetListNode outgoingCommandList;
131   enet_uint16  reliableSequenceNumber;
132   enet_uint16  unreliableSequenceNumber;
133   enet_uint32  sentTime;
134   enet_uint32  roundTripTimeout;
135   enet_uint32  roundTripTimeoutLimit;
136   enet_uint32  fragmentOffset;
137   enet_uint16  fragmentLength;
138   ENetProtocol command;
139   ENetPacket * packet;
140} ENetOutgoingCommand;
141
142typedef struct _ENetIncomingCommand
143{ 
144   ENetListNode     incomingCommandList;
145   enet_uint16      reliableSequenceNumber;
146   enet_uint16      unreliableSequenceNumber;
147   ENetProtocol     command;
148   enet_uint32      fragmentCount;
149   enet_uint32      fragmentsRemaining;
150   enet_uint32 *    fragments;
151   ENetPacket *     packet;
152} ENetIncomingCommand;
153
154typedef enum
155{
156   ENET_PEER_STATE_DISCONNECTED                = 0,
157   ENET_PEER_STATE_CONNECTING                  = 1,
158   ENET_PEER_STATE_ACKNOWLEDGING_CONNECT       = 2,
159   ENET_PEER_STATE_CONNECTION_PENDING          = 3,
160   ENET_PEER_STATE_CONNECTION_SUCCEEDED        = 4,
161   ENET_PEER_STATE_CONNECTED                   = 5,
162   ENET_PEER_STATE_DISCONNECT_LATER            = 6,
163   ENET_PEER_STATE_DISCONNECTING               = 7,
164   ENET_PEER_STATE_ACKNOWLEDGING_DISCONNECT    = 8,
165   ENET_PEER_STATE_ZOMBIE                      = 9 
166} ENetPeerState;
167
168#ifndef ENET_BUFFER_MAXIMUM
169#define ENET_BUFFER_MAXIMUM (1 + 2 * ENET_PROTOCOL_MAXIMUM_PACKET_COMMANDS)
170#endif
171
172enum
173{
174   ENET_HOST_RECEIVE_BUFFER_SIZE          = 256 * 1024,
175   ENET_HOST_SEND_BUFFER_SIZE             = 256 * 1024,
176   ENET_HOST_BANDWIDTH_THROTTLE_INTERVAL  = 1000,
177   ENET_HOST_DEFAULT_MTU                  = 1400,
178
179   ENET_PEER_DEFAULT_ROUND_TRIP_TIME      = 500,
180   ENET_PEER_DEFAULT_PACKET_THROTTLE      = 32,
181   ENET_PEER_PACKET_THROTTLE_SCALE        = 32,
182   ENET_PEER_PACKET_THROTTLE_COUNTER      = 7, 
183   ENET_PEER_PACKET_THROTTLE_ACCELERATION = 2,
184   ENET_PEER_PACKET_THROTTLE_DECELERATION = 2,
185   ENET_PEER_PACKET_THROTTLE_INTERVAL     = 5000,
186   ENET_PEER_PACKET_LOSS_SCALE            = (1 << 16),
187   ENET_PEER_PACKET_LOSS_INTERVAL         = 10000,
188   ENET_PEER_WINDOW_SIZE_SCALE            = 64 * 1024,
189   ENET_PEER_TIMEOUT_LIMIT                = 32,
190   ENET_PEER_TIMEOUT_MINIMUM              = 5000,
191   ENET_PEER_TIMEOUT_MAXIMUM              = 30000,
192   ENET_PEER_PING_INTERVAL                = 500,
193   ENET_PEER_UNSEQUENCED_WINDOW_SIZE      = 4 * 32
194};
195
196typedef struct _ENetChannel
197{
198   enet_uint16  outgoingReliableSequenceNumber;
199   enet_uint16  outgoingUnreliableSequenceNumber;
200   enet_uint16  incomingReliableSequenceNumber;
201   enet_uint16  incomingUnreliableSequenceNumber;
202   ENetList     incomingReliableCommands;
203   ENetList     incomingUnreliableCommands;
204} ENetChannel;
205
206/**
207 * An ENet peer which data packets may be sent or received from.
208 *
209 * No fields should be modified unless otherwise specified.
210 */
211typedef struct _ENetPeer
212{ 
213   struct _ENetHost * host;
214   enet_uint16   outgoingPeerID;
215   enet_uint16   incomingPeerID;
216   enet_uint32   sessionID;
217   ENetAddress   address;            /**< Internet address of the peer */
218   void *        data;               /**< Application private data, may be freely modified */
219   ENetPeerState state;
220   ENetChannel * channels;
221   size_t        channelCount;       /**< Number of channels allocated for communication with peer */
222   enet_uint32   incomingBandwidth;  /**< Downstream bandwidth of the client in bytes/second */
223   enet_uint32   outgoingBandwidth;  /**< Upstream bandwidth of the client in bytes/second */
224   enet_uint32   incomingBandwidthThrottleEpoch;
225   enet_uint32   outgoingBandwidthThrottleEpoch;
226   enet_uint32   incomingDataTotal;
227   enet_uint32   outgoingDataTotal;
228   enet_uint32   lastSendTime;
229   enet_uint32   lastReceiveTime;
230   enet_uint32   nextTimeout;
231   enet_uint32   earliestTimeout;
232   enet_uint32   packetLossEpoch;
233   enet_uint32   packetsSent;
234   enet_uint32   packetsLost;
235   enet_uint32   packetLoss;          /**< mean packet loss of reliable packets as a ratio with respect to the constant ENET_PEER_PACKET_LOSS_SCALE */
236   enet_uint32   packetLossVariance;
237   enet_uint32   packetThrottle;
238   enet_uint32   packetThrottleLimit;
239   enet_uint32   packetThrottleCounter;
240   enet_uint32   packetThrottleEpoch;
241   enet_uint32   packetThrottleAcceleration;
242   enet_uint32   packetThrottleDeceleration;
243   enet_uint32   packetThrottleInterval;
244   enet_uint32   lastRoundTripTime;
245   enet_uint32   lowestRoundTripTime;
246   enet_uint32   lastRoundTripTimeVariance;
247   enet_uint32   highestRoundTripTimeVariance;
248   enet_uint32   roundTripTime;            /**< mean round trip time (RTT), in milliseconds, between sending a reliable packet and receiving its acknowledgement */
249   enet_uint32   roundTripTimeVariance;
250   enet_uint16   mtu;
251   enet_uint32   windowSize;
252   enet_uint32   reliableDataInTransit;
253   enet_uint16   outgoingReliableSequenceNumber;
254   ENetList      acknowledgements;
255   ENetList      sentReliableCommands;
256   ENetList      sentUnreliableCommands;
257   ENetList      outgoingReliableCommands;
258   ENetList      outgoingUnreliableCommands;
259   enet_uint16   incomingUnsequencedGroup;
260   enet_uint16   outgoingUnsequencedGroup;
261   enet_uint32   unsequencedWindow [ENET_PEER_UNSEQUENCED_WINDOW_SIZE / 32]; 
262   enet_uint32   disconnectData;
263} ENetPeer;
264
265/** An ENet host for communicating with peers.
266  *
267  * No fields should be modified.
268
269    @sa enet_host_create()
270    @sa enet_host_destroy()
271    @sa enet_host_connect()
272    @sa enet_host_service()
273    @sa enet_host_flush()
274    @sa enet_host_broadcast()
275    @sa enet_host_bandwidth_limit()
276    @sa enet_host_bandwidth_throttle()
277  */
278typedef struct _ENetHost
279{
280   ENetSocket         socket;
281   ENetAddress        address;                     /**< Internet address of the host */
282   enet_uint32        incomingBandwidth;           /**< downstream bandwidth of the host */
283   enet_uint32        outgoingBandwidth;           /**< upstream bandwidth of the host */
284   enet_uint32        bandwidthThrottleEpoch;
285   enet_uint32        mtu;
286   int                recalculateBandwidthLimits;
287   ENetPeer *         peers;                       /**< array of peers allocated for this host */
288   size_t             peerCount;                   /**< number of peers allocated for this host */
289   ENetPeer *         lastServicedPeer;
290   int                continueSending;
291   size_t             packetSize;
292   enet_uint16        headerFlags;
293   ENetProtocol       commands [ENET_PROTOCOL_MAXIMUM_PACKET_COMMANDS];
294   size_t             commandCount;
295   ENetBuffer         buffers [ENET_BUFFER_MAXIMUM];
296   size_t             bufferCount;
297   ENetAddress        receivedAddress;
298   enet_uint8         receivedData [ENET_PROTOCOL_MAXIMUM_MTU];
299   size_t             receivedDataLength;
300} ENetHost;
301
302/**
303 * An ENet event type, as specified in @ref ENetEvent.
304 */
305typedef enum
306{
307   /** no event occurred within the specified time limit */
308   ENET_EVENT_TYPE_NONE       = 0, 
309
310   /** a connection request initiated by enet_host_connect has completed. 
311     * The peer field contains the peer which successfully connected.
312     */
313   ENET_EVENT_TYPE_CONNECT    = 1, 
314
315   /** a peer has disconnected.  This event is generated on a successful
316     * completion of a disconnect initiated by enet_pper_disconnect, if
317     * a peer has timed out, or if a connection request intialized by
318     * enet_host_connect has timed out.  The peer field contains the peer
319     * which disconnected. The data field contains user supplied data
320     * describing the disconnection, or 0, if none is available.
321     */
322   ENET_EVENT_TYPE_DISCONNECT = 2, 
323
324   /** a packet has been received from a peer.  The peer field specifies the
325     * peer which sent the packet.  The channelID field specifies the channel
326     * number upon which the packet was received.  The packet field contains
327     * the packet that was received; this packet must be destroyed with
328     * enet_packet_destroy after use.
329     */
330   ENET_EVENT_TYPE_RECEIVE    = 3
331} ENetEventType;
332
333/**
334 * An ENet event as returned by enet_host_service().
335   
336   @sa enet_host_service
337 */
338typedef struct _ENetEvent
339{
340   ENetEventType        type;      /**< type of the event */
341   ENetPeer *           peer;      /**< peer that generated a connect, disconnect or receive event */
342   enet_uint8           channelID; /**< channel on the peer that generated the event, if appropriate */
343   enet_uint32          data;      /**< data associated with the event, if appropriate */
344   ENetPacket *         packet;    /**< packet associated with the event, if appropriate */
345} ENetEvent;
346
347/** @defgroup global ENet global functions
348    @{
349*/
350
351/**
352  Initializes ENet globally.  Must be called prior to using any functions in
353  ENet.
354  @returns 0 on success, < 0 on failure
355*/
356ENET_API int enet_initialize (void);
357
358/**
359  Initializes ENet globally and supplies user-overridden callbacks. Must be called prior to using any functions in ENet. Do not use enet_initialize() if you use this variant.
360
361  @param version the constant ENET_VERSION should be supplied so ENet knows which version of ENetCallbacks struct to use
362  @param inits user-overriden callbacks where any NULL callbacks will use ENet's defaults
363  @returns 0 on success, < 0 on failure
364*/
365ENET_API int enet_initialize_with_callbacks (ENetVersion version, const ENetCallbacks * inits);
366
367/**
368  Shuts down ENet globally.  Should be called when a program that has
369  initialized ENet exits.
370*/
371ENET_API void enet_deinitialize (void);
372
373/** @} */
374
375/** @defgroup private ENet private implementation functions */
376
377/**
378  Returns the wall-time in milliseconds.  Its initial value is unspecified
379  unless otherwise set.
380  */
381ENET_API enet_uint32 enet_time_get (void);
382/**
383  Sets the current wall-time in milliseconds.
384  */
385ENET_API void enet_time_set (enet_uint32);
386
387/** @defgroup socket ENet socket functions
388    @{
389*/
390ENET_API ENetSocket enet_socket_create (ENetSocketType, const ENetAddress *);
391ENET_API ENetSocket enet_socket_accept (ENetSocket, ENetAddress *);
392ENET_API int        enet_socket_connect (ENetSocket, const ENetAddress *);
393ENET_API int        enet_socket_send (ENetSocket, const ENetAddress *, const ENetBuffer *, size_t);
394ENET_API int        enet_socket_receive (ENetSocket, ENetAddress *, ENetBuffer *, size_t);
395ENET_API int        enet_socket_wait (ENetSocket, enet_uint32 *, enet_uint32);
396ENET_API void       enet_socket_destroy (ENetSocket);
397
398/** @} */
399
400/** @defgroup Address ENet address functions
401    @{
402*/
403/** Attempts to resolve the host named by the parameter hostName and sets
404    the host field in the address parameter if successful.
405    @param address destination to store resolved address
406    @param hostName host name to lookup
407    @retval 0 on success
408    @retval < 0 on failure
409    @returns the address of the given hostName in address on success
410*/
411ENET_API int enet_address_set_host (ENetAddress * address, const char * hostName);
412
413/** Gives the printable form of the ip address specified in the address parameter.
414    @param address    address printed
415    @param hostName   destination for name, must not be NULL
416    @param nameLength maximum length of hostName.
417    @returns the null-terminated name of the host in hostName on success
418    @retval 0 on success
419    @retval < 0 on failure
420*/
421ENET_API int enet_address_get_host_ip (const ENetAddress * address, char * hostName, size_t nameLength);
422
423/** Attempts to do a reverse lookup of the host field in the address parameter.
424    @param address    address used for reverse lookup
425    @param hostName   destination for name, must not be NULL
426    @param nameLength maximum length of hostName.
427    @returns the null-terminated name of the host in hostName on success
428    @retval 0 on success
429    @retval < 0 on failure
430*/
431ENET_API int enet_address_get_host (const ENetAddress * address, char * hostName, size_t nameLength);
432
433/** @} */
434
435ENET_API ENetPacket * enet_packet_create (const void *, size_t, enet_uint32);
436ENET_API void         enet_packet_destroy (ENetPacket *);
437ENET_API int          enet_packet_resize  (ENetPacket *, size_t);
438extern enet_uint32    enet_crc32 (const ENetBuffer *, size_t);
439               
440ENET_API ENetHost * enet_host_create (const ENetAddress *, size_t, enet_uint32, enet_uint32);
441ENET_API void       enet_host_destroy (ENetHost *);
442ENET_API ENetPeer * enet_host_connect (ENetHost *, const ENetAddress *, size_t);
443ENET_API int        enet_host_service (ENetHost *, ENetEvent *, enet_uint32);
444ENET_API void       enet_host_flush (ENetHost *);
445ENET_API void       enet_host_broadcast (ENetHost *, enet_uint8, ENetPacket *);
446ENET_API void       enet_host_bandwidth_limit (ENetHost *, enet_uint32, enet_uint32);
447extern   void       enet_host_bandwidth_throttle (ENetHost *);
448
449ENET_API int                 enet_peer_send (ENetPeer *, enet_uint8, ENetPacket *);
450ENET_API ENetPacket *        enet_peer_receive (ENetPeer *, enet_uint8);
451ENET_API void                enet_peer_ping (ENetPeer *);
452ENET_API void                enet_peer_reset (ENetPeer *);
453ENET_API void                enet_peer_disconnect (ENetPeer *, enet_uint32);
454ENET_API void                enet_peer_disconnect_now (ENetPeer *, enet_uint32);
455ENET_API void                enet_peer_disconnect_later (ENetPeer *, enet_uint32);
456ENET_API void                enet_peer_throttle_configure (ENetPeer *, enet_uint32, enet_uint32, enet_uint32);
457extern int                   enet_peer_throttle (ENetPeer *, enet_uint32);
458extern void                  enet_peer_reset_queues (ENetPeer *);
459extern ENetOutgoingCommand * enet_peer_queue_outgoing_command (ENetPeer *, const ENetProtocol *, ENetPacket *, enet_uint32, enet_uint16);
460extern ENetIncomingCommand * enet_peer_queue_incoming_command (ENetPeer *, const ENetProtocol *, ENetPacket *, enet_uint32);
461extern ENetAcknowledgement * enet_peer_queue_acknowledgement (ENetPeer *, const ENetProtocol *, enet_uint16);
462
463extern size_t enet_protocol_command_size (enet_uint8);
464
465#ifdef __cplusplus
466}
467#endif
468
469#endif /* __ENET_ENET_H__ */
470
Note: See TracBrowser for help on using the repository browser.