Git-Mirrors/RetroShare
1
0
Fork 0
mirror of https://github.com/RetroShare/RetroShare.git synced 2025-01-15 01:17:16 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

improved documentation of TurtleClientService class with doxygen type

Browse Source
This commit is contained in:
csoler 2018-03-24 16:41:51 +01:00
parent 58aa2413b3
commit 2255bda007
No known key found for this signature in database
GPG Key ID: 7BCA522266C0804C
1 changed files with 59 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
libretroshare/src/turtle/turtleclientservice.h
View File

@ -42,51 +42,77 @@ class p3turtle ;
class RsTurtleClientService
{
public:
// Handling of tunnel request for the given hash. Most of the time, it's a search in a predefined list.
// The output info_string is used by the turtle router to display info about tunnels it manages. It is
// not passed to the tunnel.
virtual bool handleTunnelRequest(const RsFileHash& /*hash*/,const RsPeerId& /*peer_id*/) { return false ; }
/*!
* \brief handleTunnelRequest
Handling of tunnel request for the given hash. To be derived by the service in order to tell the turtle router
whether the service handles this hash or not. Most of the time, it's a search in a predefined list.
* \return true if the service
*/
virtual bool handleTunnelRequest(const RsFileHash& /*hash*/,const RsPeerId& /*peer_id*/) { return false ; }
// This method is called by the turtle router to send data that comes out of a turtle tunnel.
// The turtle router stays responsible for the memory management of data. Most of the time the
// data chunk is a serialized item to be de-serialized by the client service.
//
// Parameters:
// virtual_peer_id : name of the tunnel that sent the data
// data : memory chunk for the data
// size : size of data
// item->direction : direction of travel:
// RsTurtleGenericTunnelItem::DIRECTION_CLIENT: the service is acting as a client
// RsTurtleGenericTunnelItem::DIRECTION_CLIENT: the service is acting as a server
//
// Most of the time this parameter is not used by services, except when some info (such as chunk maps, chat items, etc) go
// both ways, and their nature cannot suffice to determine where they should be handled.
//
// By default (if not overloaded), the method will just free the data, as any subclass should do as well.
// Note: p3turtle stays owner of the item, so the client should not delete it!
//
/*!
* \brief receiveTurtleData
* This method is called by the turtle router to send data that comes out of a turtle tunnel, and should
* be overloaded by the client service.
* The turtle router stays responsible for the memory management of data. Most of the time the
* data chunk is a serialized item to be de-serialized by the client service.
*
* Parameters:
* virtual_peer_id : name of the tunnel that sent the data
* data : memory chunk for the data
* size : size of data
* item->direction : direction of travel:
* RsTurtleGenericTunnelItem::DIRECTION_CLIENT: the service is acting as a client
* RsTurtleGenericTunnelItem::DIRECTION_CLIENT: the service is acting as a server
*
* Most of the time this parameter is not used by services, except when some info (such as chunk maps, chat items, etc) go
* both ways, and their nature cannot suffice to determine where they should be handled.
*
* By default (if not overloaded), the method will just free the data, as any subclass should do as well.
* Note: p3turtle stays owner of the item, so the client should not delete it!
*/
virtual void receiveTurtleData(RsTurtleGenericTunnelItem */*item*/,const RsFileHash& /*hash*/,const RsPeerId& /*virtual_peer_id*/,RsTurtleGenericTunnelItem::Direction /*direction*/)
{
std::cerr << "!!!!!! Received Data from turtle router, but the client service is not handling it !!!!!!!!!!" << std::endl ;
}
// Method for creating specific items of the client service. The
// method has a default behavior of not doing anything, since most client
// services might only use the generic item already provided by the turtle
// router: RsTurtleGenericDataItem
/*!
* \brief serializer
* Method for creating specific items of the client service. The
* method has a default behavior of not doing anything, since most client
* services might only use the generic item already provided by the turtle
* router: RsTurtleGenericDataItem
*
* \return the client's serializer is returned
*/
virtual RsServiceSerializer *serializer() { return NULL ; }
// These methods are called by the turtle router to add/remove virtual peers when tunnels are created/deleted
//
/*!
* \brief addVirtualPeer
* These methods are called by the turtle router to notify the client in order to add/remove virtual peers when tunnels are created/deleted
* These methods must be overloaded, because a service which does not care about tunel being openned or closed is not supposed to need tunnels.
*
* \param hash hash that the tunnel responds to
* \param virtual_peer_id virtual peer id provided by turtle to allow the client to send data into this tunnel. This peer is related to the tunnel itself
* rather than to its destination. As such, multiple peer ids may actually send data to the same computer because multiple tunnels
* arrive at the same location.
* \param dir dir indicates which side the cient will be talking to: CLIENT means that the client is the server. SERVER means that the client acts
* as a client (and therefore actually requested the tunnel).
*/
virtual void addVirtualPeer(const TurtleFileHash& hash,const TurtleVirtualPeerId& virtual_peer_id,RsTurtleGenericTunnelItem::Direction dir) = 0 ;
virtual void removeVirtualPeer(const TurtleFileHash& hash,const TurtleVirtualPeerId& virtual_peer_id) = 0 ;
// This function is mandatory. It should do two things:
// 1 - keep a pointer to the turtle router, so as to be able to send data (e.g. copy pt into a local variable)
// 2 - call pt->registerTunnelService(this), so that the TR knows that service and can send back information to it.
//
/*!
* \brief connectToTurtleRouter
* This function must be overloaded by the client. It should do two things:
* 1 - keep a pointer to the turtle router, so as to be able to send data (e.g. store pt into a local variable)
* 2 - call pt->registerTunnelService(this), so that the TR knows that service and can send back information to it.
*
* \param pt A pointer to the turtle router.
*/
virtual void connectToTurtleRouter(p3turtle *pt) = 0 ;
};