Burger::NetworkEndpointInstance Class Reference

Base class for network endpoint instances. More...

Inheritance diagram for Burger::NetworkEndpointInstance:

Collaboration diagram for Burger::NetworkEndpointInstance:

Public Types
enum	eCallbackCode {   kConnectionRequest , kAcceptionComplete , kHandoffComplete , kClosed ,   kDied , kUnblocked , kDatagramReceived , kStreamDataReceived ,   kPreprocessResponse }
	Callback code for endpoint instance events. More...
enum	eBlockMode { kNonBlocking , kBlocking }
	Flag for enabling or disabling blocking on data transmission. More...
typedef void(*	CallbackProc) (void *pContext, eCallbackCode uCode, NetworkEndpointInstance *pInstance, eError uError, void *pExtra)
	Function prototype for event callbacks.

Public Member Functions
	NetworkEndpointInstance (NetworkModule *pNetworkModule)
	Default constructor.
virtual	~NetworkEndpointInstance ()
	Default destructor.
NetworkModule *	GetNetworkModule (void) const
	Return the pointer to the parent NetworkModule.
eError	GetLocalAddress (String *pOutput)
	Return the address of the local endpoint.
eError	GetRemoteAddress (String *pOutput)
	Return the address of the remote endpoint.
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 a NetworkEndpointInstance.
virtual eError	AcceptConnection (CallbackProc pCallback, void *pContext, void *pExtra)=0
	Accept a remote connection request.
virtual eError	RejectConnection (void *pExtra)=0
	Reject a remote connection request.
virtual uint_t	IsAlive (void)=0
	Test if a stream connection with a remote machine is still active.
virtual eError	SetTimeOut (uint32_t uTimeout=kDefaultTimeout)=0
	Set the endpoint instance time 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=0
	Poll for events.
virtual eError	Send (uintptr_t *pBytesSent, const void *pData, uintptr_t uDataSize, eBlockMode uMode=kNonBlocking)=0
	Send data using guaranteed protocol.
virtual eError	Receive (uintptr_t *pBytesReceived, void *pData, uintptr_t uDataSize)=0
	Receive data using guaranteed protocol.
virtual eError	SendDatagram (uintptr_t *pBytesSent, const void *pData, uintptr_t uDataSize, eBlockMode uMode=kNonBlocking)=0
	Send data using datagram protocol.
virtual eError	ReceiveDatagram (uintptr_t *pBytesReceived, void *pData, uintptr_t uDataSize)=0
	Receive data using non-guaranteed protocol.

Static Public Attributes
static const uint32_t	kDefaultTimeout = 5000
	In milliseconds, 5 second timeout.

Protected Attributes
NetworkModule *	m_pNetworkModule
	Pointer to the parent NetworkModule.
NetAddr_t	m_LocalAddress
	Network address for local endpoint (All protocols supported)
NetAddr_t	m_RemoteAddress
	Network address for connected endpoint (All protocols supported)

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

Detailed Description

Base class for network endpoint instances.

---

A NetworkEndpoint can have one or more NetworkEndpointInstance classes, this class is an abstract class for which others are derived from.

Since this is an abstract class, most functions must be implemented by derived classes.

See also

NetworkEndpoint or NetworkModule

Member Typedef Documentation

CallbackProc

Burger::NetworkEndpointInstance::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.
pInstance	Pointer to the NetworkEndpointInstance 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

eCallbackCode and NetworkEndpointInstance

Member Enumeration Documentation

eBlockMode

enum Burger::NetworkEndpointInstance::eBlockMode

Flag for enabling or disabling blocking on data transmission.

---

When calling Send() or SendDatagram(), this enum is used to alert the function if blocking is desired. If blocked, the function won't return until data is sent or a timeout.

See also

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

Enumerator
kNonBlocking	Don't block on sending data.
kBlocking	Block until data is sent.

eCallbackCode

enum Burger::NetworkEndpointInstance::eCallbackCode

Callback code for endpoint instance events.

---

When a NetworkEndpointInstance generates an event, a callback is issued and one of these codes is used to determine the event.

See also

NetworkEndpointInstance or CallbackProc

Enumerator
kConnectionRequest	The endpoint has received a connection request.
kAcceptionComplete	Connect has been accepted, pExtra has the parent NetworkEndpointInstance.
kHandoffComplete	Connection hand off is complete, pExtra has the NetworkEndpointInstance that generated the hand off.
kClosed	Endpoint has finished closing.
kDied	Endpoint has died (Lost connection or remote disconnect)
kUnblocked	Endpoint has restarted (Whatever blocked the endpoint has cleared)
kDatagramReceived	UDP/IPX datagram data has arrived.
kStreamDataReceived	TCP/SPX stream data has arrived.
kPreprocessResponse	Before a response is sent, allow the callback to do data munging (Obsolete)

Constructor & Destructor Documentation

NetworkEndpointInstance() [1/3]

Burger::NetworkEndpointInstance::NetworkEndpointInstance ( const NetworkEndpointInstance & )

privatedelete

NetworkEndpointInstance() [2/3]

Burger::NetworkEndpointInstance::NetworkEndpointInstance ( NetworkEndpointInstance && )

privatedelete

NetworkEndpointInstance() [3/3]

Burger::NetworkEndpointInstance::NetworkEndpointInstance

