NET_CreateDatagramSocket(3)

NAME
NET_CreateDatagramSocket - Create and bind a new datagram socket.

SYNOPSIS
#include <SDL3_net/SDL_net.h>

NET_DatagramSocket * NET_CreateDatagramSocket(NET_Address *addr, Uint16 port, SDL_PropertiesID props);

#define NET_PROP_DATAGRAM_SOCKET_REUSEADDR_BOOLEAN         "NET.datagram_socket.reuseaddr"
#define NET_PROP_DATAGRAM_SOCKET_ALLOW_BROADCAST_BOOLEAN   "NET.datagram_socket.allow_broadcast"

DESCRIPTION
Datagram sockets follow different rules than stream sockets. They are not a reliable stream of bytes but rather packets, they are not limited to talking to a single other remote system, they do not maintain a single "connection" that can be dropped, and they are more nimble about network failures at the expense of being more complex to use. What makes sense for your app depends entirely on what your app is trying to accomplish.

Generally the idea of a datagram socket is that you send data one chunk ("packet") at a time to any address you want, and it arrives whenever it gets there, even if later packets get there first, and maybe it doesn't get there at all, and you don't know when anything of this happens by default.

This function creates a new datagram socket.

This function does not block, and is not asynchronous, as the system can decide immediately if it can create a socket or not. If this returns success, you can immediately start talking to the network.

You can specify an address to listen for connections on; this address must be local to the system, and probably one returned by NET_GetLocalAddresses(), but almost always you just want to specify NULL here, to listen on any address available to the app.

If you need to bind to a specific port (like a server), you should specify it in the port argument; datagram servers should do this, so they can be reached at a well-known port. If you only plan to initiate communications (like a client), you should specify 0 and let the system pick an unused port. Only one process can bind to a specific port at a time, so if you aren't acting as a server, you should choose 0. Datagram sockets can send individual packets to any port, so this just declares where data will arrive for your socket.

Datagram sockets don't employ any protocol (above the UDP level), so they can talk to apps that aren't using SDL_net, but if you want to speak any protocol beyond arbitrary packets of bytes, such as WebRTC, you'll have to implement that yourself on top of the stream socket.

Unlike BSD sockets or WinSock, you specify the port as a normal integer; you do not have to byteswap it into "network order," as the library will handle that for you.

The caller may supply properties to customize behavior. This is optional, and a value of zero for props will request defaults for all properties.

These are the supported properties:

• NET_PROP_DATAGRAM_SOCKET_REUSEADDR_BOOLEAN: true if the socket should be created even if a previous socket has recently used this address. For various reasons, networks prefer that there be some delay between apps reusing the same address, but this can be problematic when iterating quickly, for software development purposes or just restarting a crashed service. This property defaults to true (although it should be noted that, at the operating system level, this defaults to false!). If this property is false and the OS feels that not enough time has elapsed, socket creation will fail and this function will report an error.

• NET_PROP_DATAGRAM_SOCKET_ALLOW_BROADCAST_BOOLEAN: true if the socket should allow broadcasting. At the lower level, this will set SO_BROADCAST for IPv4 sockets, to allow sending to the subnet's broadcast address at the OS level. For IPv6, it'll join the all-nodes link-local multicast group, ff02::1, allowing sending and receiving there, more or less simulating the usual IPv4 broadcast semantics. Other protocols take similar approaches. If you do not intend to send or receive broadcast packets on this socket, set this property to false, or omit it, as it defaults to false. Note: IPv4 will still be able to receive broadcast packets without this option, but IPv6 will not. Also see notes about sending to a broadcast address in NET_SendDatagram().

FUNCTION PARAMETERS

addr
    the local address to listen for connections on, or NULL to listen on all available local addresses.

port
    the port on the local address to listen for connections on, or zero for the system to decide.

props
    properties of the new socket. Specify zero for defaults.

RETURN VALUE
Returns a new NET_DatagramSocket, or NULL on error; call SDL_GetError() for details.

THREAD SAFETY
It is safe to call this function from any thread.

AVAILABILITY
This function is available since SDL_net 3.0.0.

SEE ALSO
NET_GetLocalAddresses(3), NET_DestroyDatagramSocket(3)