|
1 /* |
|
2 SDL_net: An example cross-platform network library for use with SDL |
|
3 Copyright (C) 1997-2012 Sam Lantinga <slouken@libsdl.org> |
|
4 |
|
5 This software is provided 'as-is', without any express or implied |
|
6 warranty. In no event will the authors be held liable for any damages |
|
7 arising from the use of this software. |
|
8 |
|
9 Permission is granted to anyone to use this software for any purpose, |
|
10 including commercial applications, and to alter it and redistribute it |
|
11 freely, subject to the following restrictions: |
|
12 |
|
13 1. The origin of this software must not be misrepresented; you must not |
|
14 claim that you wrote the original software. If you use this software |
|
15 in a product, an acknowledgment in the product documentation would be |
|
16 appreciated but is not required. |
|
17 2. Altered source versions must be plainly marked as such, and must not be |
|
18 misrepresented as being the original software. |
|
19 3. This notice may not be removed or altered from any source distribution. |
|
20 */ |
|
21 |
|
22 /* $Id$ */ |
|
23 |
|
24 #ifndef _SDL_NET_H |
|
25 #define _SDL_NET_H |
|
26 |
|
27 #include "SDL.h" |
|
28 #include "SDL_endian.h" |
|
29 #include "SDL_version.h" |
|
30 #include "begin_code.h" |
|
31 |
|
32 |
|
33 |
|
34 /* Set up for C function definitions, even when using C++ */ |
|
35 #ifdef __cplusplus |
|
36 extern "C" { |
|
37 #endif |
|
38 |
|
39 /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL |
|
40 */ |
|
41 #define SDL_NET_MAJOR_VERSION 1 |
|
42 #define SDL_NET_MINOR_VERSION 2 |
|
43 #define SDL_NET_PATCHLEVEL 8 |
|
44 |
|
45 /* This macro can be used to fill a version structure with the compile-time |
|
46 * version of the SDL_net library. |
|
47 */ |
|
48 #define SDL_NET_VERSION(X) \ |
|
49 { \ |
|
50 (X)->major = SDL_NET_MAJOR_VERSION; \ |
|
51 (X)->minor = SDL_NET_MINOR_VERSION; \ |
|
52 (X)->patch = SDL_NET_PATCHLEVEL; \ |
|
53 } |
|
54 |
|
55 /* This function gets the version of the dynamically linked SDL_net library. |
|
56 it should NOT be used to fill a version structure, instead you should |
|
57 use the SDL_NET_VERSION() macro. |
|
58 */ |
|
59 extern DECLSPEC const SDL_version * SDLCALL SDLNet_Linked_Version(void); |
|
60 |
|
61 /* Initialize/Cleanup the network API |
|
62 SDL must be initialized before calls to functions in this library, |
|
63 because this library uses utility functions from the SDL library. |
|
64 */ |
|
65 extern DECLSPEC int SDLCALL SDLNet_Init(void); |
|
66 extern DECLSPEC void SDLCALL SDLNet_Quit(void); |
|
67 |
|
68 /***********************************************************************/ |
|
69 /* IPv4 hostname resolution API */ |
|
70 /***********************************************************************/ |
|
71 |
|
72 typedef struct { |
|
73 Uint32 host; /* 32-bit IPv4 host address */ |
|
74 Uint16 port; /* 16-bit protocol port */ |
|
75 } IPaddress; |
|
76 |
|
77 /* Resolve a host name and port to an IP address in network form. |
|
78 If the function succeeds, it will return 0. |
|
79 If the host couldn't be resolved, the host portion of the returned |
|
80 address will be INADDR_NONE, and the function will return -1. |
|
81 If 'host' is NULL, the resolved host will be set to INADDR_ANY. |
|
82 */ |
|
83 #ifndef INADDR_ANY |
|
84 #define INADDR_ANY 0x00000000 |
|
85 #endif |
|
86 #ifndef INADDR_NONE |
|
87 #define INADDR_NONE 0xFFFFFFFF |
|
88 #endif |
|
89 #ifndef INADDR_BROADCAST |
|
90 #define INADDR_BROADCAST 0xFFFFFFFF |
|
91 #endif |
|
92 extern DECLSPEC int SDLCALL SDLNet_ResolveHost(IPaddress *address, const char *host, Uint16 port); |
|
93 |
|
94 /* Resolve an ip address to a host name in canonical form. |
|
95 If the ip couldn't be resolved, this function returns NULL, |
|
96 otherwise a pointer to a static buffer containing the hostname |
|
97 is returned. Note that this function is not thread-safe. |
|
98 */ |
|
99 extern DECLSPEC const char * SDLCALL SDLNet_ResolveIP(const IPaddress *ip); |
|
100 |
|
101 /* Get the addresses of network interfaces on this system. |
|
102 This returns the number of addresses saved in 'addresses' |
|
103 */ |
|
104 extern DECLSPEC int SDLCALL SDLNet_GetLocalAddresses(IPaddress *addresses, int maxcount); |
|
105 |
|
106 /***********************************************************************/ |
|
107 /* TCP network API */ |
|
108 /***********************************************************************/ |
|
109 |
|
110 typedef struct _TCPsocket *TCPsocket; |
|
111 |
|
112 /* Open a TCP network socket |
|
113 If ip.host is INADDR_NONE or INADDR_ANY, this creates a local server |
|
114 socket on the given port, otherwise a TCP connection to the remote |
|
115 host and port is attempted. The address passed in should already be |
|
116 swapped to network byte order (addresses returned from |
|
117 SDLNet_ResolveHost() are already in the correct form). |
|
118 The newly created socket is returned, or NULL if there was an error. |
|
119 */ |
|
120 extern DECLSPEC TCPsocket SDLCALL SDLNet_TCP_Open(IPaddress *ip); |
|
121 |
|
122 /* Accept an incoming connection on the given server socket. |
|
123 The newly created socket is returned, or NULL if there was an error. |
|
124 */ |
|
125 extern DECLSPEC TCPsocket SDLCALL SDLNet_TCP_Accept(TCPsocket server); |
|
126 |
|
127 /* Get the IP address of the remote system associated with the socket. |
|
128 If the socket is a server socket, this function returns NULL. |
|
129 */ |
|
130 extern DECLSPEC IPaddress * SDLCALL SDLNet_TCP_GetPeerAddress(TCPsocket sock); |
|
131 |
|
132 /* Send 'len' bytes of 'data' over the non-server socket 'sock' |
|
133 This function returns the actual amount of data sent. If the return value |
|
134 is less than the amount of data sent, then either the remote connection was |
|
135 closed, or an unknown socket error occurred. |
|
136 */ |
|
137 extern DECLSPEC int SDLCALL SDLNet_TCP_Send(TCPsocket sock, const void *data, |
|
138 int len); |
|
139 |
|
140 /* Receive up to 'maxlen' bytes of data over the non-server socket 'sock', |
|
141 and store them in the buffer pointed to by 'data'. |
|
142 This function returns the actual amount of data received. If the return |
|
143 value is less than or equal to zero, then either the remote connection was |
|
144 closed, or an unknown socket error occurred. |
|
145 */ |
|
146 extern DECLSPEC int SDLCALL SDLNet_TCP_Recv(TCPsocket sock, void *data, int maxlen); |
|
147 |
|
148 /* Close a TCP network socket */ |
|
149 extern DECLSPEC void SDLCALL SDLNet_TCP_Close(TCPsocket sock); |
|
150 |
|
151 |
|
152 /***********************************************************************/ |
|
153 /* UDP network API */ |
|
154 /***********************************************************************/ |
|
155 |
|
156 /* The maximum channels on a a UDP socket */ |
|
157 #define SDLNET_MAX_UDPCHANNELS 32 |
|
158 /* The maximum addresses bound to a single UDP socket channel */ |
|
159 #define SDLNET_MAX_UDPADDRESSES 4 |
|
160 |
|
161 typedef struct _UDPsocket *UDPsocket; |
|
162 typedef struct { |
|
163 int channel; /* The src/dst channel of the packet */ |
|
164 Uint8 *data; /* The packet data */ |
|
165 int len; /* The length of the packet data */ |
|
166 int maxlen; /* The size of the data buffer */ |
|
167 int status; /* packet status after sending */ |
|
168 IPaddress address; /* The source/dest address of an incoming/outgoing packet */ |
|
169 } UDPpacket; |
|
170 |
|
171 /* Allocate/resize/free a single UDP packet 'size' bytes long. |
|
172 The new packet is returned, or NULL if the function ran out of memory. |
|
173 */ |
|
174 extern DECLSPEC UDPpacket * SDLCALL SDLNet_AllocPacket(int size); |
|
175 extern DECLSPEC int SDLCALL SDLNet_ResizePacket(UDPpacket *packet, int newsize); |
|
176 extern DECLSPEC void SDLCALL SDLNet_FreePacket(UDPpacket *packet); |
|
177 |
|
178 /* Allocate/Free a UDP packet vector (array of packets) of 'howmany' packets, |
|
179 each 'size' bytes long. |
|
180 A pointer to the first packet in the array is returned, or NULL if the |
|
181 function ran out of memory. |
|
182 */ |
|
183 extern DECLSPEC UDPpacket ** SDLCALL SDLNet_AllocPacketV(int howmany, int size); |
|
184 extern DECLSPEC void SDLCALL SDLNet_FreePacketV(UDPpacket **packetV); |
|
185 |
|
186 |
|
187 /* Open a UDP network socket |
|
188 If 'port' is non-zero, the UDP socket is bound to a local port. |
|
189 The 'port' should be given in native byte order, but is used |
|
190 internally in network (big endian) byte order, in addresses, etc. |
|
191 This allows other systems to send to this socket via a known port. |
|
192 */ |
|
193 extern DECLSPEC UDPsocket SDLCALL SDLNet_UDP_Open(Uint16 port); |
|
194 |
|
195 /* Set the percentage of simulated packet loss for packets sent on the socket. |
|
196 */ |
|
197 extern DECLSPEC void SDLCALL SDLNet_UDP_SetPacketLoss(UDPsocket sock, int percent); |
|
198 |
|
199 /* Bind the address 'address' to the requested channel on the UDP socket. |
|
200 If the channel is -1, then the first unbound channel will be bound with |
|
201 the given address as it's primary address. |
|
202 If the channel is already bound, this new address will be added to the |
|
203 list of valid source addresses for packets arriving on the channel. |
|
204 If the channel is not already bound, then the address becomes the primary |
|
205 address, to which all outbound packets on the channel are sent. |
|
206 This function returns the channel which was bound, or -1 on error. |
|
207 */ |
|
208 extern DECLSPEC int SDLCALL SDLNet_UDP_Bind(UDPsocket sock, int channel, const IPaddress *address); |
|
209 |
|
210 /* Unbind all addresses from the given channel */ |
|
211 extern DECLSPEC void SDLCALL SDLNet_UDP_Unbind(UDPsocket sock, int channel); |
|
212 |
|
213 /* Get the primary IP address of the remote system associated with the |
|
214 socket and channel. If the channel is -1, then the primary IP port |
|
215 of the UDP socket is returned -- this is only meaningful for sockets |
|
216 opened with a specific port. |
|
217 If the channel is not bound and not -1, this function returns NULL. |
|
218 */ |
|
219 extern DECLSPEC IPaddress * SDLCALL SDLNet_UDP_GetPeerAddress(UDPsocket sock, int channel); |
|
220 |
|
221 /* Send a vector of packets to the the channels specified within the packet. |
|
222 If the channel specified in the packet is -1, the packet will be sent to |
|
223 the address in the 'src' member of the packet. |
|
224 Each packet will be updated with the status of the packet after it has |
|
225 been sent, -1 if the packet send failed. |
|
226 This function returns the number of packets sent. |
|
227 */ |
|
228 extern DECLSPEC int SDLCALL SDLNet_UDP_SendV(UDPsocket sock, UDPpacket **packets, int npackets); |
|
229 |
|
230 /* Send a single packet to the specified channel. |
|
231 If the channel specified in the packet is -1, the packet will be sent to |
|
232 the address in the 'src' member of the packet. |
|
233 The packet will be updated with the status of the packet after it has |
|
234 been sent. |
|
235 This function returns 1 if the packet was sent, or 0 on error. |
|
236 |
|
237 NOTE: |
|
238 The maximum size of the packet is limited by the MTU (Maximum Transfer Unit) |
|
239 of the transport medium. It can be as low as 250 bytes for some PPP links, |
|
240 and as high as 1500 bytes for ethernet. |
|
241 */ |
|
242 extern DECLSPEC int SDLCALL SDLNet_UDP_Send(UDPsocket sock, int channel, UDPpacket *packet); |
|
243 |
|
244 /* Receive a vector of pending packets from the UDP socket. |
|
245 The returned packets contain the source address and the channel they arrived |
|
246 on. If they did not arrive on a bound channel, the the channel will be set |
|
247 to -1. |
|
248 The channels are checked in highest to lowest order, so if an address is |
|
249 bound to multiple channels, the highest channel with the source address |
|
250 bound will be returned. |
|
251 This function returns the number of packets read from the network, or -1 |
|
252 on error. This function does not block, so can return 0 packets pending. |
|
253 */ |
|
254 extern DECLSPEC int SDLCALL SDLNet_UDP_RecvV(UDPsocket sock, UDPpacket **packets); |
|
255 |
|
256 /* Receive a single packet from the UDP socket. |
|
257 The returned packet contains the source address and the channel it arrived |
|
258 on. If it did not arrive on a bound channel, the the channel will be set |
|
259 to -1. |
|
260 The channels are checked in highest to lowest order, so if an address is |
|
261 bound to multiple channels, the highest channel with the source address |
|
262 bound will be returned. |
|
263 This function returns the number of packets read from the network, or -1 |
|
264 on error. This function does not block, so can return 0 packets pending. |
|
265 */ |
|
266 extern DECLSPEC int SDLCALL SDLNet_UDP_Recv(UDPsocket sock, UDPpacket *packet); |
|
267 |
|
268 /* Close a UDP network socket */ |
|
269 extern DECLSPEC void SDLCALL SDLNet_UDP_Close(UDPsocket sock); |
|
270 |
|
271 |
|
272 /***********************************************************************/ |
|
273 /* Hooks for checking sockets for available data */ |
|
274 /***********************************************************************/ |
|
275 |
|
276 typedef struct _SDLNet_SocketSet *SDLNet_SocketSet; |
|
277 |
|
278 /* Any network socket can be safely cast to this socket type */ |
|
279 typedef struct _SDLNet_GenericSocket { |
|
280 int ready; |
|
281 } *SDLNet_GenericSocket; |
|
282 |
|
283 /* Allocate a socket set for use with SDLNet_CheckSockets() |
|
284 This returns a socket set for up to 'maxsockets' sockets, or NULL if |
|
285 the function ran out of memory. |
|
286 */ |
|
287 extern DECLSPEC SDLNet_SocketSet SDLCALL SDLNet_AllocSocketSet(int maxsockets); |
|
288 |
|
289 /* Add a socket to a set of sockets to be checked for available data */ |
|
290 #define SDLNet_TCP_AddSocket(set, sock) \ |
|
291 SDLNet_AddSocket(set, SDL_reinterpret_cast(SDLNet_GenericSocket, sock)) |
|
292 #define SDLNet_UDP_AddSocket(set, sock) \ |
|
293 SDLNet_AddSocket(set, SDL_reinterpret_cast(SDLNet_GenericSocket, sock)) |
|
294 extern DECLSPEC int SDLCALL SDLNet_AddSocket(SDLNet_SocketSet set, SDLNet_GenericSocket sock); |
|
295 |
|
296 /* Remove a socket from a set of sockets to be checked for available data */ |
|
297 #define SDLNet_TCP_DelSocket(set, sock) \ |
|
298 SDLNet_DelSocket(set, SDL_reinterpret_cast(SDLNet_GenericSocket, sock)) |
|
299 #define SDLNet_UDP_DelSocket(set, sock) \ |
|
300 SDLNet_DelSocket(set, SDL_reinterpret_cast(SDLNet_GenericSocket, sock)) |
|
301 extern DECLSPEC int SDLCALL SDLNet_DelSocket(SDLNet_SocketSet set, SDLNet_GenericSocket sock); |
|
302 |
|
303 /* This function checks to see if data is available for reading on the |
|
304 given set of sockets. If 'timeout' is 0, it performs a quick poll, |
|
305 otherwise the function returns when either data is available for |
|
306 reading, or the timeout in milliseconds has elapsed, which ever occurs |
|
307 first. This function returns the number of sockets ready for reading, |
|
308 or -1 if there was an error with the select() system call. |
|
309 */ |
|
310 extern DECLSPEC int SDLCALL SDLNet_CheckSockets(SDLNet_SocketSet set, Uint32 timeout); |
|
311 |
|
312 /* After calling SDLNet_CheckSockets(), you can use this function on a |
|
313 socket that was in the socket set, to find out if data is available |
|
314 for reading. |
|
315 */ |
|
316 #define SDLNet_SocketReady(sock) \ |
|
317 ((sock != NULL) && SDL_reinterpret_cast(SDLNet_GenericSocket, sock)->ready) |
|
318 |
|
319 /* Free a set of sockets allocated by SDL_NetAllocSocketSet() */ |
|
320 extern DECLSPEC void SDLCALL SDLNet_FreeSocketSet(SDLNet_SocketSet set); |
|
321 |
|
322 |
|
323 /***********************************************************************/ |
|
324 /* Platform-independent data conversion functions */ |
|
325 /***********************************************************************/ |
|
326 |
|
327 /* Write a 16/32 bit value to network packet buffer */ |
|
328 extern DECLSPEC void SDLCALL SDLNet_Write16(Uint16 value, void *area); |
|
329 extern DECLSPEC void SDLCALL SDLNet_Write32(Uint32 value, void *area); |
|
330 |
|
331 /* Read a 16/32 bit value from network packet buffer */ |
|
332 extern DECLSPEC Uint16 SDLCALL SDLNet_Read16(void *area); |
|
333 extern DECLSPEC Uint32 SDLCALL SDLNet_Read32(void *area); |
|
334 |
|
335 /***********************************************************************/ |
|
336 /* Error reporting functions */ |
|
337 /***********************************************************************/ |
|
338 |
|
339 /* We'll use SDL's functions for error reporting */ |
|
340 #define SDLNet_SetError SDL_SetError |
|
341 #define SDLNet_GetError SDL_GetError |
|
342 |
|
343 /* I'm eventually going to try to disentangle SDL_net from SDL, thus making |
|
344 SDL_net an independent X-platform networking toolkit. Not today though.... |
|
345 |
|
346 extern no_parse_DECLSPEC void SDLCALL SDLNet_SetError(const char *fmt, ...); |
|
347 extern no_parse_DECLSPEC char * SDLCALL SDLNet_GetError(void); |
|
348 */ |
|
349 |
|
350 |
|
351 /* Inline macro functions to read/write network data */ |
|
352 |
|
353 /* Warning, some systems have data access alignment restrictions */ |
|
354 #if defined(sparc) || defined(mips) |
|
355 #define SDL_DATA_ALIGNED 1 |
|
356 #endif |
|
357 #ifndef SDL_DATA_ALIGNED |
|
358 #define SDL_DATA_ALIGNED 0 |
|
359 #endif |
|
360 |
|
361 /* Write a 16 bit value to network packet buffer */ |
|
362 #if !SDL_DATA_ALIGNED |
|
363 #define SDLNet_Write16(value, areap) \ |
|
364 (*SDL_reinterpret_cast(Uint16 *, areap) = SDL_SwapBE16(value)) |
|
365 #else |
|
366 #if SDL_BYTEORDER == SDL_BIG_ENDIAN |
|
367 #define SDLNet_Write16(value, areap) \ |
|
368 do \ |
|
369 { \ |
|
370 Uint8 *area = SDL_reinterpret_cast(Uint8 *, areap); \ |
|
371 area[0] = (value >> 8) & 0xFF; \ |
|
372 area[1] = value & 0xFF; \ |
|
373 } while ( 0 ) |
|
374 #else |
|
375 #define SDLNet_Write16(value, areap) \ |
|
376 do \ |
|
377 { \ |
|
378 Uint8 *area = SDL_reinterpret_cast(Uint8 *, areap); \ |
|
379 area[1] = (value >> 8) & 0xFF; \ |
|
380 area[0] = value & 0xFF; \ |
|
381 } while ( 0 ) |
|
382 #endif |
|
383 #endif /* !SDL_DATA_ALIGNED */ |
|
384 |
|
385 /* Write a 32 bit value to network packet buffer */ |
|
386 #if !SDL_DATA_ALIGNED |
|
387 #define SDLNet_Write32(value, areap) \ |
|
388 *SDL_reinterpret_cast(Uint32 *, areap) = SDL_SwapBE32(value); |
|
389 #else |
|
390 #if SDL_BYTEORDER == SDL_BIG_ENDIAN |
|
391 #define SDLNet_Write32(value, areap) \ |
|
392 do \ |
|
393 { \ |
|
394 Uint8 *area = SDL_reinterpret_cast(Uint8 *, areap); \ |
|
395 area[0] = (value >> 24) & 0xFF; \ |
|
396 area[1] = (value >> 16) & 0xFF; \ |
|
397 area[2] = (value >> 8) & 0xFF; \ |
|
398 area[3] = value & 0xFF; \ |
|
399 } while ( 0 ) |
|
400 #else |
|
401 #define SDLNet_Write32(value, areap) \ |
|
402 do \ |
|
403 { \ |
|
404 Uint8 *area = SDL_reinterpret_cast(Uint8 *, areap); \ |
|
405 area[3] = (value >> 24) & 0xFF; \ |
|
406 area[2] = (value >> 16) & 0xFF; \ |
|
407 area[1] = (value >> 8) & 0xFF; \ |
|
408 area[0] = value & 0xFF; \ |
|
409 } while ( 0 ) |
|
410 #endif |
|
411 #endif /* !SDL_DATA_ALIGNED */ |
|
412 |
|
413 /* Read a 16 bit value from network packet buffer */ |
|
414 #if !SDL_DATA_ALIGNED |
|
415 #define SDLNet_Read16(areap) \ |
|
416 (SDL_SwapBE16(*SDL_reinterpret_cast(Uint16 *, areap))) |
|
417 #else |
|
418 #if SDL_BYTEORDER == SDL_BIG_ENDIAN |
|
419 #define SDLNet_Read16(areap) \ |
|
420 (((SDL_reinterpret_cast(Uint8 *, areap))[0] << 8) | (SDL_reinterpret_cast(Uint8 *, areap))[1] << 0) |
|
421 #else |
|
422 #define SDLNet_Read16(areap) \ |
|
423 (((SDL_reinterpret_cast(Uint8 *, areap))[1] << 8) | (SDL_reinterpret_cast(Uint8 *, areap))[0] << 0) |
|
424 #endif |
|
425 #endif /* !SDL_DATA_ALIGNED */ |
|
426 |
|
427 /* Read a 32 bit value from network packet buffer */ |
|
428 #if !SDL_DATA_ALIGNED |
|
429 #define SDLNet_Read32(areap) \ |
|
430 (SDL_SwapBE32(*SDL_reinterpret_cast(Uint32 *, areap))) |
|
431 #else |
|
432 #if SDL_BYTEORDER == SDL_BIG_ENDIAN |
|
433 #define SDLNet_Read32(areap) \ |
|
434 (((SDL_reinterpret_cast(Uint8 *, areap))[0] << 24) | ((SDL_reinterpret_cast(Uint8 *, areap))[1] << 16) | \ |
|
435 ((SDL_reinterpret_cast(Uint8 *, areap))[2] << 8) | (SDL_reinterpret_cast(Uint8 *, areap))[3] << 0) |
|
436 #else |
|
437 #define SDLNet_Read32(areap) \ |
|
438 (((SDL_reinterpret_cast(Uint8 *, areap))[3] << 24) | ((SDL_reinterpret_cast(Uint8 *, areap))[2] << 16) | \ |
|
439 ((SDL_reinterpret_cast(Uint8 *, areap))[1] << 8) | (SDL_reinterpret_cast(Uint8 *, areap))[0] << 0) |
|
440 #endif |
|
441 #endif /* !SDL_DATA_ALIGNED */ |
|
442 |
|
443 /* Ends C function definitions when using C++ */ |
|
444 #ifdef __cplusplus |
|
445 } |
|
446 #endif |
|
447 #include "close_code.h" |
|
448 |
|
449 #endif /* _SDL_NET_H */ |