From 70521db34252c8de919bae068b5d80bc59aef72d Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 14 May 2025 01:37:55 -0400
Subject: [PATCH] Revert "Sync SDL3_net wiki -> header"
This reverts commit bc6a72ba055ffe13a5a89108bc5a56320d0fa72c.
---
include/SDL3_net/SDL_net.h | 37 +++++++++++++++++++++++++++++++++++++
1 file changed, 37 insertions(+)
diff --git a/include/SDL3_net/SDL_net.h b/include/SDL3_net/SDL_net.h
index aa9a4b8..5a135f5 100644
--- a/include/SDL3_net/SDL_net.h
+++ b/include/SDL3_net/SDL_net.h
@@ -588,6 +588,20 @@ extern SDL_DECLSPEC NET_StreamSocket * SDLCALL NET_CreateClient(NET_Address *add
*/
extern SDL_DECLSPEC int SDLCALL NET_WaitUntilConnected(NET_StreamSocket *sock, Sint32 timeout);
+/**
+ * The receiving end of a stream connection.
+ *
+ * This is an opaque datatype, to be treated by the app as a handle.
+ *
+ * Internally, this is what BSD sockets refers to as a "listen socket". Clients
+ * attempt to connect to a server, and if the server accepts the connection,
+ * will provide the app with a stream socket to send and receive data over that
+ * connection.
+ *
+ * \since This datatype is available since SDL_Net 3.0.0.
+ *
+ * \sa NET_CreateServer
+ */
typedef struct NET_Server NET_Server; /**< a listen socket, internally. Binds to a port, accepts connections. */
/**
@@ -1000,6 +1014,29 @@ extern SDL_DECLSPEC void SDLCALL NET_DestroyStreamSocket(NET_StreamSocket *sock)
/* Datagram (UDP) API... */
+/**
+ * An object that represents a datagram connection to another system.
+ *
+ * This is meant to be an unreliable, packet-oriented connection, such as UDP.
+ *
+ * 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.
+ *
+ * \since This datatype is available since SDL_Net 3.0.0.
+ *
+ * \sa NET_CreateDatagramSocket
+ * \sa NET_SendDatagram
+ * \sa NET_ReceiveDatagram
+ */
typedef struct NET_DatagramSocket NET_DatagramSocket; /**< a UDP socket. Unreliable, packet-based transmission, with the usual pros/cons */
/**