NET_CreateClient(3)

NAME
NET_CreateClient - Begin connecting a socket as a client to a remote server.

SYNOPSIS
#include <SDL3_net/SDL_net.h>

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

DESCRIPTION
Each NET_StreamSocket represents a single connection between systems. Usually, a client app will have one connection to a server app on a different computer, and the server app might have many connections from different clients. Each of these connections communicate over a separate stream socket.

Connecting is an asynchronous operation; this function does not block, and will return before the connection is complete. One has to then use NET_WaitUntilConnected() or NET_GetConnectionStatus() to see when the operation has completed, and if it was successful.

Once connected, you can read and write data to the returned socket. Stream sockets are a mode of _reliable_ transmission, which means data will be received as a stream of bytes in the order you sent it. If there are problems in transmission, the system will deal with protocol negotiation and retransmission as necessary, transparent to your app, but this means until data is available in the order sent, the remote side will not get any new data. This is the tradeoff vs datagram sockets, where data can arrive in any order, or not arrive at all, without waiting, but the sender will not know.

Stream sockets don't employ any protocol (above the TCP level), so they can connect to servers that aren't using SDL_net, but if you want to speak any protocol beyond an abritrary stream of bytes, such as HTTP, you'll have to implement that yourself on top of the stream socket.

This function will fail if address is not finished resolving.

When you are done with this connection (whether it failed to connect or not), you must dispose of it with NET_DestroyStreamSocket().

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.

There are currently no extra properties for creating a client, so props should be zero. A future revision of SDL_net may add additional (optional) properties.

FUNCTION PARAMETERS

address
    the address of the remote server to connect to.

port
    the port on the remote server to connect to.

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

RETURN VALUE
Returns a new NET_StreamSocket, pending connection, 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_WaitUntilConnected(3), NET_GetConnectionStatus(3), NET_DestroyStreamSocket(3)