Skip to content

Commit 0e36832

Browse files
ProgramMaxProgramMax
committed
Adding documentation.
1 parent 2b25c94 commit 0e36832

16 files changed

Lines changed: 454 additions & 48 deletions

‎Code/Common/Include/maxSocket/SocketSystem.hpp‎

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -67,11 +67,8 @@ MAX_CURRENT_VERSION_NAMESPACE_BEGIN( v0 )
6767
OutOfMemory,
6868
NetworkHostExistsButHasNoEndPoints,
6969
UnknownHostName,
70-
EncounteredAnUnknownAddressFamily,
7170
SystemError,
7271
LibraryError,
73-
AuthoritiveAnswerHostNotFound,
74-
ExceededMaximumEndPointSanityCheck,
7572
UnknownError
7673
}; // enum Enum
7774
} // namespace ResolveHostNameResults
@@ -81,15 +78,12 @@ MAX_CURRENT_VERSION_NAMESPACE_BEGIN( v0 )
8178
enum Enum
8279
{
8380
Success,
84-
UnknownIPVersion,
85-
UnknownProtocol,
8681
NoMoreSocketDescriptorsAvailable,
8782
ConnectionRefused,
88-
RemoteHostResetConnection,
83+
ConnectionResetByEndPoint,
8984
TimedOut,
9085
NetworkUnreachable,
91-
RemoteAddressInvalid,
92-
HostUnreachable,
86+
EndPointUnreachable,
9387
NetworkDown,
9488
Interrupted,
9589
NotAuthorized,
@@ -106,18 +100,22 @@ MAX_CURRENT_VERSION_NAMESPACE_BEGIN( v0 )
106100
{
107101
public:
108102

109-
static CreateSocketSystemResults::Enum CreateSocketSystem( std::unique_ptr< SocketSystem > & CreatedSocketSystem ) MAX_DOES_NOT_THROW;
103+
static CreateSocketSystemResults::Enum CreateSocketSystem(
104+
std::unique_ptr< SocketSystem > & CreatedSocketSystem
105+
) MAX_DOES_NOT_THROW;
110106

111107
~SocketSystem() MAX_DOES_NOT_THROW;
112108

113-
ResolveHostNameResults::Enum ResolveHostName( const char * const HostName,
114-
const AddressFamily::Enum AddresFamilyFilter,
115-
IP::Addresses & EndPoints
116-
) MAX_DOES_NOT_THROW;
109+
ResolveHostNameResults::Enum ResolveHostNameUsingOSDefaults(
110+
const char * const HostName,
111+
const AddressFamily::Enum AddresFamilyFilter,
112+
IP::Addresses & EndPoints
113+
) MAX_DOES_NOT_THROW;
117114

118-
CreateSocketAndConnectResults::Enum CreateSocketAndConnect( const IP::Address & EndPoint,
119-
const unsigned short Port,
120-
const Protocol::Enum Protocol,
115+
CreateSocketAndConnectResults::Enum CreateSocketAndConnect(
116+
const IP::Address & EndPoint,
117+
const unsigned short Port,
118+
const Protocol::Enum Protocol,
121119
std::unique_ptr< Socket > & CreatedSocket
122120
) MAX_DOES_NOT_THROW;
123121

‎Code/Linux/SocketSystem.cpp‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,9 @@ namespace maxSocket
5050
namespace v0
5151
{
5252

53-
CreateSocketSystemResults::Enum SocketSystem::CreateSocketSystem( std::unique_ptr< SocketSystem > & CreatedSocketSystem ) MAX_DOES_NOT_THROW
53+
CreateSocketSystemResults::Enum SocketSystem::CreateSocketSystem(
54+
std::unique_ptr< SocketSystem > & CreatedSocketSystem
55+
) MAX_DOES_NOT_THROW
5456
{
5557
CreatedSocketSystem.reset( new SocketSystem() );
5658
return CreateSocketSystemResults::Success;
@@ -60,10 +62,11 @@ namespace v0
6062
{
6163
}
6264

63-
ResolveHostNameResults::Enum SocketSystem::ResolveHostName( const char * const HostName,
64-
const AddressFamily::Enum AddressFamilyFilter,
65-
IP::Addresses & EndPoints
66-
) MAX_DOES_NOT_THROW
65+
ResolveHostNameResults::Enum SocketSystem::ResolveHostNameUsingOSDefaults(
66+
const char * const HostName,
67+
const AddressFamily::Enum AddressFamilyFilter,
68+
IP::Addresses & EndPoints
69+
) MAX_DOES_NOT_THROW
6770
{
6871
//
6972
// Prepare parameters for the call to getaddrinfo.
@@ -135,9 +138,10 @@ namespace v0
135138
return ResolveHostNameResults::Success;
136139
}
137140

138-
CreateSocketAndConnectResults::Enum SocketSystem::CreateSocketAndConnect( const IP::Address & EndPoint,
139-
const unsigned short Port,
140-
const Protocol::Enum Protocol,
141+
CreateSocketAndConnectResults::Enum SocketSystem::CreateSocketAndConnect(
142+
const IP::Address & EndPoint,
143+
const unsigned short Port,
144+
const Protocol::Enum Protocol,
141145
std::unique_ptr< Socket > & CreatedSocket
142146
) MAX_DOES_NOT_THROW
143147
{
@@ -155,7 +159,7 @@ namespace v0
155159
}
156160

157161
auto LinuxSocketType = SOCK_STREAM;
158-
auto LinuxProtocol = IPPROTO_TCP;
162+
auto LinuxProtocol = IPPROTO_TCP;
159163
switch( Protocol )
160164
{
161165
case Protocol::TCP:
@@ -231,7 +235,6 @@ namespace v0
231235
{
232236
case EADDRNOTAVAIL: // The specified address is not available from the local machine.
233237
case EAFNOSUPPORT: // The specified address is not a valid address for the address family of the specified socket.
234-
return CreateSocketAndConnectResults::RemoteAddressInvalid;
235238
case EALREADY: // A connection request is already in progress for the specified socket.
236239
case EBADF: // The socket argument is not a valid file descriptor.
237240
case EINPROGRESS: // O_NONBLOCK is set for the file descriptor for the socket and the connection cannot be immediately established; the connection shall be established asynchronously.
@@ -260,9 +263,9 @@ namespace v0
260263
case EIO: // An I/O error occurred whil reading from or writing to the file system.
261264
return CreateSocketAndConnectResults::SystemError;
262265
case ECONNRESET: // Remote host reset the connection request.
263-
return CreateSocketAndConnectResults::RemoteHostResetConnection;
266+
return CreateSocketAndConnectResults::ConnectionResetByEndPoint;
264267
case EHOSTUNREACH: // The destination host cannot be reached (probably because the host is down or a remote router cannot reach it).
265-
return CreateSocketAndConnectResults::HostUnreachable;
268+
return CreateSocketAndConnectResults::EndPointUnreachable;
266269
case ENETDOWN: // The local network interface used to reach the destinatino is down.
267270
return CreateSocketAndConnectResults::NetworkDown;
268271
case ENOBUFS: // No buffer space is available.

‎Code/Windows/SocketSystem.cpp‎

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,9 @@ namespace maxSocket
4949
namespace v0
5050
{
5151

52-
CreateSocketSystemResults::Enum SocketSystem::CreateSocketSystem( std::unique_ptr< SocketSystem > & CreatedSocketSystem ) MAX_DOES_NOT_THROW
52+
CreateSocketSystemResults::Enum SocketSystem::CreateSocketSystem(
53+
std::unique_ptr< SocketSystem > & CreatedSocketSystem
54+
) MAX_DOES_NOT_THROW
5355
{
5456
auto RequestedVersion = MAKEWORD( 2, 2 );
5557
auto WinsockVersion = WSADATA{};
@@ -92,10 +94,11 @@ namespace v0
9294
WSACleanup();
9395
}
9496

95-
ResolveHostNameResults::Enum SocketSystem::ResolveHostName( const char * const HostName,
96-
const AddressFamily::Enum AddressFamilyFilter,
97-
IP::Addresses & EndPoints
98-
) MAX_DOES_NOT_THROW
97+
ResolveHostNameResults::Enum SocketSystem::ResolveHostNameUsingOSDefaults(
98+
const char * const HostName,
99+
const AddressFamily::Enum AddressFamilyFilter,
100+
IP::Addresses & EndPoints
101+
) MAX_DOES_NOT_THROW
99102
{
100103
//
101104
// Prepare parameters for the call to getaddrinfo.
@@ -169,9 +172,10 @@ namespace v0
169172
return ResolveHostNameResults::Success;
170173
}
171174

172-
CreateSocketAndConnectResults::Enum SocketSystem::CreateSocketAndConnect( const IP::Address & EndPoint,
173-
const unsigned short Port,
174-
const Protocol::Enum Protocol,
175+
CreateSocketAndConnectResults::Enum SocketSystem::CreateSocketAndConnect(
176+
const IP::Address & EndPoint,
177+
const unsigned short Port,
178+
const Protocol::Enum Protocol,
175179
std::unique_ptr< Socket > & CreatedSocket
176180
) MAX_DOES_NOT_THROW
177181
{
@@ -275,19 +279,19 @@ namespace v0
275279
// This just means the socket is async and we don't know if it connected yet.
276280
break;
277281

278-
case WSAECONNREFUSED: // unable to connect
282+
case WSAECONNREFUSED: // unable to connect
279283
return CreateSocketAndConnectResults::ConnectionRefused;
280-
case WSAETIMEDOUT: // timed out
284+
case WSAETIMEDOUT: // timed out
281285
return CreateSocketAndConnectResults::TimedOut;
282286
case WSAENETUNREACH:
283287
return CreateSocketAndConnectResults::NetworkUnreachable;
284-
case WSAEADDRNOTAVAIL: // remote address is not valid
288+
case WSAEADDRNOTAVAIL: // remote address is not valid
285289
return CreateSocketAndConnectResults::RemoteAddressInvalid;
286-
case WSAEAFNOSUPPORT: // address in specified family cannot be used
287-
// (perhaps using an IPv6 address for an IPv4 family
290+
case WSAEAFNOSUPPORT: // address in specified family cannot be used
291+
// (perhaps using an IPv6 address for an IPv4 family
288292
return CreateSocketAndConnectResults::LibraryError;
289-
case WSAEHOSTUNREACH: // unreachable host
290-
return CreateSocketAndConnectResults::HostUnreachable;
293+
case WSAEHOSTUNREACH: // unreachable host
294+
return CreateSocketAndConnectResults::EndPointUnreachable;
291295
case WSAENETDOWN:
292296
return CreateSocketAndConnectResults::NetworkDown;
293297

‎Documentation/Code/v0.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# v0
2+
3+
This API version is not yet stable. Do not use this version as a protection against API change.
4+
5+
## What is it?
6+
7+
maxSocket's API is versioned.
8+
9+
This means as the API is improved over time we will not break your code.
10+
11+
The latest version will be pulled into the maxSocket namespace. That way you may chose to use the latest version and be notified via compiler errors when the API changes.
12+
13+
But if instead you prefer to upgrade when you are ready, you can use a specific version. In the case of v0, this is in the namespace maxSocket::v0.
14+
15+
However, **v0 is not yet stable**. It is likely to change.

‎Documentation/Code/v0/SocketSystem.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# SocketSystem
2+
3+
API version: [**v0**](../v0.md)
4+
5+
## What is it?
6+
7+
The SocketSystem class is the starting point for all of maxSocket.
8+
9+
A developer starts using maxSocket by calling [CreateSocketSystem](SocketSystem_CreateSocketSystem.md).
10+
11+
From there, a developer may choose to resolve a host name via [ResolveHostNameUsingOSDefaults](SocketSystem_ResolveHostNameUsingOSDefaults.md) and/or
12+
connect to an end point via [CreateSocketAndConnect](SocketSystem_CreateSocketAndConnect.md).
13+
14+
## Note
15+
16+
Even though some methods of socket communication are considered connectionless (they do not perform a handshake nor maintain state), maxSocket uses the word "connect" to mean establish a route to the end point.
17+
18+
So a developer would call [CreateSocketAndConnect](SocketSystem_CreateSocketAndConnect.md) even when creating a UDP socket.
19+
20+
## Methods of interest
21+
22+
* [CreateSocketSystem](SocketSystem_CreateSocketSystem.md)
23+
* [ResolveHostNameUsingOSDefaults](SocketSystem_ResolveHostNameUsingOSDefaults.md)
24+
* [CreateSocketAndConnect](SocketSystem_CreateSocketAndConnect.md)
25+
26+
## Less interesting methods
27+
28+
* [~SocketSystem (destructor)](SocketSystem_dtor.md)

‎Documentation/Code/v0/SocketSystem_CreateSocketAndConnect.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# SocketSystem::CreateSocketAndConnect
2+
3+
API version: [**v0**](../v0.md)
4+
5+
## What is it?
6+
7+
This method will create a socket and connect to the spefied end point.
8+
9+
This is a method of [SocketSystem](SocketSystem.md).
10+
11+
## Note
12+
13+
In this context, "connect" means setup a line of communication to the end point. A protocol which is said to be connectionless (does not perform a handshake nor maintain state) such as UDP will still needs to be setup.
14+
15+
The actual socket communication has not yet been polished. As a consequence, this function is likely to change soon.
16+
17+
## Signature
18+
19+
```c++
20+
CreateSocketAndConnectResults::Enum SocketSystem::CreateSocketAndConnect(
21+
const IP::Address & EndPoint,
22+
const unsigned short Port,
23+
const Protocol::Enum Protocol,
24+
std::unique_ptr< Socket > & CreatedSocket
25+
) MAX_DOES_NOT_THROW;
26+
```
27+
28+
## Parameters
29+
30+
* **EndPoint**
31+
* This is the end point to which a connection will be established.
32+
* **Port**
33+
* This is the port at the end point to connect to.
34+
* **Protocol**
35+
* Specifies which protocol to connect using:
36+
37+
| value | Description |
38+
| --- | --- |
39+
| Protocol::TCP | will perform a handshake, attempt to keep messages ordered, and notify when the end point can no longer be reached. |
40+
| Protocol::UDP | will only touch the network when instructed to but does not know if the message was received. |
41+
42+
* **CreatedSocket**
43+
* On success, this is populated with the socket which was created and connected.
44+
* If this parameter previously referenced another socket, that socket will be destroyed.
45+
46+
## Returns
47+
48+
* On success, returns **CreateSocketAndConnectResults::Success**
49+
* On error, returns:
50+
51+
| Value | Description |
52+
| --- | --- |
53+
| **CreateSocketAndConnectResults::SystemError** | when the system does not support the type of connection requested. |
54+
| **CreateSocketAndConnectResults::NoMoreSocketDescriptorsAvailable** | when there are not enough socket descriptors left for the system fulfill the request. |
55+
| **CreateSocketAndConnectResults::NotAuthorized** | when the process does not have permission to create the requested socket. |
56+
| **CreateSocketAndConnectResults::OutOfMemory** | when the system does not have enough memory to fulfill the request. |
57+
| **CreateSocketAndConnectResults::ConnectionRefused** | when the end point turned down the connection. |
58+
| **CreateSocketAndConnectResults::TimedOut** | when the connection to the end point did not complete in time. |
59+
| **CreateSocketAndConnectResults::NetworkUnreachable** | when the underlying network cannot be reached. |
60+
| **CreateSocketAndConnectResults::EndPointUnreachable** | when the end point cannot be reached. |
61+
| **CreateSocketAndConnectResults::NetworkDown** | when the underlying network has gone down. |
62+
| **CreateSocketAndConnectResults::ConnectionResetByEndPoint** | when the underlying network has gone down. |
63+
| **CreateSocketAndConnectResults::Interrupted** | when the connection was interrupted by a system event. |
64+
| **CreateSocketAndConnectResults::LibraryError** | when there is an error in maxSocket's logic. Please notify us if you ever see a LibraryError. |
65+
| **CreateSocketAndConnectResults::UnknownError** | when there is an error maxSocket is not aware of. Please notify us if you ever see an UnknownError. |

‎Documentation/Code/v0/SocketSystem_CreateSocketSystem.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# SocketSystem::CreateSocketSystem
2+
3+
API version: [**v0**](../v0.md)
4+
5+
## What is it?
6+
7+
Before a developer can use maxSocket they must create a [SocketSystem](SocketSystem.md) by calling **SocketSystem::CreateSocketSystem**.
8+
9+
## Signature
10+
11+
```c++
12+
static CreateSocketSystemResults::Enum SocketSystem::CreateSocketSystem(
13+
14+
std::unique_ptr< SocketSystem > & CreatedSocketSystem
15+
16+
) MAX_DOES_NOT_THROW;
17+
```
18+
19+
## Parameters
20+
21+
* **CreatedSocketSystem**
22+
* On success, this parameter will be populated with the created SocketSystem.
23+
* If this parameter previously referenced a SocketSystem, that SocketSystem will be destroyed.
24+
25+
## Returns
26+
27+
* On success, returns **CreateSocketSystemResults::Success**
28+
* On error, returns:
29+
30+
| Value | Description |
31+
| --- | --- |
32+
| **CreateSocketSystemResults::SystemIsNotReady** | when the underlying network system is not ready. A developer can try again later. |
33+
| **CreateSocketSystemResults::NoSystemSupport** | when the OS does not meet the minimum requirements for maxSocket. |
34+
| **CreateSocketSystemResults::LibraryError** | when there is an error in maxSocket's logic. Please notify us if you ever see a LibraryError. |
35+
| **CreateSocketSystemResults::UnknownError** | when there is an error maxSocket is not aware of. Please notify us if you ever see an UnknownError. |
36+
37+
## Example
38+
39+
```c++
40+
auto SocketSystem = std::unique_ptr< maxSocket::SocketSystem >{};
41+
auto CreateSocketSystemResult = maxSocket::SocketSystem::CreateSocketSystem( SocketSystem );
42+
if( CreateSocketSystemResult != maxSocket::CreateSocketSystemResults::Success )
43+
{
44+
// error
45+
}
46+
```

0 commit comments

Comments
 (0)