Socket class. More...

Inheritance diagram for cSocket:

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< tInt >	m_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

enum 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

enum 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

strAddress the address string to convert.

Returns: the address.

Return values

SOCKET_NO_ADDRESS if 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] nHow Parameter 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]	ui32FarAddress	The Address you want to reach
[in]	ui32LocalAddress	return 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

strHostName the hostname.

Returns: The address.

Return values

0	Address not found.

See also: AddLibraryRef; ReleaseLibraryRef

◆ GetHostName()

static cString GetHostName ( tUInt32 dwHostAddress = 0 )

static

Returns the hostname for a given address.

Use

Parameters

dwHostAddress the 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] oAddresses The 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] eLevel option level, allowed values:

See also: cSocket::tOptionLevel

Parameters

[in] eId option id, allowed values (in terms of platform independence):

See also: cSocket::tOptionId

Parameters

[out]	o_pValue	return value of the given option id
[out]	o_pValueLen	size of the returned value

Return values

ERR_NOERROR	everything is OK
ERR_UNKNOWN	something 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]	nLevel	option level, e.g. SOL_SOCKET
[in]	nOptionId	option 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_pValue	return value of the given nOptionId
[out]	o_pValueLen	size of the returned value

Return values

ERR_NOERROR	everything is OK
ERR_UNKNOWN	something 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

nTimeout The 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] id system specific socket option

Returns: the resolved option

◆ ResolveOptionLevel()

tInt ResolveOptionLevel ( tOptionLevel level ) const

protected

Resolve the option value of the socket.

Parameters

[in] level system 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] eLevel option level, allowed values:

See also: cSocket::tOptionLevel

Parameters

[in] eId option id, allowed values (in terms of platform independence):

See also: cSocket::tOptionLevel

Parameters

[in]	pValue	pointer to the new value
[in]	nValueLen	size 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]	nLevel	option level, e.g. SOL_SOCKET
[in]	nOptionId	option 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]	pValue	pointer to the new value.
[in]	nValueLen	size 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

nReadTimeout	the timeout for read operations (microseconds).
nWriteTimeout	the 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] nSocketError socket 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

ui32Address the 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_lstSockets	List of Sockets checked for data
[out]	o_ppSocket	first cSocket Pointer to the cSocket out of `i_lstSockets`
[in]	tmTimeOut	Maximum time to wait in microseconds, -1 = forever.

Returns: Standard Error Code.

Return values

ERR_POINTER o_pSocket is set to nullptr

◆ WaitForData() [2/2]

tBool WaitForData ( tTimeStamp nTimeout = -1 )

Blocks the current process until data is available for reading.

Parameters

nTimeout Maximum time to wait in microseconds, -1 = forever.

Returns: true if data is available, false otherwise.

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ tOpenMode

◆ tOptionId

◆ tOptionLevel

◆ tShutdownMode

Member Function Documentation

◆ AddressToUInt32()

◆ Close() [1/2]

◆ Close() [2/2]

◆ DataAvailable()

◆ FindInterfaceForAddress()

◆ GetAddress()

◆ GetHandle()

◆ GetHostAddress()

◆ GetHostName()

◆ GetLastErrorCode()

◆ GetLocalAddresses()

◆ GetOption() [1/2]

◆ GetOption() [2/2]

◆ GetPort()

◆ Initialize()

◆ IsConnected()

◆ ResolveOptionId()

◆ ResolveOptionLevel()

◆ SetOption() [1/2]

◆ SetOption() [2/2]

◆ SetTimeout()

◆ SocketError()

◆ UInt32ToAddress()

◆ WaitForData() [1/2]

◆ WaitForData() [2/2]