Socket

Table of Contents

• Dependencies
• Features
• Details
• Status
• Blog
• Description
  • SocketDescriptor
  • SocketServer
  • SocketClient
  • SocketIPAddress
  • SocketDNS
• Roadmap
• Statistics

🟨 Synchronous socket networking and DNS lookup

SaneCppSocket.h is a library implementing synchronous socket networking and DNS lookup.

Dependencies

• Dependencies: Foundation
• All dependencies: Foundation

Features

Class	Description
SC::SocketDescriptor	Low-level OS socket handle.
SC::SocketServer	Use a SocketDescriptor as a Server (example TCP or UDP Socket Server).
SC::SocketClient	Use a SocketDescriptor as a client (example a TCP or UDP socket client).
SC::SocketIPAddress	Native representation of an IP Address.
SC::SocketDNS	Synchronous DNS Resolution.
SC::SocketNetworking	Networking globals initialization (Winsock2 WSAStartup)

Details

Status

🟨 MVP
Simple synchronous TCP client / server workflow is supported, but it would need better testing.

Blog

Some relevant blog posts are:

• June 2025 Update
• July 2025 Update

Description

• SC::SocketDescriptor can create and destroy the OS level socket descriptor.
• SC::SocketServer can SC::SocketServer::listen on a given port / address and SC::SocketServer::accept a new client socket.
• SC::SocketClient can SC::SocketClient::connect, SC::SocketClient::write, SC::SocketClient::read and SC::SocketClient::readWithTimeout.
• SC::SocketIPAddress allows creating an ip address native object from a SC::StringView and port.
• SC::SocketDNS class allow resolving a StringView to an IP address.
• SC::SocketNetworking initializes WinSock2 for current process.

SocketDescriptor

It also allow querying inheritability and changing it (and blocking mode)
Example (extracted from unit test):

    bool isInheritable;
 
    // We are testing only the inheritable because on windows there is no reliable
    // way of checking if a non-connected socket is in non-blocking mode
    SocketDescriptor socket;
    SC_TEST_EXPECT(socket.create(SocketFlags::AddressFamilyIPV4, SocketFlags::SocketStream, SocketFlags::ProtocolTcp,
                                 SocketFlags::NonBlocking, SocketFlags::NonInheritable));
    SC_TEST_EXPECT(socket.isValid());
    isInheritable = false;
    SC_TEST_EXPECT(socket.isInheritable(isInheritable));
    SC_TEST_EXPECT(not isInheritable);
    SC_TEST_EXPECT(socket.close());
 
    SC_TEST_EXPECT(socket.create(SocketFlags::AddressFamilyIPV4, SocketFlags::SocketStream, SocketFlags::ProtocolTcp,
                                 SocketFlags::Blocking, SocketFlags::NonInheritable));
    SC_TEST_EXPECT(socket.isValid());
    isInheritable = false;
    SC_TEST_EXPECT(socket.isInheritable(isInheritable));
    SC_TEST_EXPECT(not isInheritable);
    SC_TEST_EXPECT(socket.close());
 
    SC_TEST_EXPECT(socket.create(SocketFlags::AddressFamilyIPV4, SocketFlags::SocketStream, SocketFlags::ProtocolTcp,
                                 SocketFlags::Blocking, SocketFlags::Inheritable));
    SC_TEST_EXPECT(socket.isValid());
    isInheritable = false;
    SC_TEST_EXPECT(socket.isInheritable(isInheritable));
    SC_TEST_EXPECT(isInheritable);
    SC_TEST_EXPECT(socket.close());

SocketServer

