@@ -588,6 +588,20 @@ extern SDL_DECLSPEC NET_StreamSocket * SDLCALL NET_CreateClient(NET_Address *add
588
588
*/
589
589
extern SDL_DECLSPEC int SDLCALL NET_WaitUntilConnected (NET_StreamSocket * sock , Sint32 timeout );
590
590
591
+ /**
592
+ * The receiving end of a stream connection.
593
+ *
594
+ * This is an opaque datatype, to be treated by the app as a handle.
595
+ *
596
+ * Internally, this is what BSD sockets refers to as a "listen socket". Clients
597
+ * attempt to connect to a server, and if the server accepts the connection,
598
+ * will provide the app with a stream socket to send and receive data over that
599
+ * connection.
600
+ *
601
+ * \since This datatype is available since SDL_Net 3.0.0.
602
+ *
603
+ * \sa NET_CreateServer
604
+ */
591
605
typedef struct NET_Server NET_Server ; /**< a listen socket, internally. Binds to a port, accepts connections. */
592
606
593
607
/**
@@ -1000,6 +1014,29 @@ extern SDL_DECLSPEC void SDLCALL NET_DestroyStreamSocket(NET_StreamSocket *sock)
1000
1014
1001
1015
/* Datagram (UDP) API... */
1002
1016
1017
+ /**
1018
+ * An object that represents a datagram connection to another system.
1019
+ *
1020
+ * This is meant to be an unreliable, packet-oriented connection, such as UDP.
1021
+ *
1022
+ * Datagram sockets follow different rules than stream sockets. They are not a
1023
+ * reliable stream of bytes but rather packets, they are not limited to
1024
+ * talking to a single other remote system, they do not maintain a single
1025
+ * "connection" that can be dropped, and they are more nimble about network
1026
+ * failures at the expense of being more complex to use. What makes sense for
1027
+ * your app depends entirely on what your app is trying to accomplish.
1028
+ *
1029
+ * Generally the idea of a datagram socket is that you send data one chunk
1030
+ * ("packet") at a time to any address you want, and it arrives whenever it
1031
+ * gets there, even if later packets get there first, and maybe it doesn't get
1032
+ * there at all, and you don't know when anything of this happens by default.
1033
+ *
1034
+ * \since This datatype is available since SDL_Net 3.0.0.
1035
+ *
1036
+ * \sa NET_CreateDatagramSocket
1037
+ * \sa NET_SendDatagram
1038
+ * \sa NET_ReceiveDatagram
1039
+ */
1003
1040
typedef struct NET_DatagramSocket NET_DatagramSocket ; /**< a UDP socket. Unreliable, packet-based transmission, with the usual pros/cons */
1004
1041
1005
1042
/**
0 commit comments