Burger::NetworkEndpoint Class Reference

Base class for network endpoints. More...

Inheritance diagram for Burger::NetworkEndpoint:

Collaboration diagram for Burger::NetworkEndpoint:

Public Types
enum	eOpenType { kPassive , kActive }
	Enum describing how to open an endpoint. More...
enum	eState { kStateUnknown , kStateActive , kStateClosing , kStateClosed }
	Enum describing the state of an endpoint. More...
typedef void(*	CallbackProc) (void *pContext, NetworkEndpointInstance::eCallbackCode uCode, NetworkEndpoint *pEndpoint, eError uError, void *pExtra)
	Function prototype for event callbacks.

Public Member Functions
	NetworkEndpoint (NetworkModule *pNetworkModule)
	Default constructor.
virtual	~NetworkEndpoint ()
	Default destructor.
NetworkManager *	GetNetworkManager (void) const
	Return the parent NetworkManager.
NetworkModule *	GetNetworkModule (void) const
	Return the parent NetworkModule.
NetworkEndpointInstance *	GetNetworkEndpointInstance (void) const
	Return the connected NetworkEndpointInstance.
void	SetCallback (CallbackProc pCallback)
	Set the callback function pointer.
void	SetCallbackContext (void *pContext)
	Set the callback function's context pointer.
void	SetOpenType (eOpenType uOpenType)
eOpenType	GetOpenType (void) const
	Get the open type of the endpoint.
eNetworkProtocol	GetType (void) const
	Get the protocol type of the endpoint.
void	SetState (eState uState)
eState	GetState (void) const
	Get the state of the endpoint.
eError	GetInfo (NetworkModuleInfo_t *pOutput) const
	Get information about the parent NetworkModule.
eError	GetLocalAddress (String *pOutput)
	Return the address of the local endpoint instance.
eError	GetRemoteAddress (String *pOutput)
	Return the address of the remote endpoint instance.
eError	NotificationLock (eSocketFlags uFlags)
	Obtain the endpoint lock.
eError	NotificationUnlock (eSocketFlags uFlags)
	Release the endpoint lock.
virtual eError	Close (uint_t bOrderly)=0
	Close and dispose of all NetworkEndpointInstance records.
eError	AcceptConnection (CallbackProc pCallback, void *pContext, void *pExtra)
	Try to accept a requested connection.
eError	RejectConnection (void *pExtra)
	Reject the connection.
uint_t	IsAlive (void)
	Return TRUE if there is an active connection.
eError	SetTimeOut (uint32_t uTimeout=NetworkEndpointInstance::kDefaultTimeout)
	Set the timeout in milliseconds.
virtual eError	StartAdvertising (void)=0
	Enable listening for broadcast packets.
virtual eError	StopAdvertising (void)=0
	Disable listening for broadcast packets.
virtual eError	Poll (void) noexcept
	Poll for events.
eError	Send (uintptr_t *pBytesSent, const void *pData, uintptr_t uDataSize, NetworkEndpointInstance::eBlockMode uMode=NetworkEndpointInstance::kNonBlocking)
	Send data using guaranteed protocol.
eError	Receive (uintptr_t *pBytesReceived, void *pData, uintptr_t uDataSize)
	Receive data using guaranteed protocol.
eError	SendDatagram (uintptr_t *pBytesSent, const void *pData, uintptr_t uDataSize, NetworkEndpointInstance::eBlockMode uMode=NetworkEndpointInstance::kNonBlocking)
	Send data using datagram protocol.
eError	ReceiveDatagram (uintptr_t *pBytesReceived, void *pData, uintptr_t uDataSize)
	Receive data using non-guaranteed protocol.

Static Public Member Functions
static void	EndpointCallback (void *pContext, NetworkEndpointInstance::eCallbackCode uCode, NetworkEndpointInstance *pInstance, eError uError, void *pExtra)
	Endpoint callback.

Public Attributes
NetworkEndpointInstance *	m_pEndpointInstance
	Pointer to the endpoint instance (Head of a possible chain)

Protected Attributes
NetworkManager *	m_pNetworkManager
	Parent network manager.
NetworkModule *	m_pNetworkModule
	Parent network module.
NetworkEndpoint *	m_pNextEndpoint
	Next entry in the linked list of endpoints.
