Penultimate touches to the RsGxsService interface

- added most request receive pairs for querying base service 
- Still need to finalise the RsGixs and Search functionality, look at p3DistribSecurity for this

git-svn-id: http://svn.code.sf.net/p/retroshare/code/branches/v0.5-new_cache_system@5013 b45a01b8-16f6-495d-af2f-9b41ad6348cc

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<grpId, pair<msgId,version> >)
-           void receiveMsgs(int token, std::list<RsGxsMsg*>); // call back		
+                void receiveMsgs(int token, std::list<RsGxsMsg*>); // 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<grpId, pair<msgId,version> >)
+		returned with message
-		int requestGrpIdentity(string grpId)
 		----------------
 
 	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<grpId, pair<msgId,version> >)
-		int receivedNewUpdates(multimap<grpId, version> >)
+		int receivedNewUpdates(map<grpId, version> >)
 		----------------
 
 	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<grpId, version>)
+		int GXService::updateGroup(multimap<grpId, version>)
 		----------------
 
 		---------------- 		

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

libretroshare/src/gxs/rsgixs.h

@@ -91,17 +91,16 @@ class KeyRefSet {
 };
 
 class SignatureSet {
-    std::set<Signature> mSignatureSet;
+    std::set<RsGxsSignature> 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();
 
     /*!

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 ;
 		// [...]
 };
 

libretroshare/src/gxs/rsgxs.h

@@ -38,7 +38,19 @@
 #include <set>
 #include <map>
 
+#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<std::string, uint32_t> IdVersionM;
+typedef std::multimap<std::string, std::pair<std::string, uint32_t> > 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<uint32_t> version;
+};
 
-class RsGxsId {
 
-    std::string msgId;
+class RsGxsMsgId {
-    std::string grpId;
+
+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<std::string> mHashtags;
         std::list<RsGxsLink> mLinked;
-
+        std::set<uint32_t> versions;
-        RsGxpSignature mSignature;
+        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
+ *      * 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
+ *      * 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<RsGxsGrpId>& 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
+     * returns IDs of groups which are still in valid time range
-     * this is called alerting the user that messages have been received
+     * @return token for request
-     * @param msgsReceived set of messages received
      */
-    void received(std::list<RsGxsId>& 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<RsGxsGrpId>& 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<RsGxsGroup*>& 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<RsGxsGrpId>&);
+
+    /*!
+     * 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<RsGxsMsgId>& 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<RsGxsMsg*>& msgs) = 0;
+
+    /*!
+     * request message ids for grp
+     * @param msgIdSet set of id for msg
+     * @return token to be redeemed
+     */
+    int requestGrpMsgIdList(std::list<RsGxsGrpId>& msgIds);
+
 
     /*!
      *
+     * @param token to be redeemed
+     * @param the msgIdSet associated to request token
+     */
+    virtual void receiveMsgIdList(int token, std::list<RsGxsMsgId>& msgIdList) = 0;
+
+
+    /*!
      * @param searchToken token to be redeemed
      * @param result result set
      */
     void receivedSearchResult(int searchToken, std::set<RsGxsSearchResult*> 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<RsGxsItem*>& msg);
+    void pushMsg(std::set<RsGxsMsg*>& msg);
 
 
     /*!
-     * Pushes a RsGxsGroupItem
+     * Pushes a RsGxsGroup on RsGxsNetwork and associates it with a \n
-     * @param msg set of messages to push onto service for publication
+     * given RsGixs profile
+     * @param grp group to push onto network
+     * @return error code
      */
-    void pushGrp(std::set<RsGxsGroupItem*>& grp);
+    int pushGrp(std::set<RsGxsGroup*>& grp, std::string& profileName);
 
     /*!
-     * Event call back from GxsRunner
+     * Pushes a RsGxsGroup onto RsGxs network, associates it with an RsGixs profile to be
-     * after request msg(s) have been received
+     * created given the parameters below
-     */
+     * @param grp set of messages to push onto service for publication
-    void receiveItem(std::set<RsGxsItem*>& items);
+     * @param type the type of identity to create
-
-    /*!
-     * Event call back from Gxs runner
-     * after requested Grp(s) have been retrieved
-     */
-    void receiveGrp(std::set<RsGxsGroupItem*>& 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
      * @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<std::string> peers, const std::string pseudonymName);
+    void pushGrp(std::set<RsGxsGroup*>& grp, RsIdentityExchangeService::IdentityType type, const std::set<std::string>& 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<RsGroupId>&, const RsGxsGrpId& grpId);
+
+    /*********** End: Identity control and groups *****************/
 
 
     /****************************************************************************************************/
@@ -194,89 +301,163 @@ public:
     // This is a configuration thing.
     /****************************************************************************************************/
 
-    int flagItemRead(const RsGxsId& id);
+    /*********** Start: Update of groups/messages locally *****************/
-    int flagItemUnread(const RsGxsId& id);
-    int flagGroupRead(const RsGxsId& id);
-    int flagGroupUnread(const RsGxsId& id);
-
-    /****************************************************************************************************/
-    // External Interface for Data.
-    /****************************************************************************************************/
 
     /*!
-     * completes the creating of a group by associating it to an identity and creating its signature
+     * To flags message as read or not read in store
-     * grp can then be pushed onto exchange
+     * @param GrpMsgMap flags this msg,version pair as read
-     * @param grp the created grp
+     * @param read set to true for read and false for unread
-     * @param IdentityId identity to associate created grp. Associates to an anonymous id which is created on the fly (or default anonymous id?)
      */
-    int createGroup(RsGxsGroupItem* grp, std::string& IdentityId);
+    int flagMsgRead(const RsGxsMsgId& msgId, bool read) ;
-
-    /*!
-     * 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<std::string> &groupIds);
-
-    /*!
-     * @param groupIds all groups locally resident on this exchange
-     */
-    int getGroups(std::set<std::string> &groupIds);
-
-    /*!
-     * NB: looks useful, but not sure of usecase?
-     * @param from
-     * @param to
-     * @param grpIds
-     */
-    int getGrpsForTimeRange(RsGxsTime from, RsGxsTime to, std::set<std::string> 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<RsGxsId> replaceIds);
 
 
     /*!
-     * Sets the oldest group one can pull off the exhange service
+     * To flag group as read or not read
-     * and by definition the oldest message
+     * @param grpId the
-     * Does not affect locally resident data
+     * @param
-     * @param range sets the oldest allowable groupId to pull from exchange service
      */
-    void setGroupTimeRange(uint64_t cutoff);
+    int flagGroupRead(const RsGxsGrpId& grpId, bool read);
-
-    // Getting the Actual Data, data returned via 'received' call back
-    void getMsg(const std::set<RsGxsId>& itemIds);
-    void getGroup(const std::set<std::string>& grpIds);
-    void getMsgsOfGroup(const std::string& grpId);
-
-
-    // Interface with GIXP Stuff... everything else should be behind the scenes.
 
     /*!
-     * @param retrieve the profile of a given Identity id
+     * @param msgId
-     * @return identity profile
      */
-    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...
+    /******************* Start: Configuration *************************/
-    int localSearch(const RsGxsSearchItem&);
+
+    /*!
+     * 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<RsGxsGrpId> 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<RsGxsMsgId> 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<RsGxsGrpId>& 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<RsGxsMsgId> &msgIds) = 0;
+
+    /*!
+     *
+     * @param token request token to be redeemed
+     * @param grps
+     */
+    virtual void receiveRemoteSearchGrps(int token, std::list<RsGxsGrpId>& grps) = 0;
+
+    /*!
+     *
+     * @param token the request token to be redeemed
+     * @param msgIds
+     */
+    virtual void recieveRemoteSearchMsgs(int token, std::list<RsGxsMsgId>& 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<RsGxsMsgId> msgIds);
+
+    /*!
+     * @param grpIds the ids of the group being requested
+     * @return token to be redeemed
+     * @see receiveGrp()
+     */
+    int requestRemoteGrp(std::list<RsGxsGrpId>& grpIds);
+
+    /****************** End: Search from event runner ***************/
 
 };