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