Using SDL_net

This document is released under the GPL license.

Goal: To show how to use the SDL_net API on the SDL applications on maemo

Target audience: SDL1 developers

Introduction

SDL_net is a portable network library for use with SDL. The port for maemo platform maintains all original functionalities. The SDL_net is is available under the GNU Library General Public License. The API can be found in the SDL_net.h file.

The purpose of this document is to illustrate how to use SDL_net to enable your SDL applications and games to use the networking capabilities of the maemo platform.

Basics of SDL_net

For the complete documentation and demo programs, see http://www.libsdl.org/projects/SDL_net/.

The following sections summarise the complete documentation.

Types

The SDL_net API defines and uses the following types:

Table 1. SDL_net types

Type Description
IPaddress IP address and port number
TCPsocket TCP socket type (opaque)
UDPsocket UDP socket type (opaque)
UDPpacket UDP packet encapsulation
SDLNET_SocketSet Socket set type (opaque)
SDLNET_GenericSocket Generic type for UDP and TCP sockets

Functions

The SDL_net API provides the following functions:

  • Initialisation

    SDLNet_Init:
    int SDLNet_Init()
    Start up SDL_net functionality.

    SDLNet_Quit:
    void SDLNet_Quit()
    Stop SDL_net functionality.

  • Errors

    SDLNet_GetError:
    char *SDLNet_GetError()
    Get the current error string.

  • Data helpers

    SDLNet_Write16
    void SDLNet_Write16(Uint16 value, void *area)
    Put a 16-bit number in the network-ordered data.

    SDLNet_Write32
    void SDLNet_Write32(Uint32 value, void *area)
    Put a 32-bit number in the network-ordered data.

    SDLNet_Read16
    Uint16 SDLNet_Read16(void *area)
    Get a 16-bit number from the network-ordered data.

    SDLNet_Read32
    Uint32 SDLNet_Read32(void *area)
    Get a 32-bit number from the network-ordered data.

  • Name resolution

    The following functions are used to resolve hostnames and numerical IPv4 addresses to each other.



    SDLNet_ResolveHost:
    int SDLNet_ResolveHost(IPaddress *address, char *host, Uint16 port)
    Resolve the string host, and fill in the IP address pointed by the address with the resolved IP and the port number that was passed in through the port.

    SDLNet_ResolveIP:
    char *SDLNet_ResolveIP(IPaddress *address)
    Resolve the IPv4 numeric address in address­>host, and return the hostname.

  • TCP sockets

    The following functions are used to work with TCP sockets. TCP is used with a full connection, whereas UDP is connectionless. TCP also ensures that all packets reach the destination (when possible). TCP also ensures that packets are received in the same order as they were sent.



    SDLNet_TCP_Open:
    TCPsocket SDLNet_TCP_Open(IPaddress *ip)
    Open a TCP client or server socket.

    SDLNet_TCP_Close:
    void SDLNet_TCP_Close(TCPsocket sock)
    Close a TCP socket.

    SDLNet_TCP_Accept:
    TCPsocket SDLNet_TCP_Accept(TCPsocket server)
    Accept a connection on a server socket. This function is non­blocking.

    SDLNet_TCP_GetPeerAddress:
    IPaddress *SDLNet_TCP_GetPeerAddress(TCPsocket sock)
    Get the remote host address and port number.

    SDLNet_TCP_Send:
    int SDLNet_TCP_Send(TCPsocket sock, void *data, int len)
    Send data over a connected socket.

    SDLNet_TCP_Recv:
    int SDLNet_TCP_Recv(TCPsocket sock, void *data, int maxlen)
    Receive data from a connected socket. This function does not wait to receive maximum length of bytes, it can return before the maximum length is reached. This function is blocking.

  • UDP sockets

    The following functions are used to work with UDP Sockets. UDP is connectionless, but can be used as if it is connected, in the sense that you do not have to address every outgoing packet. This is done by binding a socket to remote IP address and port pairs. UDP has no delivery guarantees, each packet has a chance of never getting to the destination. UDP packets can also be received in a different order than they were originally sent.



    SDLNet_UDP_Open:
    UDPsocket SDLNet_UDP_Open(Uint16 port)
    Create a UDP socket. If the port is not 0, the bind is done in this function.

    SDLNet_UDP_Close:
    void SDLNet_UDP_Close(UDPsocket sock)
    Close and free a UDP socket.

    SDLNet_UDP_Bind:
    int SDLNet_UDP_Bind(UDPsocket sock, int channel, IPaddress*address)
    Assign an IP address number to a socket channel.

    SDLNet_UDP_Unbind:
    void SDLNet_UDP_Unbind(UDPsocket sock, int channel)
    Remove all assigned IP addresses from a socket channel.

    SDLNet_UDP_GetPeerAddress:
    IPaddress *SDLNet_UDP_GetPeerAddress(UDPsocket sock, int channel)
    Get an IP address for a socket channel or get the port with which you opened the socket.

    SDLNet_UDP_Send:
    int SDLNet_UDP_Send(UDPsocket sock, int channel, UDPpacket *packet)
    Send a UDP packet.

    SDLNet_UDP_Recv:
    int SDLNet_UDP_Recv(UDPsocket sock, UDPpacket *packet)
    Receive into a UDP packet. This function is non­blocking.

    SDLNet_UDP_SendV:
    int SDLNet_UDP_SendV(UDPsocket sock, UDPpacket **packetV, int npackets)
    Send a UDP packet vector.

    SDLNet_UDP_RecvV:
    int SDLNet_UDP_RecvV(UDPsocket sock, UDPpacket **packetV)
    Receive into a UDP packet vector.

  • UDP packets

    The following functions are used to work with the UDPpacket type. This type is used with UDP sockets to transmit and receive data.

    SDLNet_AllocPacket:
    UDPpacket *SDLNet_AllocPacket(int size)
    Allocate a new UDP packet with a data buffer.

    SDLNet_ResizePacket:
    int SDLNet_ResizePacket(UDPpacket *packet, int size)
    Resize the data buffer in a UDP packet.

    SDLNet_FreePacket:
    void SDLNet_FreePacket(UDPpacket *packet)

    Free a previously allocated UDP packet.

    SDLNet_AllocPacketV:
    UDPpacket **SDLNet_AllocPacketV(int howmany, int size)
    Allocate a vector of UDP packets.

    SDLNet_FreePacketV:
    void SDLNet_FreePacketV(UDPpacket **packetV)
    Free a vector of UDP packets.

  • Socket sets

    The following functions are used to work with multiple sockets. They allow you to determine when a socket has data or a connection waiting to be processed. This is analogous to polling, or the select function.

    SDLNet_AllocSocketSet:
    SDLNet_SocketSet SDLNet_AllocSocketSet(int maxsockets)
    Create a new socket set.

    SDLNet_FreeSocketSet:
    void SDLNet_FreeSocketSet(SDLNet_SocketSet set)
    Free a socket set.

    SDLNet_AddSocket:
    int SDLNet_AddSocket(SDLNet_SocketSet set, SDLNet_GenericSocket sock)
    Add a socket to a socket set.

    SDLNet_DelSocket:
    int SDLNet_DelSocket(SDLNet_SocketSet set, SDLNet_GenericSocket sock)
    Remove a socket from a socket set.

    SDLNet_CheckSockets:
    int SDLNet_CheckSockets(SDLNet_SocketSet set, Uint32 timeout)
    Check and wait for sockets in a set to have activity.

    SDLNet_SocketReady:
    int SDLNet_SocketReady(sock)
    See if a socket has activity.

