IPeer
Functions
bool |
|
int |
|
int |
|
const String & |
|
unsigned int |
|
unsigned int |
|
bool |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
Detailed Description
-
class IPeer : public RED::IREDObject
This interface gives access to REDnet peer configuration and life cycle management.
@related class RNET::System
Introduction
A peer is a network node that can act both as a client and as a server, at the same time. It is a singleton, meaning that only one peer can exist at a given time, in a given process.
Setup
A peer can optionaly connect to a REDnet \ref bk_rednet_dispatcher. The dispatcher maintains an updated list of active peer connections in order to serve client requests: it’s called administration. Administration is transparent to the user and is managed through the REDnet \ref bk_rednet_dispatcher. Though, some specific code must be written in the server application to support the dispatcher features.
If administration is disabled for a peer, it will become invisible to the \ref bk_rednet_dispatcher and should be managed directly by the user.
If adminisitration is turned on, the peer automatically informs the \ref bk_rednet_dispatcher of any status change. For example, if a peer reaches its maximum allowed input connections, a busy status message is sent to the \ref bk_rednet_dispatcher.
When choosing the peer port, try setting something greater than 1024. Otherwise, it may conflict with well-known ports already in use by common platform services (like HTTP or FTP for example).
Usage
Once setup, the peer needs to be started by calling RNET::IPeer::Start. A new thread then runs in the background. It manages the network I/O for the peer and calls the corresponding user-defined callbacks on events. As long as the peer exists, the thread will be running. To release it, just delete the peer by a call to RED::Factory::DeletePeer.
You can find several tutorials about the usage of peers (\ref wf_rednet_first_peer, \ref wf_rednet_html5_client) and their administration (\ref wf_rednet_registering_dispatcher).
Public Functions
-
SET_CID(CID_class_RNETIPeer)
-
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
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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
virtual bool IsConnectedToDispatcher() const = 0
- Returns
true if the peer is connected to a dispatcher, false otherwise.
-
virtual int GetPort() const = 0
- Returns
the network communication port.
-
virtual int GetMaxConnections() const = 0
- Returns
the maximum number of allowed connections (or 0 for unlimited number).
-
virtual const RED::String &GetWebServerPath() const = 0
- Returns
the path to additional web server files.
-
virtual unsigned int GetID() const = 0
- Returns
the ID of the peer.
-
virtual unsigned int GetVersion() const = 0
- Returns
the version of the peer.
-
virtual RED_RC 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.
-
virtual bool 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.
-
virtual RED_RC 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.
-
virtual RNET::Address 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.
-
virtual RED_RC 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.
-
virtual void 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.
-
virtual void 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.
-
virtual void 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.
-
virtual void 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.
-
virtual void 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.
-
virtual void 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.
-
virtual void 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.
-
virtual RED_RC 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.
-
virtual RED_RC SendString(int iConnectionID, const RED::String &iString) = 0
Sends a RED string through a connection.
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
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.
-
virtual RED_RC 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.
-
virtual RED_RC 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.
-
SET_CID(CID_class_RNETIPeer)
