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 */