NET_CreateClient(3)

💖 NET_CreateClient(3) 💖

okay bestie, welcome to the SDL_net3 FUNCTIONS corner of the manual, and today's main character is NET_CreateClient 🫶

---

✨ NAME ✨

NET_CreateClient — start connecting a socket as a client to a remote server. it's giving "hi, can we be friends" but with TCP 🔥

---

✨ SYNOPSIS ✨

#include <SDL3_net/SDL_net.h>

NET_StreamSocket * NET_CreateClient(NET_Address *address, Uint16 port, SDL_PropertiesID props);

---

✨ DESCRIPTION ✨

so like, every single NET_StreamSocket is one connection between systems. one. single. connection. usually a client app has one connection to a server app living on some other computer, and that server app might be juggling a whole crowd of connections from different clients 👑 and each of those connections talks over its own separate stream socket. iconic, honestly.

connecting is asynchronous, which is the fancy way of saying: this function does not block, and it will come back to you before the connection is actually complete. so you can't just assume it worked!! you have to go check with NET_WaitUntilConnected() or NET_GetConnectionStatus() to see when the operation finished and whether it was actually successful. no skipping this step, fr fr 🙈

once you're connected, you can read and write data on the socket you got back. stream sockets are a mode of reliable transmission — that means your data shows up as a stream of bytes in the exact order you sent it. if transmission has problems, the system handles protocol negotiation and retransmission for you, transparent to your app, no notes 💅 but here's the tradeoff: until data is available in the order sent, the remote side gets nothing new. that's the deal you make. compare that to datagram sockets, where data can arrive in any order, or just... not arrive at all, without waiting — but the sender never finds out. pick your fighter.

stream sockets don't employ any protocol above the TCP level, so they can connect to servers that aren't even using SDL_net 🦋 but if you wanna speak anything beyond an arbitrary stream of bytes — like HTTP — you're gonna have to implement that yourself on top of the stream socket. it's giving DIY. it's giving "you got this, but it's on you."

heads up bestie: this function will fail if address is not finished resolving. 🚨

when you're done with this connection — and yes, that includes if it failed to connect — you must dispose of it with NET_DestroyStreamSocket(). don't leave it lying around, that's not the vibe 🌸

and here's a lil gift: unlike BSD sockets or WinSock, you pass the port as a normal integer. you do not have to byteswap it into "network order" — the library handles that for you. periodt 💅

also, as of right now there are no extra properties for creating a client, so props should be zero. a future revision of SDL_net may add additional (optional) properties though, so keep an eye out 👀

---

✨ FUNCTION PARAMETERS ✨

• address — the address of the remote server you're connecting to. the destination. the whole point. 🎯
• port — the port on that remote server you're connecting to. 🔌
• props — the properties of your new client. specify zero for defaults. (and rn zero is literally the only option, so, easy.) ✨

---

✨ RETURN VALUE ✨

returns a new NET_StreamSocket with a pending connection, or NULL on error 😭 — and if you get NULL, call SDL_GetError() for the details. always read the error, bestie, it's literally telling you what went wrong.

---

✨ THREAD SAFETY ✨

it is safe to call this function from any thread. go wild. 🌈

---

✨ AVAILABILITY ✨

this function has been available since SDL_net 3.0.0 🎀

---

✨ SEE ALSO ✨

• NET_WaitUntilConnected(3) — go wait for it to connect 💖
• NET_GetConnectionStatus(3) — go check how it's going 👀
• NET_DestroyStreamSocket(3) — go clean up after yourself 🧚

---

and that's the whole page, bestie!! this one's from SDL_net 3.2.0, manual page NET_CreateClient(3), brought to you by the fine folks over at SDL_net 💜 go forth and connect responsibly, mwah 🫶✨