Create common API for sockets

[EvilLord666]

We should review our demands and after that we could understand how API should look.
Basically, we must have common C API and 3 C implementations (Linux, Unix, Windows). Implementations that including conditionally on what OS is selected (Have not understood all details completely). Also I think there should be C++ wrapping (03 and 11) for C++ programs.

Library must be lightweight as possible (without any synch primitives, threads and so on).

[Edisson]

in which particular document here we should write API stuff?

[Edisson]

EasySocket has to work equally on supported platforms.

It should provide interface for work with TCP/UDP protocols, as well as for IPv4, IPv6
(it could be inherited classes TcpSocket, UdpSocket that are inherited from AbstractSocket)

Easy interface for connection to host

probably it would be great to implement methods for
reading and setting buffer size
reading and setting socket options (such as SO_KEEPALIVE, TCP_NODELAY, SO_SNDBUF, SO_RECVBUF, etc)

Easy access to the state of socket.

[Edisson]

bool connectToHost(const string hostName, int port, OpenMode openMode, NetworkProtocol protocol, int &error);

method connectToHost attempts to make a connection to hostName on the given port. The protocol parameter can be used to specify which network protocol to use (IPv4 or IPv6).

enum NetworkProtocol { IPv4Protocol, IPv6Protocol, AnyIPProtocol... }
enum OpenMode { NotOpen, ReadOnly, WriteOnly, ReadWrite...}

hostName may be an IP address in string form ("10.0.0.1"), or it may be a host name ("easysock.com"). Port is in native byte order.

bool connectToHost(const string hostName, int port, OpenMode openMode = ReadWrite, int &error)

This is an overloaded function and attempts to make a connection to address on port port.

void disconnectFromHost()

Attempts to close the socket. As I know If there is pending data waiting to be written, socket will enter in sort of "closing state" and wait until all data has been written. Eventually, it will switch to unconnected state.

void close()

Close the current connection of socket. And assumably discarding any pending data in the write buffer.

bool isValid() const

Returns true if the socket is valid and ready for use otherwise returns false.

in implementation: if we pass socket to any one of the windows socket functions (for example getsockopt()), if the socket is invalid, it will return SOCKET_ERROR while WSAGetLastError() will return WSAENOTSOCK. It is important to note that INVALID_SOCKET does not equal 0.

to be continued...

[Edisson]

Also we need to create a unified cross-platform classification of errors, 'cos it's not similar for different os's

SocketError error() const

Returns the type of error that last occurred.

I would suggest creating firstly a set of general codes:

Error name	Code	Description
ConnectionRefusedError	0	The connection was refused by the peer (or timed out).
RemoteHostClosedError	1	The remote host closed the connection. Note that the client socket (i.e., this socket) will be closed after the remote close notification has been sent.
HostNotFoundError	2	The host address was not found.
SocketAccessError	3	The socket operation failed because the application lacked the required privileges.
SocketResourceError	4	The local system ran out of resources (e.g., too many sockets).
SocketTimeoutError	5	The socket operation timed out.
DatagramTooLargeError	6	The datagram was larger than the operating system's limit (which can be as low as 8192 bytes).
NetworkError	7	An error occurred with the network (e.g., the network cable was accidentally plugged out).
SocketAddressNotAvailableError	8	The address specified to QAbstractSocket::bind() does not belong to the host.
UnsupportedSocketOperationError	9	The requested socket operation is not supported by the local operating system (e.g., lack of IPv6 support).
UnfinishedSocketOperationError	10	Used by QAbstractSocketEngine only, The last operation attempted has not finished yet (still in progress in the background).
OperationError	11	An operation was attempted while the socket was in a state that did not permit it.
TemporaryError	12	A temporary error occurred (e.g., operation would block and socket is non-blocking).
UnknownSocketError	-1	An unidentified error occurred.

[Edisson]

SocketState state() const

return state of socket:

enum SocketState

State name	Code	Description
UnconnectedState	0	The socket is not connected.
HostLookupState	1	The socket is performing a host name lookup.
ConnectingState	2	The socket has started establishing a connection.
ConnectedState	3	A connection is established.
BoundState	4	The socket is bound to an address and port.
ClosingState	6	The socket is about to close (data may still be waiting to be written).
ListeningState	5	For internal use only.

[EvilLord666]

Some function in my branch i added but we clearly must separate common functions, client and server ones.

[EvilLord666]

The main task is to create common socket data : socket number (some OS descriptor), socket network address (ip 4/6, and port for server).

[EvilLord666]

Posiibly as you written before could be some socket state as int (which is mapping for WinSocks to enum that you have posted previously).