NetworkEndpoint *	m_pParent
	Pointer to a parent endpoint (If one exists)
CallbackProc	m_pCallback
	Function to call for Endpoint events.
void *	m_pCallbackContext
	Application supplied pointer for the callback.
eOpenType	m_uOpenType
	Host or client endpoint.
eNetworkProtocol	m_uType
	Type of endpoint.
eState	m_uState
	Asynchronous state of the endpoint.

Private Member Functions
	NetworkEndpoint (const NetworkEndpoint &)=delete
NetworkEndpoint &	operator= (const NetworkEndpoint &)=delete
	NetworkEndpoint (NetworkEndpoint &&)=delete
NetworkEndpoint &	operator= (NetworkEndpoint &&)=delete

Detailed Description

Base class for network endpoints.

---

For each connection to another a machine, an endpoint is needed to manage the connection. Endpoints can have more than one actual instance due to accepting connections from remote machines.

See also

NetworkEndpointInstance or NetworkModule

Member Typedef Documentation

CallbackProc

Burger::NetworkEndpoint::CallbackProc

Function prototype for event callbacks.

---

When an event has occurred for an endpoint, a callback using this function prototype will be issued with the proper callback code.

Parameters

pContext	Pointer to the user supplied context for the callback.
uCode	callback code issued to denote the type of event that had occurred.
pEndpoint	Pointer to the NetworkEndpoint that caused this event.
uError	Error state, if any, that occurred before the call was issued.
pExtra	Pointer to extra data if needed by the callback code.

See also

NetworkEndpointInstance::eCallbackCode and NetworkEndpoint

Member Enumeration Documentation

eOpenType

enum Burger::NetworkEndpoint::eOpenType

Enum describing how to open an endpoint.

---

Endpoints can be opened as a connection to a remote machine, kActive or as a listening endpoint that waits for events coming in from a remote system, kPassive

See also

NetworkEndpoint

Enumerator
kPassive	Passive endpoint for hosts.
kActive	Active endpoint for clients.

eState

enum Burger::NetworkEndpoint::eState

Enum describing the state of an endpoint.

---

When an endpoint is created, it's set to an unknown state, and states are tracked when it's being created or torn down.

See also

NetworkEndpoint or Close(uint_t)

Enumerator
kStateUnknown	Unknown socket state.
kStateActive	Socket has an active connection.
kStateClosing	Socket is in process of shutting down.
kStateClosed	Socket has cleanly shut down.

Constructor & Destructor Documentation

NetworkEndpoint() [1/3]

Burger::NetworkEndpoint::NetworkEndpoint ( const NetworkEndpoint & )

privatedelete

NetworkEndpoint() [2/3]

Burger::NetworkEndpoint::NetworkEndpoint ( NetworkEndpoint && )

privatedelete

NetworkEndpoint() [3/3]

Burger::NetworkEndpoint::NetworkEndpoint

(

NetworkModule *

pNetworkModule

)

Default constructor.

---

Parameters

pNetworkModule

Pointer to the parent NetworkModule

See also

NetworkModule

~NetworkEndpoint()

Burger::NetworkEndpoint::~NetworkEndpoint ( )

virtual

Default destructor.

---

Member Function Documentation

AcceptConnection()

Burger::eError BURGER_API Burger::NetworkEndpoint::AcceptConnection	(	CallbackProc	pCallback,
		void *	pContext,
		void *	pExtra )

Try to accept a requested connection.

---

Create a new endpoint and connect that endpoint to the endpoint instance

Parameters

pCallback	Pointer to the callback function, can be NULL if callbacks are not required.
pContext	Pointer to the context for the callback function
pExtra	Pointer to data that is passed to the pExtra parameter for the callback function

Returns

Zero if no error, non-zero if there was an error.

See also

RejectConnection(void *)

Close()

Burger::eError Burger::NetworkEndpoint::Close ( uint_t bOrderly )

pure virtual

Close and dispose of all NetworkEndpointInstance records.

---

Close all open endpoint instances and release the memory.

Parameters

bOrderly

TRUE if the remote machine is notified of the closure, FALSE if not.

Returns

Zero if no error, non-zero if there was an error.