(

NetworkModule *

pNetworkModule

)

Default constructor.

---

Parameters

pNetworkModule

Pointer to the parent NetworkModule

~NetworkEndpointInstance()

Burger::NetworkEndpointInstance::~NetworkEndpointInstance ( )

virtual

Default destructor.

---

Member Function Documentation

AcceptConnection()

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

pure virtual

Accept a remote connection request.

---

Attempt to connect to the remote endpoint. This can fail if the connection was interrupted before it could be acknowledged.

Parameters

pCallback	Pointer to a callback function that will be called to determine if a connection should be accepted or rejected.
pContext	Pointer to a context for the callback function.
pExtra	Pointer to the Endpoint that issued this accept request.

Returns

Zero if no error, non-zero on error.

Implemented in Burger::NetworkEndpointInstanceTCP.

Close()

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

pure virtual

Close and dispose of a NetworkEndpointInstance.

---

Close an endpoint and if bOrderly is set to TRUE, issue calls to the network driver to notify any connected remote machine that this endpoint is to be shut down and disposed of. If bOrderly is FALSE, the socket is torn down and no attempt is made to notify the machine on the other side.

Parameters

bOrderly

TRUE if the socket is to close in an orderly fashion, FALSE if not.

Returns

Zero if no error, non-zero on error.

Implemented in Burger::NetworkEndpointInstanceTCP.

GetLocalAddress()

Burger::eError BURGER_API Burger::NetworkEndpointInstance::GetLocalAddress

(

String *

pOutput

)

Return the address of the local endpoint.

---

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

GetNetworkModule()

Burger::NetworkEndpointInstance::GetNetworkModule ( void ) const

inline

Return the pointer to the parent NetworkModule.

---

Returns

Pointer to the parent NetworkModule for this NetworkEndpointInstance

GetRemoteAddress()

Burger::eError BURGER_API Burger::NetworkEndpointInstance::GetRemoteAddress

(

String *

pOutput

)

Return the address of the remote endpoint.

---

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

IsAlive()

uint_t Burger::NetworkEndpointInstance::IsAlive ( void )

pure virtual

Test if a stream connection with a remote machine is still active.

---

If a connection with a remote machine is active, return TRUE. Otherwise if the endpoint is invalid or not connected, it will return FALSE.

Returns

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

Implemented in Burger::NetworkEndpointInstanceTCP.

NotificationLock()

Burger::eError BURGER_API Burger::NetworkEndpointInstance::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_API Burger::NetworkEndpointInstance::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]

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

privatedelete

operator=() [2/2]

NetworkEndpointInstance & Burger::NetworkEndpointInstance::operator= ( NetworkEndpointInstance && )

privatedelete

Poll()

Burger::eError Burger::NetworkEndpointInstance::Poll ( void )

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

Implemented in Burger::NetworkEndpointInstanceTCP.

Receive()

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

pure virtual

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)

Implemented in Burger::NetworkEndpointInstanceTCP.

ReceiveDatagram()

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

pure virtual

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)

Implemented in Burger::NetworkEndpointInstanceTCP.

RejectConnection()

Burger::eError Burger::NetworkEndpointInstance::RejectConnection ( void * pExtra )

pure virtual

Reject a remote connection request.

---

Reject a connection to a remote endpoint.

Parameters

pExtra

Pointer to the Endpoint that issued an accept request that should be rejected.

Returns

Zero if no error, non-zero on error.

Implemented in Burger::NetworkEndpointInstanceTCP.

Send()

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

pure virtual

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 kBlocking if this function should block until error or all data is send or 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)

Implemented in Burger::NetworkEndpointInstanceTCP.

SendDatagram()

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

pure virtual

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 kBlocking if this function should block until error or all data is send or 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)

Implemented in Burger::NetworkEndpointInstanceTCP.

SetTimeOut()

Burger::eError Burger::NetworkEndpointInstance::SetTimeOut ( uint32_t uTimeout = kDefaultTimeout )

pure virtual

Set the endpoint instance time in milliseconds.

---

Set the timeout value for this endpoint instance in milliseconds.

Parameters

uTimeout

Timeout in milliseconds, 5 seconds is the default. kDefaultTimeout

Returns

Zero if no error, non-zero on error.

See also

kDefaultTimeout

Implemented in Burger::NetworkEndpointInstanceTCP.

StartAdvertising()

Burger::eError Burger::NetworkEndpointInstance::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.

See also

StopAdvertising(void)

Implemented in Burger::NetworkEndpointInstanceTCP.

StopAdvertising()

Burger::eError Burger::NetworkEndpointInstance::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.

See also

StartAdvertising(void)

Implemented in Burger::NetworkEndpointInstanceTCP.

Member Data Documentation

kDefaultTimeout

const uint32_t Burger::NetworkEndpointInstance::kDefaultTimeout = 5000

static

In milliseconds, 5 second timeout.

m_LocalAddress

NetAddr_t Burger::NetworkEndpointInstance::m_LocalAddress

protected

Network address for local endpoint (All protocols supported)

m_pNetworkModule

NetworkModule* Burger::NetworkEndpointInstance::m_pNetworkModule

protected

Pointer to the parent NetworkModule.

m_RemoteAddress

NetAddr_t Burger::NetworkEndpointInstance::m_RemoteAddress

protected

Network address for connected endpoint (All protocols supported)