class RNET::IPeer

This interface gives access to REDnet peer configuration and life cycle management.

#include <RNETIPeer.h>

Inherits: IREDObject.

Public functions:

virtual RED_RC	CloseConnection ( int iConnectionID ) = 0
virtual RED_RC	ConnectTo ( const RNET::Address & iAddress ) = 0
virtual RNET::Address	GetConnectionAddress ( int iConnection ) = 0
virtual RED_RC	GetConnectionsIDList ( RED::Vector< int > & oConnectionsID ) const = 0
virtual unsigned int	GetID ( ) const = 0
virtual int	GetMaxConnections ( ) const = 0
virtual int	GetPort ( ) const = 0
virtual unsigned int	GetVersion ( ) const = 0
virtual const RED::String &	GetWebServerPath ( ) const = 0
virtual bool	IsConnectedToDispatcher ( ) const = 0
virtual bool	IsConnectionAlive ( int iConnection ) = 0
virtual RED_RC	SendImage ( unsigned int & oSentBytes, float & ioQuality, int iConnectionID, RED::Object * iImage, unsigned int iMaxFrameSize = 102400 ) = 0
virtual RED_RC	SendImage ( unsigned int & oSentBytes, float & ioQuality, const RED::Vector< int > & iConnectionIDs, RED::Object * iImage, unsigned int iMaxFrameSize = 102400 ) = 0
virtual RED_RC	SendMessage ( int iConnectionID, RNET::MessageType iType, const char * iData, unsigned int iDataSize ) = 0
virtual RED_RC	SendString ( int iConnectionID, const RED::String & iString ) = 0
virtual void	SetOnConnectionClosed ( ON_CONNECTION_CLOSED_CALLBACK iCallback, void * iUserData ) = 0
virtual void	SetOnConnectionReady ( ON_CONNECTION_READY_CALLBACK iCallback, void * iUserData ) = 0
virtual void	SetOnDataReceived ( ON_DATA_RECEIVED_CALLBACK iCallback, void * iUserData ) = 0
virtual void	SetOnDataRequest ( ON_DATA_REQUEST_CALLBACK iCallback, void * iUserData ) = 0
virtual void	SetOnPoll ( ON_POLL_CALLBACK iCallback, void * iUserData ) = 0
virtual void	SetOnShutdown ( ON_SHUTDOWN_CALLBACK iCallback, void * iUserData ) = 0
virtual void	SetPollTimeout ( unsigned int iPollTimeMS ) = 0
virtual RED_RC	SetStatus ( RNET::PeerStatus iStatus, unsigned int iWorkLoad ) = 0
virtual RED_RC	Shutdown ( ) = 0
virtual RED_RC	Start ( unsigned int iID, unsigned int iVersion, const RED::String & iWebServerPath, unsigned int iMaxConnections = 0, int iPort = 18000, const RNET::Address & iDispatcherAddress = RNET::Address() ) = 0

Functions documentation

public static RED::CID RNET::IPeer::GetClassID

(

)

public virtual RED_RC RNET::IPeer::CloseConnection

(

int

iConnectionID

) = 0

Closes a connection with a peer.

If the connection does not exist or is already closed, RED_OK is returned. In the case of a peer to peer connection, any message that was sent but that wasn't emitted yet will be lost.

Parameters:

iConnectionID

ID of the connection to close.

Returns:

RED_OK on success,
RED_FAIL otherwise.

public virtual RED_RC RNET::IPeer::ConnectTo

(

const RNET::Address &

iAddress

) = 0

Connects to another REDnet peer.

The connection is postponed to next internal call to poll. Success or failure of the connection will be notified to the corresponding peer callback.

Parameters:

iAddress

network address of the peer to connect to.

Returns:

RED_OK on success,
RED_FAIL otherwise.

public virtual RNET::Address RNET::IPeer::GetConnectionAddress

(

int

iConnection

) = 0

Returns the network address of a connection.