Observations

When using SDL_net, the UDP sockets are by default configured to send broadcast packets. There is no direct access to the sockets for making extra configurations, such as changing the blocking mode.

SDL_net demos

The demos are simple programs that demonstrate how to work using SDL_net. The README file inside SDL_net_demos.tar.gz explains how to run the demos. The demos demonstrate seven usage possibilities for SDL_net API.

  • The dnr.c demonstrates host name and IP lookup.

  • The tcpserver.c and tcpclient.c demonstrate a TCP message server and client.

  • The tcpmultiserver.c and tcpmulticlient.c demonstrate a TCP chat server that allows multiple clients to connect to it.

  • The tcpmulticlientthreaded.c demonstrates the same functionality as tcpmulticlient.c with SDL_Threads used for all I/O.

  • The tcptimesync.c demonstrates simple TCP reading and writing and time synchronisation in 5 packets.

  • The tcptimesyncserver.c and tcptimesyncclient.c demonstrate a more flexible implementation of tcptimesync.c's server and they also loop until the server decides that the client is in acceptable sync.

  • The udptftpserver.c and udptftpclient.c show an advanced UDP demo with UDP (and only UDP) file transfer server and client not using SDLNet_SocketSet.

SDL_net examples

The following examples illustrate a simple SDL_net initialisation and basic TCP functions.

