SDL_net 1.2.4

1. Overview

The README from the SDL_net distribution

2. Getting Started

Using SDL_net

3. Functions		Functions supported by the SDL_net API
4. Types		Types used with the SDL_net API
5. Defines		Defined values/macros in the SDL_net API

6. Glossary

Terms used in this document

Index

Index of selected words

1. Overview

I am currently, as I write this document, a programmer for Raytheon. There I do all sorts of communications, network, GUI, and other general programming tasks in C/C++ on the Solaris and sometimes Linux Operating Systems. I have been programming network code at work and in my free time for about 8 years. I find there is always more to learn about network coding, but the rewards for making something comunicate over what can only be called the most chaotic channel of information transfer are sometimes to much fun to ignore. I have coded only a few things in SDL_net that I would call complete projects. However SDL_net does make network coding easier and more portable than anything I could code using just plain BSD sockets. I was happy that I could finally base my code on something that is portable and small enough to be unintrusive. SDL_net does sometimes seem to oversimplify some things, but in the end I found that if I couldn't do it in SDL_net then perhaps I'm not doing something that is worthwhile. Of course I have and will continue to do things that are not so worthwhile perhaps, using SDL_net. Like a Web Server library, and an IRC client library. But I still enjoy making them anyway! So if you are making a game, or doing a school project, or even making a no-fun application, SDL_net is a viable choice in my opinion for almost any of these tasks. If you are interested in multicast and non-TCP/IPv4 networking then SDL_net is not the right thing for you. Everyone else, please make more network games that are fun to play, and portable enough that more people are out there to play with. I, meanwhile, will continue writting documentation and applications and games that will likely become vapourware before they even see the light of day, but I'll be having fun the whole time.

Feel free to contact me: This e-mail address is being protected from spambots. You need JavaScript enabled to view it

I am also usually on IRC at irc.freenode.net in the #SDL channel as LIM

This is the README in the SDL_net source archive.

You may want to look at
Beej's Guide to Network Programming, which explains network programming using BSD sockets. You can apply the knowledge from there while using SDL_net.

And here's a bit of humor for you to look at as you deal with networking terms.

2. Getting Started

This assumes you have gotten SDL_net and installed it on your system. SDL_net has an INSTALL document in the source distribution to help you get it compiled and installed.

Generally, installation consists of:

./configure
make
make install

You may also want to look at some demonstration code which may be downloaded from:
http://jcatki.no-ip.org/SDL_net/

2.1 Includes		The include files to use for SDL_net
2.2 Compiling		Using the SDL_net library and header file.

2.1 Includes

To use SDL_net functions in a C/C++ source code file, you must use the SDL_net.h include file:

  #include "SDL_net.h"

2.2 Compiling

To link with SDL_net you should use sdl-config to get the required SDL compilation options. After that, compiling with SDL_net is quite easy.
Note: Some systems may not have the SDL_net library and include file in the same place as the SDL library and includes are located, in that case you will need to add more -I and -L paths to these command lines.

  cc -c `sdl-config --cflags` mysource.c

  cc -o myprogram mysource.o `sdl-config --libs` -lSDL_net

Now myprogram is ready to run.

3. Functions

These are the functions in the SDL_net API.

3.1 General		API activation
3.2 Name Resolution		Hostname and numeric IP lookup (IPaddress functions)
3.3 TCP Sockets		Working with TCP connections
3.4 UDP Sockets		Working with UDP semi-connections
3.5 UDP Packets		Working with the UDPpacket type
3.6 Socket Sets		Working on demand with sockets

3.1 General

These functions are useful, as they are the only/best ways to work with SDL_net.

Activation

3.1.1 SDLNet_Init		Start up SDL_net functionality
3.1.2 SDLNet_Quit		Stop SDL_net functionality

Errors

3.1.3 SDLNet_GetError

Get the current error string

Data Helpers

3.1.4 SDLNet_Write16		Put a 16bit number in network ordered data
3.1.5 SDLNet_Write32		Put a 32bit number in network ordered data
3.1.6 SDLNet_Read16		Get a 16bit number from network ordered data
3.1.7 SDLNet_Read32		Get a 32bit number from network ordered data

3.1.1 SDLNet_Init