If the connection is not valid anymore, an invalid address is returned.

Returns:

the network address of a connection.

public virtual RED_RC RNET::IPeer::GetConnectionsIDList

(

RED::Vector< int > &

oConnectionsID

) const = 0

Gets the list of active connections ID.

A connection may still be active while being closed.

Parameters:

oConnectionsID

list of active connections ID.

Returns:

RED_OK on success,
RED_ALLOC_FAILURE on a memory allocation error,
RED_FAIL otherwise.

public virtual unsigned int RNET::IPeer::GetID

(

) const = 0

Returns:

the ID of the peer.

public virtual int RNET::IPeer::GetMaxConnections

(

) const = 0

Returns:

the maximum number of allowed connections (or 0 for unlimited number).

public virtual int RNET::IPeer::GetPort

(

) const = 0

Returns:

the network communication port.

public virtual unsigned int RNET::IPeer::GetVersion

(

) const = 0

Returns:

the version of the peer.

public virtual const RED::String & RNET::IPeer::GetWebServerPath

(

) const = 0

Returns:

the path to additional web server files.

public virtual bool RNET::IPeer::IsConnectedToDispatcher

(

) const = 0

Returns:

true if the peer is connected to a dispatcher, false otherwise.

public virtual bool RNET::IPeer::IsConnectionAlive

(

int

iConnection

) = 0

Returns true if the input connection is alive, false otherwise.

An alive connection is a connection which is not closed (or being closed).

Returns:

true if the input connection is alive, false otherwise.

public virtual RED_RC RNET::IPeer::SendImage	(	unsigned int &	oSentBytes,
		float &	ioQuality,
		int	iConnectionID,
		RED::Object *	iImage,
		unsigned int	iMaxFrameSize = 102400
	)	= 0

Sends a RED image through a connection.

Depending on the value of the ioQuality parameter, the image is compressed using lossy or lossless compression algorithms. 1 stands for full quality (lossless) and 0 stands for the lowest image quality (lossy).

Compression is performed using either JPEG or PNG formats depending on the value of ioQuality.

The iMaxFrameSize parameter lets you control the final size of the compressed image. It takes over the ioQuality parameter. Hence, if the compressed image size at the requested quality is larger than the value of iMaxFrameSize, the quality is decreased and compression is performed again until it satisfies the requirements. The value of the modified quality parameter is then returned in in ioQuality. If iMaxFrameSize equals to 0, the image is compressed targeting only the ioQuality value (i.e ignoring the value of iMaxFrameSize) which is then returned unchanged.

The format of the image must be one of: RED::FMT_RGB or RED::FMT_RGBA. Note that if an alpha channel is present, it is discarded before sending the image.

The local content of iImage may become invalid after the call. If you stored a pointer to the local storage of the image before calling RNET::IPeer::SendImage, you need to call GetPixels and GetLocalPixels again to update it after the call.

Due to optional compression and data re-encoding, the actual number of sent bytes may be bigger or lower than the original size of the data. oSentBytes contains the real number of bytes sent over the network.

Due to delayed network orders processing, the call may return with the RED_OK value even if the data have not been sent immediatly. Therefore, RED_OK means that the order has been successfully buffered.

Parameters:

oSentBytes	number of bytes sent by the call. If an error occured, this value may be undefined.
ioQuality	quality of the compressed image in [0, 1]. If the quality is modified by the call, the modified value is returned in ioQuality.
iConnectionID	ID of the connection to use.
iImage	pointer to the image to send.
iMaxFrameSize	maximum allowed size in bytes of a compressed image. ioQuality may be adjusted on-the-fly by the method to satisfy the size constraint. Default is 100Kb.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid input parameter,
RED_NET_SEND_FAIL if the image has not been send,
RED_FAIL otherwise.

