PLCore::Connection Class Reference

Connection base class. More...

#include <Connection.h>

Inheritance diagram for PLCore::Connection:

List of all members.

Public Types
enum	EReceiveMode { ReceiveAutomatic = 0, ReceiveManual }
	Receive mode. More...
Public Member Functions
PLCORE_API	Connection (Host &cHost)
	Constructor.
const Host &	GetHost () const
	Get host that owns this connection.
Host &	GetHost ()
	Get host that owns this connection.
String	GetHostname () const
	Get name of connected host.
uint32	GetPort () const
	Get port.
const Socket &	GetSocket () const
	Get socket.
Socket &	GetSocket ()
	Get socket.
bool	IsConnected () const
	Check if connection is active.
PLCORE_API bool	Disconnect ()
	Disconnect.
EReceiveMode	GetReceiveMode () const
	Get receive mode.
void	SetReceiveMode (EReceiveMode nReceiveMode)
	Set receive mode.
int	Send (const char *pBuffer, uint32 nSize) const
	Send data.
int	Send (const String &sString) const
	Send string.
PLCORE_API int	Receive (char *pBuffer, uint32 nSize)
	Receives data (blocking request)
PLCORE_API String	ReadLine ()
	Read line of text (blocking request)
Protected Member Functions
virtual PLCORE_API	~Connection ()
	Destructor.
PLCORE_API bool	Connect (const String &sHost, uint32 nPort)
	Establish a connection to a host by specifying address and port.
PLCORE_API bool	Connect (Socket &cSocket)
	Establish a connection to a host by using a given socket.
virtual PLCORE_API void	OnConnect ()
	Called when the connection is established.
virtual PLCORE_API void	OnDisconnect ()
	Called when the connection is disconnected.
virtual PLCORE_API void	OnReceive (const char *pBuffer, uint32 nSize)
	Called when the connection receives data.

---

Detailed Description

Connection base class.

Remarks:

This is the most important base class of the PLCore network classes for the 'concrete' communication. This class 'only' offers low-level methods for the communication on a pure abstract data layer, meaning sending of strings or data-arrays without known usage/semantic. Derived connection classes have to implement the concrete content layer. For example a chat-connection offers methods like SendMessage(), SendPrivateMessage(), SlapUser(), defining in this way what the user can do within the network. Within this methods a data-package is created and send by using Connection::Send(). In another usage a game-connection may have something like SynchronizeObject(Object*), GetUpdate(), SendAction(Action*). In short, the task of the derived connection class is to define the concrete protocol and to hide the rest so the application do not have to care about it. The application should 'only' use the methods of the concrete for instance game-connection class - NEVER creating somewhere data-packages and sending them by itself using Connection::Send()!

---

Member Enumeration Documentation

enum PLCore::Connection::EReceiveMode

Receive mode.

Enumerator:

ReceiveAutomatic	Data is received automatically (see OnReceive())
ReceiveManual	Data is received manually (see Receive())

---

Constructor & Destructor Documentation

PLCORE_API PLCore::Connection::Connection

(

Host &

cHost

)

Constructor.

Parameters:

[in]

cHost

Owner host

virtual PLCORE_API PLCore::Connection::~Connection

(

)

[protected, virtual]

Destructor.

---

Member Function Documentation

const Host & PLCore::Connection::GetHost

(

)

const [inline]

Get host that owns this connection.

Returns:

Host

Host & PLCore::Connection::GetHost

(

)

[inline]

Get host that owns this connection.

Returns:

Host

String PLCore::Connection::GetHostname

(

)

const [inline]

Get name of connected host.

Returns:

Name of host

uint32 PLCore::Connection::GetPort

(

)

const [inline]

Get port.

Returns:

Port number

const Socket & PLCore::Connection::GetSocket

(

)

const [inline]

Get socket.

Returns:

The socket object

Socket & PLCore::Connection::GetSocket

(

)