int SDLNet_Init()

Initialize the network API.
This must be called before using other functions in this library.
SDL must be initialized before this call.

Returns: 0 on success, -1 on errors

if(SDL_Init(0)==-1) {
    printf("SDL_Init: %s\n", SDL_GetError());
    exit(1);
}
if(SDLNet_Init()==-1) {
    printf("SDLNet_Init: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.1.2 SDLNet_Quit

3.1.2 SDLNet_Quit

void SDLNet_Quit()

Shutdown and cleanup the network API.
After calling this all sockets are closed, and the SDL_net functions should not be used. You may, of course, use SDLNet_Init to use the functionality again.

SDLNet_Quit();
// you could SDL_Quit(); here...or not.

See Also:
3.1.1 SDLNet_Init

3.1.3 SDLNet_GetError

char *SDLNet_GetError()

This is the same as SDL_GetError, which returns the last error set as a string which you may use to tell the user what happened when an error status has been returned from an SDLNet_function.

Returns: a char pointer (string) containing a humam readble version or the reason for the last error that occured.

printf("Oh My Goodness, an error : %s", SDLNet_GetError());

3.1.4 SDLNet_Write16

void SDLNet_Write16(Uint16 value, void *area)

value

The 16bit number to put into the area buffer

area

The pointer into a data buffer, at which to put the number

Put the 16bit (a short on 32bit systems) value into the data buffer area in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 2 bytes of space left, including the byte currently pointed at.

// put my number into a data buffer to prepare for sending to a remote host
char data[1024];
Sint16 number=12345;
SDLNet_Write16((Uint16)number,data);

See Also:
3.1.6 SDLNet_Read16, 3.1.5 SDLNet_Write32

3.1.5 SDLNet_Write32

void SDLNet_Write32(Uint32 value, void *area)

value

The 32bit number to put into the area buffer

area

The pointer into a data buffer, at which to put the number

Put the 32bit (a long on 32bit systems) value into the data buffer area in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 4 bytes of space left, including the byte currently pointed at.

// put my number into a data buffer to prepare for sending to a remote host
char data[1024];
Uint32 number=0xDEADBEEF;
SDLNet_Write32(number,data);

See Also:
3.1.7 SDLNet_Read32, 3.1.4 SDLNet_Write16

3.1.6 SDLNet_Read16

Uint16 SDLNet_Read16(void *area)

area

The pointer into a data buffer, at which to get the number from

Get a 16bit (a short on 32bit systems) value from the data buffer area which is in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The returned value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 2 bytes of space left, including the byte currently pointed at.

// get a number from a data buffer to use on this host
//char *ptr; //this points into a previously received data buffer
Sint16 number;
number=(Sint16) SDLNet_Read16(ptr);
// number is now in your hosts byte order, ready to use.

See Also:
3.1.4 SDLNet_Write16, 3.1.7 SDLNet_Read32

3.1.7 SDLNet_Read32

Uint32 SDLNet_Read32(void *area)

area

The pointer into a data buffer, at which to get the number from

Get a 32bit (a long on 32bit systems) value from the data buffer area which is in network byte order. This helps avoid byte order differences between two systems that are talking over the network. The returned value can be a signed number, the unsigned parameter type doesn't affect the data. The area pointer need not be at the beginning of a buffer, but must have at least 4 bytes of space left, including the byte currently pointed at.

// get a number from a data buffer to use on this host
//char *ptr; //this points into a previously received data buffer
Uint32 number;
number=SDLNet_Read32(ptr);
// number is now in your hosts byte order, ready to use.

See Also:
3.1.5 SDLNet_Write32, 3.1.6 SDLNet_Read16

3.2 Name Resolution

These functions are used to resolve hostnames and numerical IPv4 Address to each other.

3.2.1 SDLNet_ResolveHost
3.2.2 SDLNet_ResolveIP

3.2.1 SDLNet_ResolveHost

int SDLNet_ResolveHost(IPaddress *address, char *host, Uint16 port)

address

This points to the IPaddress that will be filled in. It doesn't need to be set before calling this, but it must be allocated in memory.

host

For connecting to a server, this is the hostname or IP in a string.
For becoming a server, this is NULL. If you do use NULL, all network interfaces would be listened to for incoming connections, using the INADDR_ANY address.

port

For connecting to a server, this is the the servers listening port number.
For becoming a server, this is the port to listen on.
If you are just doing Domain Name Resolution functions, this can be 0.

Resolve the string host, and fill in the IPaddress pointed to by address with the resolved IP and the port number passed in through port.
This is the best way to fill in the IPaddress struct for later use. This function does not actually open any sockets, it is used to prepare the arguments for the socket opening functions.
WARNING: this function will put the host and port into Network Byte Order into the address fields, so make sure you pass in the data in your hosts byte order. (normally not an issue)

Returns: 0 on success. -1 on errors, plus address.host will be INADDR_NONE. An error would likely be that the address could not be resolved.

For a server listening on all interfaces, on port 1234:

// create a server type IPaddress on port 1234
IPaddress ipaddress;
SDLNet_ResolveHost(&ipaddress, NULL, 1234);

For a client connecting to "host.domain.ext", at port 1234:

// create an IPaddress for host name "host.domain.ext" on port 1234
// this is used by a client
IPaddress ipaddress;
SDLNet_ResolveHost(&ipaddress, "host.domain.ext", 1234);

See Also:
3.2.2 SDLNet_ResolveIP, 4.1 IPaddress

3.2.2 SDLNet_ResolveIP

char *SDLNet_ResolveIP(IPaddress *address)

address

This points to the IPaddress that will be resolved to a host name. The address->port is ignored.

Resolve the IPv4 numeric address in address->host, and return the hostname as a string.

Returns: a valid char pointer (string) on success. the returned hostname will have host and domain, as in "host.domain.ext". NULL is returned on errors, such as when it's not able to resolve the host name. The returned pointer is not to be freed. Each time you call this function the previous pointer's data will change to the new value, so you may have to copy it into a local buffer to keep it around longer.

// resolve the host name of the address in ipaddress
//IPaddress ipaddress;
char *host;
if(!(host=SDLNet_ResolveIP(&ipaddress))) {
    printf("SDLNet_ResolveIP: %s\n", SDLNet_GetError());
    exit(1);
}

See Also:
3.2.1 SDLNet_ResolveHost, 4.1 IPaddress

3.3 TCP Sockets

These 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 destionation (when possible). TCP also ensures that packets are received in the same order as sent.

General

3.3.1 SDLNet_TCP_Open		Open a TCP client or server socket
3.3.2 SDLNet_TCP_Close		Close a TCP socket

Server

3.3.3 SDLNet_TCP_Accept

Accept a connection on a server socket

Information

3.3.4 SDLNet_TCP_GetPeerAddress

Get the remote host address and port number

Input/Output

3.3.5 SDLNet_TCP_Send		Send data over a connected socket
3.3.6 SDLNet_TCP_Recv		Receive data from a connected socket

3.3.1 SDLNet_TCP_Open

TCPsocket SDLNet_TCP_Open(IPaddress *ip)

ip

This points to the IPaddress that contains the resolved IP address and port number to use.

Connect to the host and port contained in ip using a TCP connection.
If the host is INADDR_ANY, then only the port number is used, and a socket is created that can be used to later accept incoming TCP connections.

Returns: a valid TCPsocket on success, which indicates a successful connection has been established, or a socket has been created that is valid to accept incoming TCP connections. NULL is returned on errors, such as when it's not able to create a socket, or it cannot connect to host and/or port contained in ip.

// connect to localhost at port 9999 using TCP (client)

IPaddress ip;
TCPsocket tcpsock;

if(SDLNet_ResolveHost(&ip,"localhost",9999)==-1) {
    printf("SDLNet_ResolveHost: %s\n", SDLNet_GetError());
    exit(1);
}

tcpsock=SDLNet_TCP_Open(&ip);
if(!tcpsock) {
    printf("SDLNet_TCP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

// create a listening TCP socket on port 9999 (server)
IPaddress ip;
TCPsocket tcpsock;

if(SDLNet_ResolveHost(&ip,NULL,9999)==-1) {
    printf("SDLNet_ResolveHost: %s\n", SDLNet_GetError());
    exit(1);
}

tcpsock=SDLNet_TCP_Open(&ip);
if(!tcpsock) {
    printf("SDLNet_TCP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.3.3 SDLNet_TCP_Accept, 3.3.2 SDLNet_TCP_Close, 4.1 IPaddress, 4.2 TCPsocket

3.3.2 SDLNet_TCP_Close

void SDLNet_TCP_Close(TCPsocket sock)

sock

A valid TCPsocket. This can be a server or client type socket.

This shutsdown, disconnects, and closes the TCPsocket sock.
After this, you can be assured that this socket is not in use anymore. You can reuse the sock variable after this to open a new connection with SDLNet_TCP_Open. Do not try to use any other functions on a closed socket, as it is now invalid.

Returns: nothing, this always succeeds for all we need to know.

// close the connection on sock
//TCPsocket sock;

SDLNet_TCP_Close(sock);

See Also:
3.3.1 SDLNet_TCP_Open, 4.2 TCPsocket

3.3.3 SDLNet_TCP_Accept

TCPsocket SDLNet_TCP_Accept(TCPsocket server)

server

This is the server TCPsocket which was previously created by
SDLNet_TCP_Open.

Accept an incoming connection on the server TCPsocket.
Do not use this function on a connected socket. Server sockets are never connected to a remote host. What you get back is a new TCPsocket that is connected to the remote host.
This is a non-blocking call, so if no connections are there to be accepted, you will get a NULL TCPsocket and the program will continue going.

Returns: a valid TCPsocket on success, which indicates a successful connection has been established. NULL is returned on errors, such as when it's not able to create a socket, or it cannot finish connecting to the originating host and port. There also may not be a connection attempt in progress, so of course you cannot accept nothing, and you get a NULL in this case as well.

// accept a connection coming in on server_tcpsock
TCPsocket new_tcpsock;

new_tcpsock=SDLNet_TCP_Accept(server_tcpsock);
if(!new_tcpsock) {
    printf("SDLNet_TCP_Accept: %s\n", SDLNet_GetError());
}
else {
    // communicate over new_tcpsock
}

See Also:
3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

3.3.4 SDLNet_TCP_GetPeerAddress

IPaddress *SDLNet_TCP_GetPeerAddress(TCPsocket sock)

sock

This is a valid TCPsocket.

Get the Peer's (the other side of the connection, the remote side, not the local side) IP address and port number.

Returns: an IPaddress. NULL is returned on errors, or when sock is a server socket.

// get the remote IP and port
//TCPsocket new_tcpsock;
IPaddress *remote_ip;

remote_ip=SDLNet_TCP_GetPeerAddress(new_tcpsock);
if(!remote_ip) {
    printf("SDLNet_TCP_GetPeerAddress: %s\n", SDLNet_GetError());
    printf("This may be a server socket.\n");
}
else {
    // print the info in IPaddress or something else...
}

See Also:
3.3.1 SDLNet_TCP_Open, 3.3.3 SDLNet_TCP_Accept, 4.1 IPaddress, 4.2 TCPsocket

3.3.5 SDLNet_TCP_Send

int SDLNet_TCP_Send(TCPsocket sock, void *data, int len)

sock

This is a valid, connected, TCPsocket.

data

This is a pointer to the data to send over sock.

len

This is the length (in bytes) if the data.

Send data of length len over the socket sock.
This routine is not used for server sockets.

Returns: the number of bytes sent. If the number returned is less than len, then an error occured, such as the client disconnecting.

// send a hello over sock
//TCPsocket sock;
int len,result;
char *msg="Hello!";

len=strlen(msg)+1; // add one for the terminating NULL
result=SDLNet_TCP_Send(sock,msg,len);
if(result<len) {
    printf("SDLNet_TCP_Send: %s\n", SDLNet_GetError());
    // It may be good to disconnect sock because it is likely invalid now.
}

See Also:
3.3.6 SDLNet_TCP_Recv, 3.3.3 SDLNet_TCP_Accept, 3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

3.3.6 SDLNet_TCP_Recv

int SDLNet_TCP_Recv(TCPsocket sock, void *data, int maxlen)

sock

This is a valid, connected, TCPsocket.

data

This is a pointer to the buffer that receives the data from sock.

maxlen

This is the maximum length (in bytes) that will be read into data.

Receive data of exactly length maxlen bytes from the socket sock, into the memory pointed to by data.
This routine is not used for server sockets.
Unless there is an error, or the connection is closed, the buffer will read maxlen bytes. If you read more than is sent from the other end, then it will wait until the full requested length is sent, or until the connection is closed from the other end.
You may have to read 1 byte at a time for some applications, for instance, text applications where blocks of text are sent, but you want to read line by line. In that case you may want to find the newline characters yourself to break the lines up, instead of reading some inordinate amount of text which may contain many lines, or not even a full line of text.

Returns: the number of bytes received. If the number returned is less than or equal to zero, then an error occured, or the remote host has closed the connection.

// receive some text from sock
//TCPsocket sock;
#define MAXLEN 1024
int result;
char msg[MAXLEN];

result=SDLNet_TCP_Recv(sock,msg,MAXLEN);
if(result<=0) {
    // An error may have occured, but sometimes you can just ignore it
    // It may be good to disconnect sock because it is likely invalid now.
}
printf("Received: \"%s\"\n",msg);

See Also:
3.3.5 SDLNet_TCP_Send, 3.3.3 SDLNet_TCP_Accept, 3.3.1 SDLNet_TCP_Open, 3.3.4 SDLNet_TCP_GetPeerAddress, 3.3.2 SDLNet_TCP_Close, 4.2 TCPsocket

3.4 UDP Sockets

These 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 don't have to address every outgoing packet if you don't want to. 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 may also be received completely out of order, as compared to the order of sending them.
All these seeming bad qualities are made up for in speed. UDP is faster than TCP, and so many games and speed sensitive applications, which may also be sending redundant data anyways, such as a game state, prefer to use UDP for the speed benefits.

SDL_net has a concept of channels, which help you to matchup packets to specific clients easier. These channel numbers are not transmitted in the UDP packet data, but rather when a UDP socket receives or sends packets, a channel number may be used instead of an IPaddress to refer to the source or destination. You might prefer not to use channels at all, which is fine. SDL_net provides them only as an optional convenience.

General

3.4.1 SDLNet_UDP_Open		Create a UDP socket
3.4.2 SDLNet_UDP_Close		Close and free a UDP socket

Channel Binding

3.4.3 SDLNet_UDP_Bind		Assign an IP address number to a socket channel
3.4.4 SDLNet_UDP_Unbind		Remove all assigned IP addresses from a socket channel
3.4.5 SDLNet_UDP_GetPeerAddress		Get the assigned IP address for a socket channel or get the port you opened the socket with

Single UDPpacket

3.4.6 SDLNet_UDP_Send		Send a UDPpacket
3.4.7 SDLNet_UDP_Recv		Receive into a UDPpacket

Many UDPpackets in a vector (array)

3.4.8 SDLNet_UDP_SendV		Send a UDPpacket vector
3.4.9 SDLNet_UDP_RecvV		Receive into a UDPpacket vector

3.4.1 SDLNet_UDP_Open

UDPsocket SDLNet_UDP_Open(Uint16 port)

port

This is the port number (in native byte order) on which to receive UDP packets. Most servers will want to use a known port number here so that clients can easily communicate with the server. This can also be zero, which then opens an anonymous unused port number, to most likely be used to send UDP packets from.

Open a socket to be used for UDP packet sending and/or receiving.
If a non-zero port is given it will be used, otherwise any open port number will be used automatically.
Unlike TCP sockets, this socket does not require a remote host IP to connect to, this is because UDP ports are never actually connected like TCP ports are.
This socket is able to send and receive directly after this simple creation.

Returns: a valid UDPsocket on success. NULL is returned on errors, such as when it's not able to create a socket, or it cannot assign the non-zero port as requested.

Note that below I say server, but clients may also open a specific port, though it is prefered that a client be more flexible, given that the port may be already allocated by another process, such as a server. In such a case you will not be able to open the socket, and your program will be stuck, so it is better to just use whatever port you are given by using a specified port of zero. Then the client will always work. The client can inform the server what port to talk back to, or the server can just look at the source of the packets it is receiving to know where to respond to.

// create a UDPsocket on port 6666 (server)
UDPsocket udpsock;

udpsock=SDLNet_UDP_Open(6666);
if(!udpsock) {
    printf("SDLNet_UDP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

// create a UDPsocket on any available port (client)
UDPsocket udpsock;

udpsock=SDLNet_UDP_Open(0);
if(!udpsock) {
    printf("SDLNet_UDP_Open: %s\n", SDLNet_GetError());
    exit(2);
}

See Also:
3.4.2 SDLNet_UDP_Close, 4.3 UDPsocket

3.4.2 SDLNet_UDP_Close

void SDLNet_UDP_Close(UDPsocket sock)

sock

A valid UDPsocket to shutdown, close, and free.

Shutdown, close, and free a UDPsocket.
Don't use the UDPsocket after calling this, except to open a new one.

Returns: nothing, this always succeeds.

// unbind all addresses on the UDPsocket channel 0
//UDPsocket udpsock;

SDLNet_UDP_Close(udpsock);
udpsock=NULL; //this helps us know that this UDPsocket is not valid anymore

See Also:
3.4.1 SDLNet_UDP_Open, 4.3 UDPsocket

3.4.3 SDLNet_UDP_Bind

int SDLNet_UDP_Bind(UDPsocket sock, int channel, IPaddress *address)

sock

the UDPsocket on which to assign the address.

channel

The channel to assign address to. This should be less than
SDLNET_MAX_UDPCHANNELS. If -1 is used, then the first unbound channel will be used, this should only be used for incomming packet filtering, as it will find the first channel with less than SDLNET_MAX_UDPADDRESSES assigned to it and use that one.

address

The resolved IPaddress to assign to the socket's channel. The host and port are both used.
It is not helpful to bind 0.0.0.0 to a channel.

Bind an address to a channel on a socket.
Incoming packets are only allowed from bound addresses for the socket channel.
All outgoing packets on that channel, regardless of the packets internal address, will attempt to send once on each bound address on that channel.
You may assign up to SDLNET_MAX_UDPADDRESSES to each channel.

Returns: The channel number that was bound. -1 is returned on errors, such as no free channels, or this channel has SDLNET_MAX_UDPADDRESSES already assigned to it, or you have used a channel higher or equal to SDLNET_MAX_UDPCHANNELS, or lower than -1.

// Bind address to the first free channel
//UDPsocket udpsock;
//IPaddress *address;
int channel;

channel=SDLNet_UDP_Bind(udpsock, -1, address);
if(channel==-1) {
    printf("SDLNet_UDP_Bind: %s\n", SDLNet_GetError());
    // do something because we failed to bind
}

See Also:
3.4.4 SDLNet_UDP_Unbind, 3.4.5 SDLNet_UDP_GetPeerAddress, 3.4.1 SDLNet_UDP_Open, 4.1 IPaddress, 4.3 UDPsocket

3.4.4 SDLNet_UDP_Unbind

void SDLNet_UDP_Unbind(UDPsocket sock, int channel)

sock

A valid UDPsocket to unbind addresses from.

channel

The channel to unbind the addresses from in the UDPsocket.

This removes all previously assigned (bound) addresses from a socket channel.
After this you may bind new addresses to the socket channel.

Returns: nothing, this always succeeds.

// unbind all addresses on the UDPsocket channel 0
//UDPsocket udpsock;

SDLNet_UDP_Unbind(udpsock, 0);

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.2 SDLNet_UDP_Close, 4.3 UDPsocket

3.4.5 SDLNet_UDP_GetPeerAddress

IPaddress *SDLNet_UDP_GetPeerAddress(UDPsocket sock, int channel)

sock

A valid UDPsocket that probably has an address assigned to the channel.

channel

The channel to get the primary address from in the socket. This may also be -1 to get the port which this socket is bound to on the local computer.

Get the primary address assigned to this channel. Only the first bound address is returned.
When channel is -1, get the port that this socket is bound to on the local computer, this only means something if you opened the socket with a specific port number.
Do not free the returned IPaddress pointer.

Returns: a pointer to an IPaddress. NULL is returned for unbound channels and on any errors.

// get the primary address bound to UDPsocket channel 0
//UDPsocket udpsock;
IPaddress *address;

address=SDLNet_UDP_GetPeerAddress(udpsock, 0);
if(!address) {
    printf("SDLNet_UDP_GetPeerAddress: %s\n", SDLNet_GetError());
    // do something because we failed to get the address
}
else {
    // perhaps print out address->host and address->port
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.4 SDLNet_UDP_Unbind, 4.1 IPaddress, 4.3 UDPsocket

3.4.6 SDLNet_UDP_Send

int SDLNet_UDP_Send(UDPsocket sock, int channel, UDPpacket *packet)

sock

A valid UDPsocket.

channel

what channel to send packet on.

packet

The packet to send.

Send packet using the specified socket sock, use ing the specified channel or else the packet's address.
If channel is not -1 then the packet is sent to all the socket channels bound addresses. If socket sock's channel is not bound to any destinations, then the packet is not sent at all!
If the channel is -1, then the packet's address is used as the destination.
Don't forget to set the length of the packet in the len element of the packet you are sending! NOTE: the packet->channel will be set to the channel passed in to this function.

Returns: The number of destinations sent to that worked. 0 is returned on errors.
Note that since a channel can point to multiple destinations, there should be just as many packets sent, so dont assume it will always return 1 on success. Unfortunately there's no way to get the number of destinations bound to a channel, so either you have to remember the number bound, or just test for the zero return value indicating all channels failed.

// send a packet using a UDPsocket, using the packet's channel as the channel
//UDPsocket udpsock;
//UDPpacket *packet;
int numsent;

numsent=SDLNet_UDP_Send(udpsock, packet->channel, packet);
if(!numsent) {
    printf("SDLNet_UDP_Send: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channel...
}

Here's a way of sending one packet using it's internal channel setting.
This is actually what SDLNet_UDP_Send ends up calling for you.

// send a packet using a UDPsocket, using the packet's channel as the channel
//UDPsocket udpsock;
//UDPpacket *packet;
int numsent;

numsent=SDLNet_UDP_SendV(sock, &packet, 1);
if(!numsent) {
    printf("SDLNet_UDP_SendV: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channel...
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.8 SDLNet_UDP_SendV, 3.4.7 SDLNet_UDP_Recv, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

3.4.7 SDLNet_UDP_Recv

int SDLNet_UDP_Recv(UDPsocket sock, UDPpacket *packet)

sock

A valid UDPsocket.

packet

The packet to receive into.

Receive a packet on the specified sock socket.
The packet you pass in must have enough of a data size allocated for the incoming packet data to fit into. This means you should have knowledge of your size needs before trying to receive UDP packets.
The packet will have it's address set to the remote sender's address.
The socket's channels are checked in highest to lowest order, so if an address is bound to multiple channels, the highest channel with the source address bound will be retreived before the lower bound channels. So, the packets channel will also be set to the highest numbered channel that has the remote address and port assigned to it. Otherwise the channel will -1, which you can filter out easily if you want to ignore unbound source address.
Note that the local and remote channel numbers do not have to, and probably won't, match, as they are only local settings, they are not sent in the packet.
This is a non-blocking call, meaning if there's no data ready to be received the function will return.

Returns: 1 is returned when a packet is received. 0 is returned when no packets are received. -1 is returned on errors.

// try to receive a waiting udp packet
//UDPsocket udpsock;
UDPpacket packet;
int numrecv;

numrecv=SDLNet_UDP_Recv(udpsock, &packet);
if(numrecv) {
    // do something with packet
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

3.4.8 SDLNet_UDP_SendV

int SDLNet_UDP_SendV(UDPsocket sock, UDPpacket **packetV, int npackets)

sock

A valid UDPsocket.

packetV

The vector of packets to send.

npackets

number of packets in the packetV vector to send.

Send npackets of packetV using the specified sock socket.
Each packet is sent in the same way as in SDLNet_UDP_Send (see section 3.4.6 SDLNet_UDP_Send).
Don't forget to set the length of the packets in the len element of the packets you are sending!

Returns: The number of destinations sent to that worked, for each packet in the vector, all summed up. 0 is returned on errors.

// send a vector of 10 packets using UDPsocket
//UDPsocket udpsock;
//UDPpacket **packetV;
int numsent;

numsent=SDLNet_UDP_SendV(udpsock, packetV, 10);
if(!numsent) {
    printf("SDLNet_UDP_SendV: %s\n", SDLNet_GetError());
    // do something because we failed to send
    // this may just be because no addresses are bound to the channels...
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.7 SDLNet_UDP_Recv, 3.4.9 SDLNet_UDP_RecvV, 4.4 UDPpacket, 4.3 UDPsocket

3.4.9 SDLNet_UDP_RecvV

int SDLNet_UDP_RecvV(UDPsocket sock, UDPpacket **packetV)

sock

A valid UDPsocket.

packet

The packet to receive into.

Receive into a packet vector on the specified socket sock.
packetV is a NULL terminated array. Packets will be received until the NULL is reached, or there are none ready to be received.
This call is otherwise the same as SDLNet_UDP_Recv (see section 3.4.7 SDLNet_UDP_Recv).

Returns: the number of packets received. 0 is returned when no packets are received. -1 is returned on errors.

// try to receive some waiting udp packets
//UDPsocket udpsock;
//UDPpacket **packetV;
int numrecv, i;

numrecv=SDLNet_UDP_RecvV(udpsock, &packetV);
if(numrecv==-1) {
    // handle error, perhaps just print out the SDL_GetError string.
}
for(i=0; i<numrecv; i++) {
    // do something with packetV[i]
}

See Also:
3.4.3 SDLNet_UDP_Bind, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 3.4.7 SDLNet_UDP_Recv, 4.4 UDPpacket, 4.3 UDPsocket

3.5 UDP Packets

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

Single UDPpacket

3.5.1 SDLNet_AllocPacket		Allocate a new UDP packet with a data buffer
3.5.2 SDLNet_ResizePacket		Resize the data buffer in a UDPpacket
3.5.3 SDLNet_FreePacket		Free a previously allocated UDPpacket

Many UDPpackets in a vector (array)

3.5.4 SDLNet_AllocPacketV		Allocate a vector of UDPpackets
3.5.5 SDLNet_FreePacketV		Free a vector of UDPpackets

3.5.1 SDLNet_AllocPacket

UDPpacket *SDLNet_AllocPacket(int size)

size

Size, in bytes, of the data buffer to be allocated in the new UDPpacket.
Zero is invalid.

Create (via malloc) a new UDPpacket with a data buffer of size bytes.
The new packet should be freed using SDLNet_FreePacket when you are done using it.

Returns: a pointer to a new empty UDPpacket. NULL is returned on errors, such as out-of-memory.

// create a new UDPpacket to hold 1024 bytes of data
UDPpacket *packet;

packet=SDLNet_AllocPacket(1024);
if(!packet) {
    printf("SDLNet_AllocPacket: %s\n", SDLNet_GetError());
    // perhaps do something else since you can't make this packet
}
else {
    // do stuff with this new packet
    // SDLNet_FreePacket this packet when finished with it
}

See Also:
3.5.4 SDLNet_AllocPacketV, 3.5.2 SDLNet_ResizePacket, 3.5.3 SDLNet_FreePacket, 3.4.6 SDLNet_UDP_Send, 3.4.8 SDLNet_UDP_SendV, 4.4 UDPpacket

3.5.2 SDLNet_ResizePacket

int SDLNet_ResizePacket(UDPpacket *packet, int size)

packet

A pointer to the UDPpacket to be resized.

size

The new desired size, in bytes, of the data buffer to be allocated in the UDPpacket.
Zero is invalid.

Resize a UDPpackets data buffer to size bytes. The old data buffer will not be retained, so the new buffer is invalid after this call.

Returns: the new size of the data in the packet. If the number returned is less than what you asked for, that's an error.

// Resize a UDPpacket to hold 2048 bytes of data
//UDPpacket *packet;
int newsize;

newsize=SDLNet_ResizePacket(packet, 2048);
if(newsize<2048) {
    printf("SDLNet_ResizePacket: %s\n", SDLNet_GetError());
    // perhaps do something else since you didn't get the buffer you wanted
}
else {
    // do stuff with the resized packet
}

See Also:
3.5.1 SDLNet_AllocPacket, 3.5.4 SDLNet_AllocPacketV, 3.5.3 SDLNet_FreePacket, 4.