Base class for network endpoints. More...

Inheritance diagram for Burger::NetworkEndpoint:

Collaboration diagram for Burger::NetworkEndpoint:

[legend]

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

void( *) Burger::NetworkEndpoint::CallbackProc(void *pContext, NetworkEndpointInstance::eCallbackCode uCode, NetworkEndpoint *pEndpoint, eError uError, void *pExtra)

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()

virtual 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()

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

inline

Return the connected NetworkEndpointInstance.

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

◆ GetNetworkManager()

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

inline

Return the parent NetworkManager.

Returns: Pointer to the parent NetworkManager

◆ GetNetworkModule()

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

inline

Return the parent NetworkModule.

Returns: Pointer to the parent NetworkModule

◆ GetOpenType()

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()

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

inline

Get the state of the endpoint.

Returns: The current state of this endpoint.

◆ GetType()

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()

virtual 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()

virtual 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.

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Attributes

Private Member Functions

Detailed Description

Member Typedef Documentation

◆ CallbackProc

Member Enumeration Documentation

◆ eOpenType

◆ eState

Constructor & Destructor Documentation

◆ NetworkEndpoint() [1/3]

◆ NetworkEndpoint() [2/3]

◆ NetworkEndpoint() [3/3]

◆ ~NetworkEndpoint()

Member Function Documentation

◆ AcceptConnection()

◆ Close()

◆ EndpointCallback()

◆ GetInfo()

◆ GetLocalAddress()

◆ GetNetworkEndpointInstance()

◆ GetNetworkManager()

◆ GetNetworkModule()

◆ GetOpenType()

◆ GetRemoteAddress()

◆ GetState()

◆ GetType()

◆ IsAlive()

◆ NotificationLock()

◆ NotificationUnlock()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Poll()

◆ Receive()

◆ ReceiveDatagram()

◆ RejectConnection()

◆ Send()

◆ SendDatagram()

◆ SetCallback()

◆ SetCallbackContext()

◆ SetOpenType()

◆ SetState()

◆ SetTimeOut()

◆ StartAdvertising()

◆ StopAdvertising()

Member Data Documentation

◆ m_pCallback

◆ m_pCallbackContext

◆ m_pEndpointInstance

◆ m_pNetworkManager

◆ m_pNetworkModule

◆ m_pNextEndpoint

◆ m_pParent

◆ m_uOpenType

◆ m_uState

◆ m_uType