Simple TCP server: accepts one connection, sends one message for the connected client and finalises itself. Creates a server at localhost, port 9999. 

#include  
#include  
#include "SDL.h" 
#include "SDL_net.h" 
int main() 
{ 
IPaddress server_ip,*client_ip; 
TCPsocket server,client; 
char *message = "You will be disconnected\n"; 
int len; 
Uint32 ipaddr; 
Uint16 port = 9999; 
// initialize SDL 
if(!SDL_Init(0)){ 
           // initialize SDL_net 
        if(SDLNet_Init()==­1){ 
    printf("SDLNet_Init: %s\n",SDLNet_GetError()); 
    exit(0); 
            } 
} else { 
printf("SDL_Init: %s\n",SDL_GetError()); 
exit(0); 
} 
// Resolve the string host, and fill in the IPaddress 
if(SDLNet_ResolveHost(&server_ip,NULL,port)==­1){ 
printf("SDLNet_ResolveHost: %s\n",SDLNet_GetError()); 
exit(0); 
} 
// open the tcp server socket 
server=SDLNet_TCP_Open(&server_ip); 
if(!server){ 
printf("SDLNet_TCP_Open: %s\n",SDLNet_GetError()); 
exit(0); 
} 
while(1){ 
            //try to accept a connection 
            client=SDLNet_TCP_Accept(server); 
            if (client) { 
    // get the clients IP and port number        
                client_ip=SDLNet_TCP_GetPeerAddress(client); 
                if (client_ip) { 
        // print out the clients IP and port number 
        ipaddr=SDL_SwapBE32(client_ip­>host); 
        printf("Accepted a connection from %d.%d.%d.%d port %hu\n", 
        ipaddr>>24, 
        (ipaddr>>16)&0xff, 
        (ipaddr>>8)&0xff, 
        ipaddr&0xff, 
        client_ip­>port); 
                      //send message to client 
        len=SDLNet_TCP_Send(client,message,strlen(message)); 
        if(len < strlen(message)) 
        printf("SDLNet_TCP_Send: %s\n", SDLNet_GetError()); 
                      // close socket        
        SDLNet_TCP_Close(client); 
                      printf("Bye\n"); 
        break; 
                } else { 
    printf("SDLNet_TCP_GetPeerAddress: %s\n",SDLNet_GetError()); 
                } 
            } 
} 
// shutdown SDL_net 
SDLNet_Quit(); 
// shutdown SDL 
SDL_Quit(); 
return(0); 
}

Simple TCP client: connects to the server on localhost, receives one message from it and finalises itself. 


#include  
#include  
#include  
#include "SDL.h" 
#include "SDL_net.h" 
int main(){ 
IPaddress ip; 
TCPsocket sock; 
char message[1024]; 
int len, result; 
Uint16 port = 9999; 
// initialize SDL 
if(!SDL_Init(0)){ 
        // initialize SDL_net 
        if(SDLNet_Init()==­1){ 
      printf("SDLNet_Init: %s\n",SDLNet_GetError()); 
      exit(0); 
        } 
} else { 
printf("SDL_Init: %s\n",SDL_GetError()); 
exit(0); 
} 
// Resolve the argument into an IPaddress type 
if(!SDLNet_ResolveHost(&ip,"localhost",port)){ 
        // open socket 
        sock=SDLNet_TCP_Open(&ip); 
        if(!sock){ 
      printf("SDLNet_TCP_Open: %s\n",SDLNet_GetError()); 
      exit(0); 
        } 
       } else { 
            printf("SDLNet_ResolveHost: %s\n",SDLNet_GetError()); 
     exit(0); 
       } 
       // read the buffer from server 
       len=SDLNet_TCP_Recv(sock, message, 1024); 
if(len) { 
printf("Sending: %.*s\n",len, message); 
} else { 
    printf("SDLNet_TCP_Recv: %s\n",SDLNet_GetError()); 
       } 
SDLNet_TCP_Close(sock); 
SDLNet_Quit(); 
SDL_Quit(); 
return(0); 
}

References

[1] The SDL LIB official site: www.libsdl.org

[2] The complete documentation and demo programs: SDL NET Official site


Improve this page