public virtual RED_RC RNET::IPeer::SendImage	(	unsigned int &	oSentBytes,
		float &	ioQuality,
		const RED::Vector< int > &	iConnectionIDs,
		RED::Object *	iImage,
		unsigned int	iMaxFrameSize = 102400
	)	= 0

Sends the same RED image through several connections.

This method lets you perform simple broadcasting of an image to several peers at the same time.

The input image is processed once for all connections. The multiple send operations add only a small processing overhead to the call compared to the other SendImage method. However, there is a network overhead which scales linearly with the number of transmissions.

The method does not check for connections redundancy in the input list. Therefore, if a connection is present multiple times in the list, it will be used as many times to transmit the image.

For more details about the method behavior, please have a look to the documentation of the single connection implementation of SendImage.

Parameters:

oSentBytes	number of bytes sent by the call. If an error occured, this value may be undefined.
ioQuality	quality of the compressed image in [0, 1]. If the quality is modified by the call, the modified value is returned in ioQuality.
iConnectionIDs	list of the ID of the connections to use.
iImage	pointer to the image to send.
iMaxFrameSize	maximum allowed size in bytes of a compressed image. ioQuality may be adjusted on-the-fly by the method to satisfy the size constraint. Default is 100Kb.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid input parameter,
RED_NET_SEND_FAIL if the image has not been send,
RED_FAIL otherwise.

public virtual RED_RC RNET::IPeer::SendMessage	(	int	iConnectionID,
		RNET::MessageType	iType,
		const char *	iData,
		unsigned int	iDataSize
	)	= 0

Sends a message through a connection.

Parameters:

iConnectionID	ID of the connection to use.
iType	message type.
iData	pointer to the optional message data to send.
iDataSize	size of the optional message data to send.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid input parameter,
RED_NET_SEND_FAIL if the image has not been send,
RED_FAIL otherwise.

public virtual RED_RC RNET::IPeer::SendString	(	int	iConnectionID,
		const RED::String &	iString
	)	= 0

Sends a RED string through a connection.

Parameters:

iConnectionID	ID of the connection to use.
iString	the string to send.

Returns:

RED_OK on success,
RED_BAD_PARAM on an invalid input parameter,
RED_NET_SEND_FAIL if the image has not been send,
RED_FAIL otherwise.

public virtual void RNET::IPeer::SetOnConnectionClosed	(	ON_CONNECTION_CLOSED_CALLBACK	iCallback,
		void *	iUserData
	)	= 0

Sets the 'on connection closed' callback.

The callback is called when a connection over the peer communication port is being closed. The reference to the connection must not be used any further after returning from the callback as the object won't reference something valid anymore.

Please, note that this does not include connections with the dispatcher (which is maintained separatly). To know if the peer is connected or not to a dispatcher, call IsConnectedToDispatcher().

Parameters:

iCallback	pointer to the callback to be called when connections get closed.
iUserData	custom user pointer to additional data to be passed to the callback.

public virtual void RNET::IPeer::SetOnConnectionReady	(	ON_CONNECTION_READY_CALLBACK	iCallback,
		void *	iUserData
	)	= 0

Sets the 'on connection ready' callback.

The callback is called once a connection has been successfully established over the peer communication port with another machine. Hence, a discarded connection request (due for example to a maximum simultaneous number of connections reached) won't result in a call to the callback.

Parameters:

iCallback	pointer to the callback to be called on new accepted input connections.
iUserData	custom user pointer to additional data to be passed to the callback.

public virtual void RNET::IPeer::SetOnDataReceived	(	ON_DATA_RECEIVED_CALLBACK	iCallback,
		void *	iUserData
	)	= 0

Sets the 'on data received' callback.

The callback is called each time data are available from a connection.

Parameters:

iCallback	pointer to the callback to be called when data are received.
iUserData	custom user pointer to additional data to be passed to the callback.

public virtual void RNET::IPeer::SetOnDataRequest	(	ON_DATA_REQUEST_CALLBACK	iCallback,
		void *	iUserData
	)	= 0

