diff --git a/libretroshare/src/gxs/UseCases.txt b/libretroshare/src/gxs/UseCases.txt index a8f5439bb..7fb995268 100644 --- a/libretroshare/src/gxs/UseCases.txt +++ b/libretroshare/src/gxs/UseCases.txt @@ -17,6 +17,9 @@ Please not all request* functions have a receive pair if not noted below -> This function will get the group list from Component: GDService::requestGroup() + + + -> ---------------- 1.1.2) list of messages for each Group. ---------------- @@ -35,7 +38,7 @@ Please not all request* functions have a receive pair if not noted below 1.1.4) details of messages by message Id. ---------------- int GXService::requestMessages(multimap >) - void receiveMsgs(int token, std::list); // call back + void receiveMsgs(int token, std::list); // call back ---------------- 1.1.5) newest version of each message -> get version list. @@ -55,8 +58,7 @@ Please not all request* functions have a receive pair if not noted below 1.1.7) access to Identity associated with Group and Messages ---------------- - int requestMsgIdentity(multimap >) - int requestGrpIdentity(string grpId) + returned with message ---------------- 1.1.8) updates when new groups arrive. @@ -74,7 +76,7 @@ Please not all request* functions have a receive pair if not noted below ---------------- int receivedNewUpdates(multimap >) - int receivedNewUpdates(multimap >) + int receivedNewUpdates(map >) ---------------- 1.1.11) Search forums for Keywords. @@ -149,7 +151,7 @@ Please not all request* functions have a receive pair if not noted below 1.4.4) modify forums we own. ---------------- - int GXService::updateForum(multimap) + int GXService::updateGroup(multimap) ---------------- ---------------- diff --git a/libretroshare/src/gxs/rsgdp.h b/libretroshare/src/gxs/rsgdp.h index 203b189ae..4b77fa089 100644 --- a/libretroshare/src/gxs/rsgdp.h +++ b/libretroshare/src/gxs/rsgdp.h @@ -84,7 +84,7 @@ public: * @param cacheRequest set to true to cache the messages requested * @return request code to be redeemed later */ - virtual int request(RequestFilter* filter, bool cacheRequest) = 0; + virtual int request(RsGxsSearch* filter, bool cacheRequest) = 0; /*! @@ -142,7 +142,7 @@ public: * Might be better off simply sending request codes * */ -class RequestFilter { +class RsGxsSearch { /*! * @@ -179,7 +179,7 @@ public: * Service should implement method taking case * @param filter */ - virtual void retrieve(RequestFilter* filter, SignedMsgGrp& msgs) = 0; + virtual void retrieve(RsGxsSearch* search, SignedMsgGrp& msgs) = 0; /*! * stores signed message in internal storage diff --git a/libretroshare/src/gxs/rsgixs.h b/libretroshare/src/gxs/rsgixs.h index 8937d7c5b..baeb4b138 100644 --- a/libretroshare/src/gxs/rsgixs.h +++ b/libretroshare/src/gxs/rsgixs.h @@ -91,17 +91,16 @@ class KeyRefSet { }; class SignatureSet { - std::set mSignatureSet; + std::set mSignatureSet; }; /*! * * */ -class Signature { +class RsGxsSignature { KeyRef mKeyRef; - Signature mSignature; }; /*! @@ -121,7 +120,7 @@ public: // TODO: add permissions members - Signature mSignature; + RsGxsSignature mSignature; }; @@ -136,10 +135,12 @@ public: * This may best be implemented as a singleton like current AuthGPG? \n * */ -class RsIdentityExchangeService : RsGeneralExchangeService +class RsIdentityExchangeService : RsGxsService { public: + enum IdentityType { Pseudonym, Signed, Anonymous }; + RsGixs(); /*! diff --git a/libretroshare/src/gxs/rsgroups.h b/libretroshare/src/gxs/rsgroups.h index 5b1023438..3852dde9e 100644 --- a/libretroshare/src/gxs/rsgroups.h +++ b/libretroshare/src/gxs/rsgroups.h @@ -132,6 +132,7 @@ class RsGroupManagement virtual bool allow_TwoPeers_TurtleTraffic (const SSLId& p1,const SSLId& p2) = 0 ; virtual bool allow_TwoPeers_Discovery (const SSLId& p1,const SSLId& p2) = 0 ; virtual bool allow_TwoPeers_LobbyAdvertisement(const SSLId& p1,const SSLId& p2) = 0 ; + virtual bool allow_TwoPeers_GeneralExchangeService(const SSLId& p1,const SSLId& p2) = 0 ; // [...] }; diff --git a/libretroshare/src/gxs/rsgxs.h b/libretroshare/src/gxs/rsgxs.h index 9325d094c..5685cdac1 100644 --- a/libretroshare/src/gxs/rsgxs.h +++ b/libretroshare/src/gxs/rsgxs.h @@ -38,7 +38,19 @@ #include #include +#include "rsgixs.h" +#include "rsgdp.h" + +#define GXS_STATUS_GRP_NOT_FOUND 1 /* request resulted in grp not found error */ +#define GXS_STATUS_MSG_NOT_FOUND 2 /* request resulted in msg not found */ +#define GXS_STATUS_ERROR 3 /* request is in error */ +#define GXS_STATUS_OK 4 /* request was successful */ + + typedef time_t RsGxsTime; +typedef std::map IdVersionM; +typedef std::multimap > GrpMsgMap; +typedef uint64_t RsGroupId ; class RsGxsLink { @@ -46,17 +58,26 @@ class RsGxsLink std::string msgId; }; -class RsGxsGroupItem { +class RsGxsGrpId{ - RsGxsId Id; +public: + + std::string grpId; + uint32_t version; }; +class RsGxsGroup { + std::set version; +}; -class RsGxsId { - std::string msgId; - std::string grpId; +class RsGxsMsgId { + +public: + std::string mMsgId; + std::string mGrpId; + uint32_t mVersion; }; @@ -66,15 +87,15 @@ class RsGxsSearchResult { class RsGxsMsg { - RsGxsId mId; + RsGxsMsgId mId; std::string mMsgId; std::string mOrigMsgId; RsGxsTime mTime; std::list mHashtags; std::list mLinked; - - RsGxpSignature mSignature; + std::set versions; + RsGxsSignature mSignature; }; /*! @@ -88,16 +109,19 @@ class RsGxsSearchItem { /*! * The whole idea is to provide a broad enough base class from which - * all the services listed in gxs/db_apps.h - * + * all the services listed in gxs/db_apps.h can be implemented + * The exchange service features a token redemption request/receive + * design in which services make as request to the underlying base + * class which returns a token which the service should redeem later + * when the request's corresponding receive is called later * Main functionality: \n * * Compared to previous cache-system, some improvements are: \n * * On-demand: There is granularity both in time and hiearchy on whats \n * locally resident, all this is controlled by service \n - * hiearchy - only grps are completely sync'd, have to request msgs \n - * time - grps and hence messages to sync if in time range, grp locally resident but outside range are kept \n + * * hiearchy - only grps are completely sync'd, have to request msgs \n + * * time - grps and hence messages to sync if in time range, grps locally resident but outside range are kept \n * * Search: \n * User can provide search terms (RsGxsSearchItem) that each service can use to retrieve \n @@ -106,7 +130,7 @@ class RsGxsSearchItem { * * Actual data exchanging: \n * Currently naming convention is a bit confused between 'items' or 'messages' \n - * - consider item and msgs to be the same for now RsGxsId, gives easy means of associate msgs to grps \n + * - consider item and msgs to be the same for now, RsGxsId, gives easy means of associate msgs to grps \n * - all data is received via call back \n * - therefore interface to UI should not be based on being alerted to msg availability \n */ @@ -116,76 +140,159 @@ class RsGxsService public: + /***************** Group request receive API ********************/ + /*! - * For requesting Msgs - * + * Request group, not intialising version member of RsGxsGrpId + * results in the latest version of group being returned + * @param grpIds the id/version of the group requested + * @return token for request */ - void requestGrp(std::string& grpId); + int requestGrp(std::list& grpIds); + + /*! + * pulls in all grps held by peer + * @param grpIds the id/version of the group requested + * @return token for request + * @see receiveGrp() + */ + int requestPeersGrps(const std::string& sslId); /*! - * Event call back for GXS runner - * this is called alerting the user that messages have been received - * @param msgsReceived set of messages received + * returns IDs of groups which are still in valid time range + * @return token for request */ - void received(std::list& itemsReceived); + int requestGrpList(); + + /*! + * @param token the token to be redeemed + * @param grpList list of group ids associated to request token + */ + virtual void receiveGrpList(int token, std::list& grpList) = 0; + + /*! + * Event call back from Gxs runner + * after requested Grp(s) have been retrieved + * @param token the token to be redeemed + * @param grps list of groups associated to request token + */ + virtual void receiveGrp(int token, std::set& grps) = 0; + + /*************** Start: Msg request receive API ********************/ + + /* Messages a level below grps on the hiearchy hence group requests */ + /* are intrinsically linked to their grp Id */ + + + /*! + * request latest version of messages for group + * @param token for request + * @see receiveMsg() + */ + int requestGrpMsgs(std::list&); + + /*! + * More fine grained request of msgs + * @param msgs the message to request, based on id, and version + * @param token for request + * @see receiveMsg() + */ + int requestMsgs(std::list& msgs); + + /*! + * pulls in all data held by peer + * @param grpIds the id/version of the group requested + * @return token for request + * @see receiveMsg() + */ + int requestPeersMsgs(std::string sslId, const RsGxsGrpId& grpId); + + /*! + * Event call back from GxsRunner + * after request msg(s) have been received + * @param token token to be redeemed + */ + virtual void receiveMsg(int token, std::set& msgs) = 0; + + /*! + * request message ids for grp + * @param msgIdSet set of id for msg + * @return token to be redeemed + */ + int requestGrpMsgIdList(std::list& msgIds); + /*! * + * @param token to be redeemed + * @param the msgIdSet associated to request token + */ + virtual void receiveMsgIdList(int token, std::list& msgIdList) = 0; + + + /*! * @param searchToken token to be redeemed * @param result result set */ void receivedSearchResult(int searchToken, std::set results); + + /*************** End: Msg request receive API ********************/ + + + /*********** Start: publication *****************/ + /*! * Pushes a RsGxsItem for publication * @param msg set of messages to push onto service for publication */ - void pushMsg(std::set& msg); + void pushMsg(std::set& msg); /*! - * Pushes a RsGxsGroupItem - * @param msg set of messages to push onto service for publication + * Pushes a RsGxsGroup on RsGxsNetwork and associates it with a \n + * given RsGixs profile + * @param grp group to push onto network + * @return error code */ - void pushGrp(std::set& grp); + int pushGrp(std::set& grp, std::string& profileName); /*! - * Event call back from GxsRunner - * after request msg(s) have been received - */ - void receiveItem(std::set& items); - - /*! - * Event call back from Gxs runner - * after requested Grp(s) have been retrieved - */ - void receiveGrp(std::set& grps); - - /****************************************************************************************************/ - // Event Callback for the service. - /****************************************************************************************************/ - - notify_groupChanged(); // Mainly for GUI display. - notify_newMessage(); // used for newsFeeds. - notify_duplicateMessage(); // Channels needs this for Downloading stuff, can probably be moved above. - locked_checkDistribMsg(); // required overload? - - - /****************************************************************************************************/ - // Must worry about sharing keys. - // Can gixp handle it? - // What interfaces do we need here? - // RsGDS deals with most things internally (decrypting, verifying), can put identity creation here to ease - /****************************************************************************************************/ - - /*! - * can choose the share created identity immediately or use identity service later to share it - * @param type + * Pushes a RsGxsGroup onto RsGxs network, associates it with an RsGixs profile to be + * created given the parameters below + * @param grp set of messages to push onto service for publication + * @param type the type of identity to create * @param peers peers to share this identity with * @param pseudonym if type is pseudonym then uses this as the name of the pseudonym Identity */ - void createIdentity(int type, std::set peers, const std::string pseudonymName); + void pushGrp(std::set& grp, RsIdentityExchangeService::IdentityType type, const std::set& peers, + RsGxsGroup*& group, const std::string& pseudonymName = ""); + + /*********** End: publication *****************/ + + /*************************************************************************/ + // The main idea here is each RsGroup needs permission set for each RsGxsGroup + // Thus a + // This is a configuration thing. + /*************************************************************************/ + /*********** Start: Identity control and groups *****************/ + + /*! + * can choose the share created identity immediately or use identity service later to share it + * if type is pseudonym and pseudonym field is empty, identity creation will fail + * @param group is now associated + */ + void getProfile(std::string profileName); + + /*! + * + * This sets an RsGroup to be able to share file between its members + * Default behaviour on group sharing is share with between all peers + */ + void setShareGroup(const std::list&, const RsGxsGrpId& grpId); + + /*********** End: Identity control and groups *****************/ /****************************************************************************************************/ @@ -194,89 +301,163 @@ public: // This is a configuration thing. /****************************************************************************************************/ - int flagItemRead(const RsGxsId& id); - int flagItemUnread(const RsGxsId& id); - int flagGroupRead(const RsGxsId& id); - int flagGroupUnread(const RsGxsId& id); - - /****************************************************************************************************/ - // External Interface for Data. - /****************************************************************************************************/ + /*********** Start: Update of groups/messages locally *****************/ /*! - * completes the creating of a group by associating it to an identity and creating its signature - * grp can then be pushed onto exchange - * @param grp the created grp - * @param IdentityId identity to associate created grp. Associates to an anonymous id which is created on the fly (or default anonymous id?) + * To flags message as read or not read in store + * @param GrpMsgMap flags this msg,version pair as read + * @param read set to true for read and false for unread */ - int createGroup(RsGxsGroupItem* grp, std::string& IdentityId); - - /*! - * completes the creation of a message by associating to an identity and creating its signature - * item can then be pushed onto exhange - * @param item the created item, ensure the grp id is set - * @return 0 if creationg failed - */ - int createItem(RsGxsItem* item); - - // Group Lists & Message Lists. - - /*! - * A group is marked as changed when it receives a new message, - * or its description has been modified - * @param groupIds set with ids of groups that have changed - */ - int getGroupsChanged(std::set &groupIds); - - /*! - * @param groupIds all groups locally resident on this exchange - */ - int getGroups(std::set &groupIds); - - /*! - * NB: looks useful, but not sure of usecase? - * @param from - * @param to - * @param grpIds - */ - int getGrpsForTimeRange(RsGxsTime from, RsGxsTime to, std::set grpIds); - - /*! - * Use this to get list of replacement Ids - * @param origIds id to check for replacements - * @param replaceIds list of ids that replace this id - */ - int getReplacementMsgs(const RsGxsId& origId, std::set replaceIds); + int flagMsgRead(const RsGxsMsgId& msgId, bool read) ; /*! - * Sets the oldest group one can pull off the exhange service - * and by definition the oldest message - * Does not affect locally resident data - * @param range sets the oldest allowable groupId to pull from exchange service + * To flag group as read or not read + * @param grpId the + * @param */ - void setGroupTimeRange(uint64_t cutoff); - - // Getting the Actual Data, data returned via 'received' call back - void getMsg(const std::set& itemIds); - void getGroup(const std::set& grpIds); - void getMsgsOfGroup(const std::string& grpId); - - - // Interface with GIXP Stuff... everything else should be behind the scenes. + int flagGroupRead(const RsGxsGrpId& grpId, bool read); /*! - * @param retrieve the profile of a given Identity id - * @return identity profile + * @param msgId */ - RsGixpProfile *getProfile(const RsGixsId&); + int requestDeleteMsg(const RsGxsMsgId& msgId); + + /*! + * This is grpId is marked in database to be removed + * and not circulated. Entry will later be removed + * once discard age is reached + */ + int requestDeleteGrp(const RsGxsGrpId& grpId); - // Immediate Search... - int localSearch(const RsGxsSearchItem&); + /******************* Start: Configuration *************************/ + + /*! + * How long to keep subscribed groups + * @param length how long to keep group in seconds + */ + void setSubscirbedGroupDiscardAge(uint32_t length); + + /*! + * How long to keep unsubscribed groups + * @param length how long to keep groups in seconds + */ + void setUnsubscribedGrpDiscardAge(uint32_t length); + + /*! + * How long to keep messages, group discard age supercedes this \n + * discard age + * @param length how long to keep messages in seconds + */ + int setMsgDiscardAge(uint32_t length); + + + /*! + * Use to subscribe or unsubscribe to group + * @param grpId the id of the group to scubscribe to + * @param subscribe set to false to unsubscribe and true otherwise + * @return token to redeem + */ + int requestSubscribeToGrp(const RsGxsGrpId& grpId, bool subscribe); + + /*! + * This called by event runner on status of subscription + * @param token the token to be redeemed + * @param gxsStatus the status of subscription request + */ + virtual void receiveSubscribeToGrp(int token, int gxsStatus) = 0; + + /******************* End: Configuration *************************/ + + /****************** Start: Notifications from event runner ***************/ + + /*! + * This is called by event runner when a group or groups \n + * have been updated or newly arrived + * @param grpId ids of groups that have changed or newly arrived + */ + virtual void notifyGroupChanged(std::list grpId) = 0; + + + /*! + * This is called by event runner when a msg or msg \n + * have been updated or newly arrived + * @param msgId ids of msgs that have changed or newly arrived + */ + virtual void notifyMsgChanged(std::list msgId) = 0; + + + /****************** End: Notifications from event runner ***************/ + + + /****************** Start: Search from event runner ***************/ + + // Users can either search groups or messages + + /*! + * Users + * Some standard search terms are supported + * @param term this allows users to search their local storage defined terms + * @return token to redeem search + */ + int requestLocalSearch(RsGxsSearch* term); // Remote Search...(2 hops ?) - int remoteSearch(const RsGxsSearchItem&); + /*! + * + * @param term This contains the search term + * @param hops how many hops to search up to + * @return token to redeem search + */ + int requestRemoteSearch(RsGxsSearch* term, uint32_t hops); + + + /*! + * + * @param token + * @param grpIds list of grp ids + */ + virtual void receiveLocalSearchGrps(int token, std::list& grpIds); + + /*! + * + * @param token the request token to be redeemed + * @param msgIds the message ids that contain contain search term + */ + virtual void receiveLocalSearchMsgs(int token, std::list &msgIds) = 0; + + /*! + * + * @param token request token to be redeemed + * @param grps + */ + virtual void receiveRemoteSearchGrps(int token, std::list& grps) = 0; + + /*! + * + * @param token the request token to be redeemed + * @param msgIds + */ + virtual void recieveRemoteSearchMsgs(int token, std::list& msgs) = 0; + + /*! + * Note if parent group is not present this will be requested \n + * by the event runner + * @param msgIds the ids of the remote messages being requested + * @return token to be redeemed + * @see receiveMsg() + */ + int requestRemoteMsg(std::list msgIds); + + /*! + * @param grpIds the ids of the group being requested + * @return token to be redeemed + * @see receiveGrp() + */ + int requestRemoteGrp(std::list& grpIds); + + /****************** End: Search from event runner ***************/ };