Socket Class

gxSocket is a TCP and UDP socket for IPv4 and IPv6. gxsAddress holds a resolved address.

Contents

Overview
gxsAddress Functions
Connection Functions
Data Transfer Functions
Information and Error Functions

Overview

gxSocket owns one socket handle and closes it when it is destroyed. It can be moved but not copied. Client sockets are opened with Connect(), which resolves the host name with getaddrinfo() and tries each address in turn with a connection timeout. Server sockets are opened with Listen(); with no bind address it listens on one dual-stack IPv6 socket that also accepts IPv4 clients. Accept() returns each client as a new gxSocket.

Most applications should use gxsTLSConnection, which adds TLS. Use gxSocket directly only for protocols that cannot be encrypted. On Windows, Winsock 2 is started the first time a socket is created. On Linux, sends use MSG_NOSIGNAL so a closed peer returns an error instead of raising SIGPIPE.

Functions that return int return 0 (gxSOCKET_NO_ERROR) on success, or a gxSocketError code. SocketExceptionMessage() describes the last error and SystemError() gives the errno or WSAGetLastError() value behind it.

gxSocket server;
if(server.Listen(8080) != 0) return 1;
gxSocket client = server.Accept();
std::cout << "Client " << client.PeerAddress().ToString() << "\n";

gxsAddress Functions

static int gxsAddress::Resolve(const std::string &host, int port, std::vector<gxsAddress> &addresses, int socket_type = SOCK_STREAM, int family = AF_UNSPEC, bool passive = false)

Resolves a host name or numeric address. family is AF_UNSPEC, AF_INET or AF_INET6. With passive true and an empty host, the wildcard address for binding is returned. Returns 0 or the getaddrinfo() error code.

int gxsAddress::Family() const

Returns AF_INET or AF_INET6.

int gxsAddress::Port() const

Returns the port number.

void gxsAddress::SetPort(int port)

Sets the port number.

std::string gxsAddress::IPAddress() const

Returns the numeric address, such as 192.0.2.1 or 2001:db8::1.

std::string gxsAddress::ToString() const

Returns the address and port, such as 192.0.2.1:80 or [2001:db8::1]:80.

sockaddr *gxsAddress::SockAddr()

Returns the address for socket API calls. Length() gives its size.

Connection Functions

int gxSocket::Connect(const std::string &host, int port, int timeout_sec = 30, int family = AF_UNSPEC)

Connects to host:port, trying each resolved address. timeout_sec limits each attempt; 0 waits for the operating system timeout.

int gxSocket::Listen(int port, const std::string &bind_address = std::string(), int max_connections = SOMAXCONN, int family = AF_UNSPEC)

Binds and listens. An empty bind_address listens on every interface, IPv6 and IPv4.

gxSocket gxSocket::Accept()

Waits for a client and returns its connection. The returned socket is not open (IsOpen() is false) if an error occurred.

int gxSocket::OpenDatagram(int family = AF_INET6, int port = 0, const std::string &bind_address = std::string())

Opens a UDP socket, bound to port when it is above 0.

int gxSocket::SendTo(const gxsAddress &to, const void *buf, int bytes)

Sends a datagram. Returns the bytes sent or -1.

int gxSocket::RecvFrom(gxsAddress &from, void *buf, int bytes, int timeout_sec = -1)

Receives a datagram and its sender. Returns the bytes received or -1.

void gxSocket::Close()

Closes the socket.

gxsSocket_t gxSocket::Release()

Gives up ownership of the socket handle without closing it.

void gxSocket::ShutDown(int how)

Calls shutdown() on the socket.

Data Transfer Functions

int gxSocket::Send(const void *buf, int bytes)

Sends every byte. Returns the number of bytes sent or -1 on an error.

int gxSocket::RecvSome(void *buf, int bytes, int timeout_sec = -1)

Receives up to bytes, waiting at most timeout_sec seconds (-1 waits forever). Returns the bytes received, 0 if the peer closed the connection, or -1 on an error or timeout.

int gxSocket::Recv(void *buf, int bytes, int timeout_sec = -1)

Receives exactly bytes unless the connection closes, an error occurs or the timeout passes. Returns the number of bytes received.

int gxSocket::RawRead(void *buf, int bytes)

One recv() call.

int gxSocket::RawWrite(const void *buf, int bytes)

One send() call.

int gxSocket::WaitReadable(int timeout_ms)

Returns 1 when the socket is readable, 0 on a timeout and -1 on an error. A static version takes a socket handle.

Information and Error Functions

const gxsAddress &gxSocket::PeerAddress() const

Address of the connected peer.

gxsAddress gxSocket::LocalAddress() const

Local address of the socket. LocalPort() returns its port.

static std::string gxSocket::HostName()

Returns the local host name.

int gxSocket::SetNoDelay(bool on = true)

Sets TCP_NODELAY.

int gxSocket::SetKeepAlive(bool on = true)

Sets SO_KEEPALIVE.

gxSocketError gxSocket::GetSocketError() const

Returns the last error code.

const char *gxSocket::SocketExceptionMessage() const

Returns a description of the last error.

int gxSocket::SystemError() const

Returns the errno or WSAGetLastError() value for the last error.