Implemented in Burger::NetworkEndpointTCP.

EndpointCallback()

void BURGER_API Burger::NetworkEndpoint::EndpointCallback ( void * pContext, NetworkEndpointInstance::eCallbackCode uCode, NetworkEndpointInstance * pInstance, eError uError, void * pExtra )

static

Endpoint callback.

---

When a connection is being accepted, this is the internal callback that handles the event.

Parameters

pContext	Pointer to the NetworkEndpoint
uCode	Callback event code
pInstance	Pointer to the endpoint instance that this event originated from
uError	Error state, if any, that was present at the time of the event
pExtra	Extra pointer that is context sensitive based on the event code

GetInfo()

Burger::eError BURGER_API Burger::NetworkEndpoint::GetInfo

(

NetworkModuleInfo_t *

pOutput

)

const

Get information about the parent NetworkModule.

---

Query the parent NetworkModule for information about the protocol.

Parameters

pOutput

Pointer to an uninitialized NetworkModuleInfo_t structure that will be filled in after a successful call to this function.

Returns

Zero if no error, non-zero if there was an error.

See also

NetworkModule::GetInfo(NetworkModuleInfo_t *) const

GetLocalAddress()

Burger::eError BURGER_API Burger::NetworkEndpoint::GetLocalAddress

(

String *

pOutput

)

Return the address of the local endpoint instance.

---

Convert the local network address into a string.

Parameters

pOutput

Pointer to a String that will receive the network address

Returns

Zero if no error, non-zero on error.

See also

GetRemoteAddress(String *)

GetNetworkEndpointInstance()

Burger::NetworkEndpointInstance * Burger::NetworkEndpoint::GetNetworkEndpointInstance ( void ) const

inline

Return the connected NetworkEndpointInstance.

---

Returns

Pointer to the connected NetworkEndpointInstance, NULL if there is none.

GetNetworkManager()

Burger::NetworkManager * Burger::NetworkEndpoint::GetNetworkManager ( void ) const

inline

Return the parent NetworkManager.

---

Returns

Pointer to the parent NetworkManager

GetNetworkModule()

Burger::NetworkModule * Burger::NetworkEndpoint::GetNetworkModule ( void ) const

inline

Return the parent NetworkModule.

---

Returns

Pointer to the parent NetworkModule

GetOpenType()

Burger::NetworkEndpoint::eOpenType Burger::NetworkEndpoint::GetOpenType ( void ) const

inline

Get the open type of the endpoint.

---

Returns

How the endpoint was opened.

GetRemoteAddress()

Burger::eError BURGER_API Burger::NetworkEndpoint::GetRemoteAddress

(

String *

pOutput

)

Return the address of the remote endpoint instance.

---

Convert the remote network address into a string.

Parameters

pOutput

Pointer to a String that will receive the network address

Returns

Zero if no error, non-zero on error.

See also

GetLocalAddress(String *)

GetState()

Burger::NetworkEndpoint::eState Burger::NetworkEndpoint::GetState ( void ) const

inline

Get the state of the endpoint.

---

Returns

The current state of this endpoint.

GetType()

Burger::eNetworkProtocol Burger::NetworkEndpoint::GetType ( void ) const

inline

Get the protocol type of the endpoint.

---

Returns

The protocol used for this endpoint.

IsAlive()

uint_t BURGER_API Burger::NetworkEndpoint::IsAlive

(

void

)

Return TRUE if there is an active connection.

---

Test the endpoint instance if there is an active connection. If there is no endpoint instances or there is no connection, return FALSE.

Returns

TRUE if there is an active connection to a remote endpoint.

NotificationLock()

Burger::eError Burger::NetworkEndpoint::NotificationLock

(

eSocketFlags

uFlags

)

Obtain the endpoint lock.

---

When endpoints are being manipulated, it may require the module lock to be achieved to hold other threads until the endpoint is set to its new state. This function obtains the parent NetworkModule lock.

Parameters

uFlags

Either kSocketFlagDatagram or kSocketFlagStream for what kind of endpoint is needing the lock.

Returns

Zero if no error, non-zero on error.

See also

NotificationUnlock(eSocketFlags)

NotificationUnlock()

Burger::eError Burger::NetworkEndpoint::NotificationUnlock

