ADTF
cSocket

Socket class. More...

Inheritance diagram for cSocket:
[legend]

Public Types

enum  tOpenMode { OM_Block = 0x0 , OM_NonBlock = 0x01 }
 The mode in which to run the sockets during and after a connection. More...
 
enum  tShutdownMode { SM_Read = 0 , SM_Write = 1 , SM_ReadWrite = 2 }
 The mode in which to switch the sockets to on shutdown. More...
 
enum  tOptionLevel { OL_SOCKET = 1 , OL_IPPROTO_TCP = 2 , OL_IPPROTO_IP = 3 }
 Abstraction of the system specific socket option levels (e.g. More...
 
enum  tOptionId {
  OI_DEBUG , OI_BROADCAST , OI_REUSEADDR , OI_KEEPALIVE ,
  OI_LINGER , OI_SNDBUF , OI_RCVBUF , OI_DONTROUTE ,
  OI_TCP_NODELAY , OI_IP_MULTICAST_LOOP
}
 Abstraction of the system specific socket options (e.g. More...
 

Public Member Functions

 cSocket ()
 Default constructor.
 
virtual ~cSocket ()
 Default destructor.
 
tVoid Close ()
 Closes the socket and frees all resources. More...
 
tVoid Close (tShutdownMode nHow)
 Closes the socket and frees all resources. More...
 
tUInt32 GetAddress () const
 Retrieves the IP address of the socket. More...
 
tInt GetPort () const
 Retrieves the port of the socket. More...
 
tSocketHandle GetHandle () const
 Get the internal socket handle. More...
 
tBool SetTimeout (tTimeStamp nReadTimeout=-1, tTimeStamp nWriteTimeout=-1)
 Sets timouts fo the read and write socket operations. More...
 
virtual tBool IsConnected (tTimeStamp nTimeout=0)
 Polls the socket for its connection state. More...
 
tBool DataAvailable ()
 Check if data is available for reading (a subsequent read succeed immediately). More...
 
tBool WaitForData (tTimeStamp nTimeout=-1)
 Blocks the current process until data is available for reading. More...
 
tInt SetOption (tInt nLevel, tInt nOptionId, const tVoid *pValue, tInt nValueLen)
 Sets a specific option for the socket. More...
 
tInt SetOption (cSocket::tOptionLevel eLevel, cSocket::tOptionId eId, const tVoid *pValue, tInt nValueLen)
 Equivalent to SetOption (tInt, tInt, const tVoid*, tInt) Instead of the system specific constants (e.g. More...
 
tResult GetOption (tInt nLevel, tInt nOptionId, tVoid *o_pValue, tInt *o_pValueLen)
 gets a specific option for the socket. More...
 
tResult GetOption (cSocket::tOptionLevel eLevel, cSocket::tOptionId eId, tVoid *o_pValue, tInt *o_pValueLen)
 Equivalent with GetOption(tInt, tInt, tVoid*, tInt*). More...
 

Static Public Member Functions

static tVoid AddLibraryRef ()
 for the work with the static methods you have to use this function to load the nessessary libs, after work ReleaseLibraryRef has to be called.
 
static tVoid ReleaseLibraryRef ()
 to correctly unload the socket-libs you have to call this function
 
static cString GetHostName (tUInt32 dwHostAddress=0)
 Returns the hostname for a given address. More...
 
static tUInt32 GetHostAddress (const cString &strHostName=cString())
 Returns the address for a given hostname. More...
 
static tUInt32 AddressToUInt32 (const cString &strAddress)
 Converts a aaa.bbb.ccc.ddd formated address string to an integer. More...
 
static cString UInt32ToAddress (tUInt32 ui32Address)
 Converts an integer to an aaa.bbb.ccc.ddd formated address string. More...
 
static tInt GetLastErrorCode ()
 Gets the error code of the last failure. More...
 
static tResult GetLocalAddresses (std::set< tUInt32, std::less< tUInt32 >, std::allocator< tUInt32 > > &oAddresses)
 Returns a list of addresses from all local interfaces. More...
 
static tResult SocketError (tInt nSocketError)
 Maps a socket error to an A_UTILS error. More...
 
static tResult FindInterfaceForAddress (tUInt32 ui32FarAddress, tUInt32 &ui32LocalAddress)
 If more than one network interface is used in the host the FindInterfaceForAddress finds out the local address of the interface where the far address is reachable. More...
 
static tResult WaitForData (const std::list< cSocket * > &i_lstSockets, cSocket **o_ppSocket, tTimeStamp tmTimeOut=-1)
 Blocks the current thread until data are available for reading in at least one of i_lstSockets. More...
 

Static Public Attributes

static const tUInt32 SOCKET_NO_ADDRESS
 Constance for check No Address.
 

Protected Member Functions

tBool Initialize ()
 Sets the params for the socket with 0/nullptr. More...
 
tInt ResolveOptionLevel (tOptionLevel level) const
 Resolve the option value of the socket. More...
 
tInt ResolveOptionId (tOptionId id) const
 Resolve the option id of the socket. More...
 

Protected Attributes

tSocketHandle m_hSocket
 this is internal handle of the socket, only use it if you really need that!!
 
tUInt32 m_ui32Address
 Address of the socket (valid only if opened)
 
tInt m_nPort
 Port of the socket (valid only if opened)
 

Static Private Attributes

static std::atomic< tIntm_nSocketLibInitCounter
 For internal use only.
 

Detailed Description

Socket class.

Remarks
If only static methods are used (no cSocket instance is created), you have manually load (AddLibraryRef()) and unload (ReleaseLibraryRef() the socket lib. Please note that you can adjust the socket options. This may help you e.g. if you discover that data is missing (see SetOption).

Definition at line 23 of file socket.h.

Member Enumeration Documentation

◆ tOpenMode

enum tOpenMode

The mode in which to run the sockets during and after a connection.

The blocking mode is the default mode and suspends the thread until a Read or Write call can either actually be completed or runs into a predefined read/write timeout (infinity by default). When calling Connect in blocking mode, an internal timeout will be used. On Windows this appears to be around 30 seconds whereas on Linux this tends to be around 2-5 seconds and is not to be confused with the read/write timeout which does not apply here.

In non-blocking mode, however, Connect returns immediately and a connection has to be checked for a successful establishment by calling IsConnected() (applies to StreamSockets only) Subsequent Read and Write calls will return immediately as well, however, possible return codes yielding failed operations do not imply a generally failed socket but only, that no data is currently available. For convenience use WaitForData() to periodically poll the socket for data.

Note
: Switching mode applies globally to a socket instance and cannot be changed in between connect and read/write operations.

Definition at line 69 of file socket.h.

◆ tOptionId

enum tOptionId

Abstraction of the system specific socket options (e.g.

SO_RCVBUF)

Enumerator
OI_DEBUG 

Equivalent with SO_DEBUG.

OI_BROADCAST 

Equivalent with SO_BROADCAST.

OI_REUSEADDR 

Equivalent with SO_REUSEADDR.

OI_KEEPALIVE 

Equivalent with SO_KEEPALIVE.

OI_LINGER 

Equivalent with SO_LINGER.

OI_SNDBUF 

Equivalent with SO_SNDBUF.

OI_RCVBUF 

Equivalent with SO_RCVBUF.

OI_DONTROUTE 

Equivalent with SO_DONTROUTE.

OI_TCP_NODELAY 

Equivalent with TCP_NODELAY.

OI_IP_MULTICAST_LOOP 

Equivalent with IP_MULTICAST_LOOP.

Definition at line 247 of file socket.h.

◆ tOptionLevel

Abstraction of the system specific socket option levels (e.g.

SOL_SOCKET)

Enumerator
OL_SOCKET 

Equivalent with SOL_SOCKET.

OL_IPPROTO_TCP 

Equivalent with IPPROTO_TCP.

OL_IPPROTO_IP 

Equivalent with IPPROTO_IP.

Definition at line 235 of file socket.h.

◆ tShutdownMode

The mode in which to switch the sockets to on shutdown.

This has significant effect on error codes thrown on the remote side.

Definition at line 80 of file socket.h.

Member Function Documentation

◆ AddressToUInt32()

static tUInt32 AddressToUInt32 ( const cString strAddress)
static

Converts a aaa.bbb.ccc.ddd formated address string to an integer.

Parameters
strAddressthe address string to convert.
Returns
the address.
Return values
SOCKET_NO_ADDRESSif strAddress is not a valid IPv4 address.
This method is real-time safe.\nSee @ref page_real_time_safe.\n

◆ Close() [1/2]

tVoid Close ( )

Closes the socket and frees all resources.

Returns
void

◆ Close() [2/2]

tVoid Close ( tShutdownMode  nHow)

Closes the socket and frees all resources.

Note
Extends cSocket::Close()
Parameters
[in]nHowParameter on how to close the socket.
Returns
void

◆ DataAvailable()

tBool DataAvailable ( )

Check if data is available for reading (a subsequent read succeed immediately).

Returns
tTrue if data is available, tFalse otherwise.

◆ FindInterfaceForAddress()

static tResult FindInterfaceForAddress ( tUInt32  ui32FarAddress,
tUInt32 ui32LocalAddress 
)
static

If more than one network interface is used in the host the FindInterfaceForAddress finds out the local address of the interface where the far address is reachable.

Remarks
: The far address must be in the same network. Only the same subnet is estimated.
Parameters
[in]ui32FarAddressThe Address you want to reach
[in]ui32LocalAddressreturn value of the local address of the interface
Returns
Matching A_UTILS error

◆ GetAddress()

tUInt32 GetAddress ( ) const

Retrieves the IP address of the socket.

Returns
the IP address of the socket.
This method is real-time safe.\nSee @ref page_real_time_safe.\n

◆ GetHandle()

tSocketHandle GetHandle ( ) const

Get the internal socket handle.

Returns
internal socket handle.
This method is real-time safe.\nSee @ref page_real_time_safe.\n

◆ GetHostAddress()

static tUInt32 GetHostAddress ( const cString strHostName = cString())
static

Returns the address for a given hostname.

Parameters
strHostNamethe hostname.
Returns
The address.
Return values
0Address not found.
See also
AddLibraryRef
ReleaseLibraryRef

◆ GetHostName()

static cString GetHostName ( tUInt32  dwHostAddress = 0)
static

Returns the hostname for a given address.

Use

Parameters
dwHostAddressthe interface address, if 0 -> localhost.
Returns
the hostname. An empty string will returned in case of an error.
See also
AddLibraryRef
ReleaseLibraryRef

◆ GetLastErrorCode()

static tInt GetLastErrorCode ( )
static

Gets the error code of the last failure.

Returns
The error code of the last failure.

◆ GetLocalAddresses()

static tResult GetLocalAddresses ( std::set< tUInt32, std::less< tUInt32 >, std::allocator< tUInt32 > > &  oAddresses)
static

Returns a list of addresses from all local interfaces.

Parameters
[out]oAddressesThe list of addresses.
Returns
Standard result.

◆ GetOption() [1/2]

tResult GetOption ( cSocket::tOptionLevel  eLevel,
cSocket::tOptionId  eId,
tVoid o_pValue,
tInt o_pValueLen 
)

Equivalent with GetOption(tInt, tInt, tVoid*, tInt*).

Instead of the system specific constants (e.g. SOL_SOCKET) use cSocket::tOptionLevel and cSocket::tOptionId

Parameters
[in]eLeveloption level, allowed values:
See also
cSocket::tOptionLevel
Parameters
[in]eIdoption id, allowed values (in terms of platform independence):
See also
cSocket::tOptionId
Parameters
[out]o_pValuereturn value of the given option id
[out]o_pValueLensize of the returned value
Return values
ERR_NOERROReverything is OK
ERR_UNKNOWNsomething went wrong

◆ GetOption() [2/2]

tResult GetOption ( tInt  nLevel,
tInt  nOptionId,
tVoid o_pValue,
tInt o_pValueLen 
)

gets a specific option for the socket.

For further information about the GetOption method have a look at your manpage (getsockopt)

Parameters
[in]nLeveloption level, e.g. SOL_SOCKET
[in]nOptionIdoption id, allowed values (in terms of platform independence) are:
  • SO_DEBUG
  • SO_BROADCAST
  • SO_REUSEADDR
  • SO_KEEPALIVE
  • SO_LINGER
  • SO_SNDBUF
  • SO_RCVBUF
  • SO_DONTROUTE
[out]o_pValuereturn value of the given nOptionId
[out]o_pValueLensize of the returned value
Return values
ERR_NOERROReverything is OK
ERR_UNKNOWNsomething went wrong

◆ GetPort()

tInt GetPort ( ) const

Retrieves the port of the socket.

Returns
the port of the socket.
This method is real-time safe.\nSee @ref page_real_time_safe.\n

◆ Initialize()

tBool Initialize ( )
protected

Sets the params for the socket with 0/nullptr.

Returns
tTrue

◆ IsConnected()

virtual tBool IsConnected ( tTimeStamp  nTimeout = 0)
virtual

Polls the socket for its connection state.

This is particularly useful when running the sockets in non-blocking mode and Connect() has returned with ERR_TIMEOUT (which does not necessarily imply a failed connection).

Note
: The current connection is being verified in read and write direction! If using a connection-based socket, please see cServerSocket::IsConnected() and cStreamSocket::IsConnected() respectively! Otherwise, using this method will require active traffic on the socket object when calling.
Parameters
nTimeoutThe timeout after which the connection is deemed to have failed.
Returns
tTrue if the connection has found to be established successfully in both directions, implying that the remote socket accepted the TCP handshake and is already transmitting traffic on our local socket. In case of UDP this only implies an opened datagram socket.
tFalse if the connection has actually failed.

Reimplemented in cServerSocket, and cStreamSocket.

◆ ResolveOptionId()

tInt ResolveOptionId ( tOptionId  id) const
protected

Resolve the option id of the socket.

Parameters
[in]idsystem specific socket option
Returns
the resolved option

◆ ResolveOptionLevel()

tInt ResolveOptionLevel ( tOptionLevel  level) const
protected

Resolve the option value of the socket.

Parameters
[in]levelsystem specific socket option level
Returns
the resolved option level

◆ SetOption() [1/2]

tInt SetOption ( cSocket::tOptionLevel  eLevel,
cSocket::tOptionId  eId,
const tVoid pValue,
tInt  nValueLen 
)

Equivalent to SetOption (tInt, tInt, const tVoid*, tInt) Instead of the system specific constants (e.g.

SOL_SOCKET) use cSocket::tOptionLevel and cSocket::tOptionId

Parameters
[in]eLeveloption level, allowed values:
See also
cSocket::tOptionLevel
Parameters
[in]eIdoption id, allowed values (in terms of platform independence):
See also
cSocket::tOptionLevel
Parameters
[in]pValuepointer to the new value
[in]nValueLensize of the data pointed to by pValue
Returns
returns an option specific return value.
Remarks
If you recognize e.g. that data is missing you can try to adjust the size of the receive buffer with the following command: tInt nRcvBuf = 8192; // Send buffer size MySocket.SetOption(cSocket::L_SOCKET, cSocket::RCVBUF, &nRcvBuf, sizeof nRcvBuf);

◆ SetOption() [2/2]

tInt SetOption ( tInt  nLevel,
tInt  nOptionId,
const tVoid pValue,
tInt  nValueLen 
)

Sets a specific option for the socket.

For further information about SetOption have a look at your manpage,... for setsockopt

Parameters
[in]nLeveloption level, e.g. SOL_SOCKET
[in]nOptionIdoption id, allowed values ( in terms of platform independence) are:
  • SO_DEBUG
  • SO_BROADCAST
  • SO_REUSEADDR
  • SO_KEEPALIVE
  • SO_LINGER
  • SO_SNDBUF
  • SO_RCVBUF
  • SO_DONTROUTE
[in]pValuepointer to the new value.
[in]nValueLensize of the data pointed to by pValue.
Returns
returns an option specific return value.
Remarks
If you recognize e.g. that data is missing you can try to adjust the size of the receive buffer with the following command: tInt nRcvBuf = 8192; // Send buffer size MySocket.SetOption(SOL_SOCKET, SO_RCVBUF, &nRcvBuf, sizeof nRcvBuf);

◆ SetTimeout()

tBool SetTimeout ( tTimeStamp  nReadTimeout = -1,
tTimeStamp  nWriteTimeout = -1 
)

Sets timouts fo the read and write socket operations.

Parameters
nReadTimeoutthe timeout for read operations (microseconds).
nWriteTimeoutthe timeout for write operations (microseconds).
Returns
tTrue if successful, tFalse otherwise.

◆ SocketError()

static tResult SocketError ( tInt  nSocketError)
static

Maps a socket error to an A_UTILS error.

Parameters
[in]nSocketErrorsocket error returned by any socket function
Returns
Matching A_UTILS error

◆ UInt32ToAddress()

static cString UInt32ToAddress ( tUInt32  ui32Address)
static

Converts an integer to an aaa.bbb.ccc.ddd formated address string.

Parameters
ui32Addressthe address to convert.
Returns
the address string.

◆ WaitForData() [1/2]

static tResult WaitForData ( const std::list< cSocket * > &  i_lstSockets,
cSocket **  o_ppSocket,
tTimeStamp  tmTimeOut = -1 
)
static

Blocks the current thread until data are available for reading in at least one of i_lstSockets.

Parameters
[in]i_lstSocketsList of Sockets checked for data
[out]o_ppSocketfirst cSocket Pointer to the cSocket out of i_lstSockets
[in]tmTimeOutMaximum time to wait in microseconds, -1 = forever.
Returns
Standard Error Code.
Return values
ERR_POINTERo_pSocket is set to nullptr

◆ WaitForData() [2/2]

tBool WaitForData ( tTimeStamp  nTimeout = -1)

Blocks the current process until data is available for reading.

Parameters
nTimeoutMaximum time to wait in microseconds, -1 = forever.
Returns
true if data is available, false otherwise.