Sets the 'on data request' callback.

The callback is called each time data are requested by a client. Because each peer acts as a web server, data can be requested by clients such as files, cgi...

Parameters:

iCallback	pointer to the callback to be called when data are received.
iUserData	custom user pointer to additional data to be passed to the callback.

public virtual void RNET::IPeer::SetOnPoll	(	ON_POLL_CALLBACK	iCallback,
		void *	iUserData
	)	= 0

Sets the 'on poll' callback.

When set, this function is automatically called each time REDnet performs polling.

This is the perfect place to do your own network management code because you're guaranteed that no other REDnet network operation is ran conccurently.

Parameters:

iCallback	pointer to the on poll callback.
iUserData	custom user pointer to additional data to be passed to the callback.

public virtual void RNET::IPeer::SetOnShutdown	(	ON_SHUTDOWN_CALLBACK	iCallback,
		void *	iUserData
	)	= 0

Sets the 'on shutdown' callback.

When set, this function is automatically called on peer shutdown.

The callback is called right before the peer is actually shutdown. A last polling operation is performed after returning from this method (however, during that polling, the ON_POLL user callback is not called anymore). Hence, this is the prefered place to send last minute information to connections.

Parameters:

iCallback	pointer to the on shutdown callback.
iUserData	custom user pointer to additional data to be passed to the callback.

public virtual void RNET::IPeer::SetPollTimeout

(

unsigned int

iPollTimeMS

) = 0

Sets the polling timeout.

This method can be set to specify the polling timeout of the peer. By default the peer has a zero timeout, so that it polls actively from its networking thread. Increasing this value will slow down the polling frequency of the peer.

Parameters:

iPollTimeMS:

Polling timeout value in milliseconds.

public virtual RED_RC RNET::IPeer::SetStatus	(	RNET::PeerStatus	iStatus,
		unsigned int	iWorkLoad
	)	= 0

Informs the dispatcher about the current peer status.

If the peer is not connected to any dispatcher, the call returns immediatly with RED_OK. Otherwise, the passed status is sent to the dispatcher.

Parameters:

iStatus	current peer status.
iWorkLoad	current work load (in [0, 100]).

Returns:

RED_OK on success,
RED_FAIL otherwise.

public virtual RED_RC RNET::IPeer::Shutdown

(

) = 0

Shutdowns a REDnet peer.

If you call Start twice, Shutdown is automatically called in-between. During shutdown, all pending sent messages are flushed and effectively transmitted before the shutdown. You'll get called by the RNET::ON_POLL_CALLBACK callback if set.

Returns:

RED_OK on success (or if the peer has already stopped),
RED_FAIL otherwise.

public virtual RED_RC RNET::IPeer::Start	(	unsigned int	iID,
		unsigned int	iVersion,
		const RED::String &	iWebServerPath,
		unsigned int	iMaxConnections = 0,
		int	iPort = 18000,
		const RNET::Address &	iDispatcherAddress = RNET::Address()
	)	= 0

Starts a new REDnet peer.

Each call to Start internally begins with a call to Shutdown, meaning that every existing communications will be closed.

Parameters:

iID	unique ID of the peer (used to identify peers over the network).
iVersion	version of the peer.
iWebServerPath	path to additional data needed by peers running as web servers.
iMaxConnections	maximum connections allowed to the peer in [0, +inf]. 0 means that the number of connections is not limited (default is 0).
iPort	net port that will be used for network communications (default is 18000).
iDispatcherAddress	network address of the dispatcher (default is undefined).

Returns:

RED_OK on success (or if the peer has already started),
RED_BAD_PARAM on an invalid port number,
RED_NET_CANT_CREATE_SOCKET if the socket can't be initialized,
RED_NET_CANT_RESOLVE_DESTINATION if the destination address can't be resolved,
RED_FAIL otherwise.

class RNET::IPeer

Public functions:

Public static functions:

Functions documentation