(

eSocketFlags

uFlags

)

Release the endpoint lock.

---

When endpoints are being manipulated, it may require the module lock to be achieved to hold other threads until the endpoint is set to its new state. This function releases the parent NetworkModule lock.

Parameters

uFlags

Either kSocketFlagDatagram or kSocketFlagStream for what kind of endpoint is releasing the lock.

Returns

Zero if no error, non-zero on error.

See also

NotificationLock(eSocketFlags)

operator=() [1/2]

NetworkEndpoint & Burger::NetworkEndpoint::operator= ( const NetworkEndpoint & )

privatedelete

operator=() [2/2]

NetworkEndpoint & Burger::NetworkEndpoint::operator= ( NetworkEndpoint && )

privatedelete

Poll()

Burger::eError Burger::NetworkEndpoint::Poll ( void )

virtualnoexcept

Poll for events.

---

On some platforms, endpoints require some CPU time from the application to perform housekeeping actions. Most platforms, this call performs no action because the network layer is all performed in its own thread.

Returns

Zero if no error, non-zero on error.

Receive()

Burger::eError BURGER_API Burger::NetworkEndpoint::Receive	(	uintptr_t *	pBytesReceived,
		void *	pData,
		uintptr_t	uDataSize )

Receive data using guaranteed protocol.

---

If this endpoint is connected to a remote endpoint, check if the endpoint has data pending and if so, fill the buffer with as many bytes that can be obtained. Set pBytesReceived with the actual number of bytes read in, this value can be zero.

Parameters

pBytesReceived	Pointer to a value that will obtain the number of bytes received during this call.
pData	Pointer to a data buffer to hold the received data.
uDataSize	Size of the buffer that will hold the received data.

Returns

Zero if no error, non-zero on error.

See also

ReceiveDatagram(uintptr_t *,const void *,uintptr_t)

ReceiveDatagram()

Burger::eError BURGER_API Burger::NetworkEndpoint::ReceiveDatagram	(	uintptr_t *	pBytesReceived,
		void *	pData,
		uintptr_t	uDataSize )

Receive data using non-guaranteed protocol.

---

If this endpoint is listening for packets, check if there is data pending and if so, fill the buffer with as many bytes that can be obtained. Set pBytesReceived with the actual number of bytes read in, this value can be zero.

Parameters

pBytesReceived	Pointer to a value that will obtain the number of bytes received during this call.
pData	Pointer to a data buffer to hold the received data.
uDataSize	Size of the buffer that will hold the received data.

Returns

Zero if no error, non-zero on error.

See also

Receive(uintptr_t *,const void *,uintptr_t)

RejectConnection()

Burger::eError BURGER_API Burger::NetworkEndpoint::RejectConnection

(

void *

pExtra

)

Reject the connection.

---

This is usually called in a callback to reject a connection during the call to AcceptConnection.

Parameters

pExtra

Pointer to the endpoint that is being rejected.

Returns

Zero if no error, non-zero if there was an error.

See also

AcceptConnection(CallbackProc,void *,void *)

Send()

Burger::eError BURGER_API Burger::NetworkEndpoint::Send	(	uintptr_t *	pBytesSent,
		const void *	pData,
		uintptr_t	uDataSize,
		NetworkEndpointInstance::eBlockMode	uMode = NetworkEndpointInstance::kNonBlocking )

Send data using guaranteed protocol.

---

If this endpoint is connected to a remote endpoint, send data to that endpoint. This function can block until data is in the queue. If the function is not blocked, check the returned pBytesSent value to determine how much data couldn't be sent due to issues such at data blockage.

Parameters

pBytesSent	Pointer to a value that will obtain the number of bytes sent during this call.
pData	Pointer to a data buffer to transmit.
uDataSize	Number of bytes to transmit.
uMode	Either NetworkEndpointInstance::kBlocking if this function should block until error or all data is send or NetworkEndpointInstance::kNonBlocking if the function should return as soon as possible.

Returns

Zero if no error, non-zero on error.

See also

SendDatagram(uintptr_t *,const void *,uintptr_t,eBlockMode)

SendDatagram()