[inline]

Get socket.

Returns:

The socket object

bool PLCore::Connection::IsConnected

(

)

const [inline]

Check if connection is active.

Returns:

'true' if the connection is currently established, else 'false'

PLCORE_API bool PLCore::Connection::Disconnect

(

)

Disconnect.

Returns:

'true' if all went fine, else 'false' (maybe there's no connection established?)

Connection::EReceiveMode PLCore::Connection::GetReceiveMode

(

)

const [inline]

Get receive mode.

Returns:

Receive mode

void PLCore::Connection::SetReceiveMode

(

EReceiveMode

nReceiveMode

)

[inline]

Set receive mode.

Parameters:

[in]

nReceiveMode

Receive mode

Remarks:

If mode is ReceiveAutomatic, data is read from the connection automatically. If mode is ReceiveManual, no data will be read until the method ReceiveData() has been called. In both cases, OnReceive() will be called whenever new data has arrived. By default, mode is set to ReceiveAutomatic.

int PLCore::Connection::Send	(	const char *	pBuffer,
		uint32	nSize
	)		const [inline]

Send data.

Parameters:

[in]	pBuffer	Data to send, if a null pointer nothing happens
[in]	nSize	Size in bytes of the buffer to send, MUST be valid!

Returns:

Total number of bytes sent. Can be less than the requested size to be sent, negative value on error

int PLCore::Connection::Send

(

const String &

sString

)

const [inline]

Send string.

Parameters:

[in]

sString

String

Returns:

Total number of bytes sent, negative value on error

PLCORE_API int PLCore::Connection::Receive	(	char *	pBuffer,
		uint32	nSize
	)

Receives data (blocking request)

Parameters:

[out]	pBuffer	Buffer that receives the data, if a null pointer, nothing can be received
[in]	nSize	Size in bytes of the buffer that receives the data, MUST be valid!

Returns:

Total number of received bytes, negative value on error

Note:

• If there is currently not enough data available, this function will read as much as possible, meaning that less data can be read than requested
• If more data is waiting to be received as the given buffer is able to store, you have to call this method multiple times in order to gather all waiting data

PLCORE_API String PLCore::Connection::ReadLine

(

)

Read line of text (blocking request)

Returns:

Line read

PLCORE_API bool PLCore::Connection::Connect	(	const String &	sHost,
		uint32	nPort
	)		[protected]

Establish a connection to a host by specifying address and port.

Parameters:

[in]	sHost	Host name
[in]	nPort	Port number

Returns:

'true' if all went fine, else 'false'

PLCORE_API bool PLCore::Connection::Connect

(

Socket &

cSocket

)

[protected]

Establish a connection to a host by using a given socket.

Parameters:

[in]

cSocket

Socket of the host to connect to

Returns:

'true' if all went fine, else 'false'

virtual PLCORE_API void PLCore::Connection::OnConnect

(

)

[protected, virtual]

Called when the connection is established.

Reimplemented in PLCore::HttpServerConnection, and PLCore::HttpClientConnection.

virtual PLCORE_API void PLCore::Connection::OnDisconnect

(

)

[protected, virtual]

Called when the connection is disconnected.

Reimplemented in PLCore::HttpServerConnection, and PLCore::HttpClientConnection.

virtual PLCORE_API void PLCore::Connection::OnReceive	(	const char *	pBuffer,
		uint32	nSize
	)		[protected, virtual]

Called when the connection receives data.

Parameters:

[in]	pBuffer	Buffer with the received data, a null pointer on terrible error
[in]	nSize	Number of received bytes within the given buffer (always valid!)

Note:

• Do NOT keep a pointer/reference to 'nBuffer' because this buffer is only valid inside this function

Reimplemented in PLCore::HttpServerConnection, and PLCore::HttpClientConnection.

---

The documentation for this class was generated from the following files:

• PLCore/include/PLCore/Network/Connection.h
• Connection.inl