NET_ReceiveDatagram(3)

💌 NET_ReceiveDatagram(3) — or, "bestie, is there a packet in the mailbox?"

okay so welcome to the SDL_net3 manual, and today's main character is NET_ReceiveDatagram. it grabs a brand-new packet that some remote system yeeted at your datagram socket. let's get into it 🫶

---

✨ NAME ✨

NET_ReceiveDatagram — receive a new packet that a remote system sent to a datagram socket. it's giving "package delivery but for bytes" 📦

---

🌸 SYNOPSIS 🌸

#include <SDL3_net/SDL_net.h>

bool NET_ReceiveDatagram(NET_DatagramSocket *sock, NET_Datagram **dgram);

---

🦋 DESCRIPTION 🦋

so datagram sockets send packets of data. packets either show up as a whole entire complete packet, or they simply do not show up at all. there is no half-packet situation, no "oops we got 60% of it", nothing. you never receive half a packet. periodt 💅

this call never blocks. if there's no new data available at the exact moment you call it, it just returns true immediately and you (the caller) can try again later. no waiting around, no staring at the wall, she's not that kind of function ✨

here's the lil trick though: on a successful call, this function returns true even if no new packets are available. so to actually know if a new packet is there, you gotta check for a successful return AND a non-NULL value in *dgram. both. together. it's a two-step vibe check, iykyk 👑

you must pass received packets to NET_DestroyDatagram when you're done with them, no leaving them lying around like dirty laundry. and if you want to hold onto the sender's address past that point, it is safe to call NET_RefAddress() on the address and keep the pointer — just as long as you call NET_UnrefAddress() on it when you're done with it. balanced. fair. iconic 🎀

since datagrams can arrive from any address or port on the network without prior warning (no invite, no heads-up, just showing up to the party unannounced 😭), that info lives in the NET_Datagram object this function hands you — and that is the only way to know who to reply to. even if you're not acting as a "server," packets can still arrive at your socket if someone sends one. you're not immune, bestie, you're just not serving.

if there's a fatal error, this function returns false. datagram sockets generally won't report failures, because there's no state like a "connection" to fail at this level — but they may report failure for unrecoverable system-level conditions. and once a datagram socket fails, assume it's no longer usable and destroy it with SDL_DestroyDatagramSocket(). that socket is done, send flowers 🌷

⚠️ for real though: once a datagram socket fails, it is not coming back. destroy it, don't try to revive it.

---

💖 FUNCTION PARAMETERS 💖

• sock — the datagram socket to send data through.
• dgram — a pointer to the datagram packet pointer.

---

🌈 RETURN VALUE 🌈

Returns true if data sent or queued for transmission, false on failure. on failure, call SDL_GetError() for the details — she will tell you what went wrong 💀

---

🧚 THREAD SAFETY 🧚

do not operate on the same socket from multiple threads at the same time without supplying a serialization mechanism. one socket, one thread at a time, we do not share. however, different threads may access different sockets at the same time without problems. so like, share the vibes, not the socket 🫶

---

⭐ AVAILABILITY ⭐

this function is available since SDL_net 3.0.0. she's been here a minute 👑

---

👀 SEE ALSO 👀

• NET_SendDatagram(3)
• NET_DestroyDatagram(3)

---

okay that's the whole page, no cap. this was the SDL_net 3.2.0 manual, NET_ReceiveDatagram(3), and honestly? obsessed with her. go check your *dgram, destroy your datagrams, and unref your addresses when you're done. mwah 💖✨🎀