Burger::eError BURGER_API Burger::NetworkEndpoint::SendDatagram	(	uintptr_t *	pBytesSent,
		const void *	pData,
		uintptr_t	uDataSize,
		NetworkEndpointInstance::eBlockMode	uMode = NetworkEndpointInstance::kNonBlocking )

Send data using datagram protocol.

---

If this endpoint has an address for a destination endpoint, send data to that endpoint. This function can block until data is in the queue. If the function is not blocked, check the returned pBytesSent value to determine how much data couldn't be sent due to issues such at data blockage.

Parameters

pBytesSent	Pointer to a value that will obtain the number of bytes sent during this call.
pData	Pointer to a data buffer to transmit.
uDataSize	Number of bytes to transmit.
uMode	Either NetworkEndpointInstance::kBlocking if this function should block until error or all data is send or NetworkEndpointInstance::kNonBlocking if the function should return as soon as possible.

Returns

Zero if no error, non-zero on error.

See also

Send(uintptr_t *,const void *,uintptr_t,eBlockMode)

SetCallback()

void Burger::NetworkEndpoint::SetCallback ( CallbackProc pCallback )

inline

Set the callback function pointer.

---

Parameters

pCallback

Pointer to the function callback or NULL if no callbacks are desired.

SetCallbackContext()

void Burger::NetworkEndpoint::SetCallbackContext ( void * pContext )

inline

Set the callback function's context pointer.

---

Parameters

pContext

Pointer to the context for the callback. It can be NULL.

SetOpenType()

void Burger::NetworkEndpoint::SetOpenType ( eOpenType uOpenType )

inline

SetState()

void Burger::NetworkEndpoint::SetState ( eState uState )

inline

SetTimeOut()

Burger::eError BURGER_API Burger::NetworkEndpoint::SetTimeOut

(

uint32_t

uTimeout = NetworkEndpointInstance::kDefaultTimeout

)

Set the timeout in milliseconds.

---

Set the timeout to the connected endpoint instance in milliseconds.

Parameters

uTimeout

in milliseconds, default is NetworkEndpointInstance::kDefaultTimeout

Returns

Zero if no error, non-zero on error.

StartAdvertising()

Burger::eError Burger::NetworkEndpoint::StartAdvertising ( void )

pure virtual

Enable listening for broadcast packets.

---

When creating a game server, it may wish to advertise its existence to the local network. This function enables the ability for this endpoint to listen for broadcast packets from a client asking for information about this server.

Returns

Zero if no error, non-zero on error.

Implemented in Burger::NetworkEndpointTCP.

StopAdvertising()

Burger::eError Burger::NetworkEndpoint::StopAdvertising ( void )

pure virtual

Disable listening for broadcast packets.

---

When creating a game server, it may wish to advertise its existence to the local network. This function disables the ability for this endpoint to listen for broadcast packets from a client asking for information about this server.

Returns

Zero if no error, non-zero on error.

Implemented in Burger::NetworkEndpointTCP.

Member Data Documentation

m_pCallback

CallbackProc Burger::NetworkEndpoint::m_pCallback

protected

Function to call for Endpoint events.

m_pCallbackContext

void* Burger::NetworkEndpoint::m_pCallbackContext

protected

Application supplied pointer for the callback.

m_pEndpointInstance

NetworkEndpointInstance* Burger::NetworkEndpoint::m_pEndpointInstance

Pointer to the endpoint instance (Head of a possible chain)

m_pNetworkManager

NetworkManager* Burger::NetworkEndpoint::m_pNetworkManager

protected

Parent network manager.

m_pNetworkModule

NetworkModule* Burger::NetworkEndpoint::m_pNetworkModule

protected

Parent network module.

m_pNextEndpoint

NetworkEndpoint* Burger::NetworkEndpoint::m_pNextEndpoint

protected

Next entry in the linked list of endpoints.

m_pParent

NetworkEndpoint* Burger::NetworkEndpoint::m_pParent

protected

Pointer to a parent endpoint (If one exists)

m_uOpenType

eOpenType Burger::NetworkEndpoint::m_uOpenType

protected

Host or client endpoint.

m_uState

eState Burger::NetworkEndpoint::m_uState

protected

Asynchronous state of the endpoint.

m_uType

eNetworkProtocol Burger::NetworkEndpoint::m_uType

protected

Type of endpoint.