Example:

    SocketDescriptor serverSocket;
    SocketServer     server(serverSocket);
 
    // Look for an available port
    constexpr int    tcpPort       = 5050;
    const StringView serverAddress = "::1"; // or "127.0.0.1"
    SocketIPAddress  nativeAddress;
    SC_TRY(nativeAddress.fromAddressPort(serverAddress, tcpPort));
    SocketFlags::AddressFamily family = nativeAddress.getAddressFamily();
 
    // Create socket and start listening
    SC_TRY(serverSocket.create(family)); // By default creates a TCP Server
 
    // [Alternatively] Create an UDP socket instead
    // SC_TRY(serverSocket.create(family, SocketFlags::SocketDgram, SocketFlags::ProtocolUdp));
 
    SC_TRY(server.bind(nativeAddress)); // Bind the socket to the given address
    SC_TRY(server.listen(1));           // Start listening (skip this for UDP sockets)
 
    // Accept a client
    SocketDescriptor acceptedClientSocket;
    SC_TRY(server.accept(family, acceptedClientSocket));
    SC_TRY(acceptedClientSocket.isValid());
 
    // ... Do something with acceptedClientSocket

SocketClient

The socket client can be obtained via SC::SocketServer::accept or connected to an endpoint through SC::SocketClient::connect.

Example (accepted client from server, doing a synchronous read):

    SocketDescriptor acceptedClientSocket;
    // ... assuming to obtain a TCP socket using SocketServer::accept
    SC_TRY(server.accept(family, acceptedClientSocket));
    SC_TRY(acceptedClientSocket.isValid());
 
    // Read some data blocking until it's available
    char buf[256];
 
    SocketClient acceptedClient(acceptedClientSocket);
    Span<char>   readData;
    SC_TRY(acceptedClient.read({buf, sizeof(buf)}, readData));
 
    // ... later on
 
    // Read again blocking but with a timeout of 10 seconds
    SC_TRY(acceptedClient.readWithTimeout({buf, sizeof(buf)}, readData, 10 * 1000));
 
    // Close the client
    SC_TRY(acceptedClientSocket.close());

Example (connecting client to server, doing two synchronous writes):

 
    // ...assuming there is a socket listening at given serverAddress and tcpPort
    SocketDescriptor clientSocket;
    SocketClient     client(clientSocket);
 
    // Create a (TCP) socket
    SC_TRY(clientSocket.create(family));
 
    // [Alternatively] Create an UDP socket instead
    // SC_TRY(clientSocket.create(family, SocketFlags::SocketDgram, SocketFlags::ProtocolUdp));
 
    // Connect to the server
    SC_TRY(client.connect(serverAddress, tcpPort));
 
    // Write some data to the socket
    const int testValue = 1;
    char      buf[1]    = {testValue};
    SC_TRY(client.write({buf, sizeof(buf)}));
    buf[0]++; // change the value and write again
    SC_TRY(client.write({buf, sizeof(buf)}));
 
    // Close the socket
    SC_TRY(clientSocket.close());

SocketIPAddress

Example:

    SocketIPAddress address;
    SC_TEST_EXPECT(not address.fromAddressPort("1223.22.44.1", 6666));
    SC_TEST_EXPECT(address.fromAddressPort("127.0.0.1", 123));
    SC_TEST_EXPECT(address.getPort() == 123);
    SC_TEST_EXPECT(address.fromAddressPort("::1", 456));
    SC_TEST_EXPECT(address.getPort() == 456);
 
    const char  badMemory[]  = "oh yeah that's a really broken socket ip address";
    const auto& badIPAddress = *reinterpret_cast<const SocketIPAddress*>(&badMemory);
    SC_TEST_EXPECT(not badIPAddress.isValid());

SocketDNS

Example:

    char       buffer[256] = {0};
    Span<char> ipAddress   = {buffer};
    SC_TEST_EXPECT(SocketDNS::resolveDNS("localhost", ipAddress));
    StringView ipString = StringView(ipAddress, true, StringEncoding::Ascii);
    SC_TEST_EXPECT(ipString == "127.0.0.1" or ipString == "::1");

Roadmap

🟩 Usable

• Add UDP specific socket operations

🟦 Complete Features:

• To be decided

💡 Unplanned Features:

• None so far

Statistics

Type	Lines Of Code	Comments	Sum
Headers	123	189	312
Sources	608	141	749
Sum	731	330	1061