Added declaration of functions which would service GXS app requirements

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

libretroshare/src/gxs/UseCases.txt

@@ -2,76 +2,270 @@
 These are some example usages of the GxsService...
 All of these must be provided by the basic system.
 
+chris:
+Please not all request* functions have a receive pair if not noted below
+
 
 1) Forums
 ------------------------------------
 1.1) Display of subscribed forums.  Service must provide:
 	1.1.1) list of subscribed Groups.
 		----------------
-		GXService::getGroups(std::list<std::string> groupIds); 
+		int GXService::requestSubscribedGroupList(); @return token
-		----------------
+		void receiveGroupList(token, list<grpId>); //call back
+
 			-> This function will get the group list from
-				GDService::getGroups()....
+           Component:
+				GDService::requestGroup()
 		----------------
 	1.1.2) list of messages for each Group.
+           ----------------
+		int GDService::requestGroupMsgs(std::string grpId); @return token
+		-> Return a request token that will be redeemed by:
+              void receiveMsgs(int token, std::list<RsGxsMsg*>); // call back
+	      Component: 
+              GDService::request(string grpId) X
+ 			-> which further uses the client service's implemented 
+		----------------
 	1.1.3) details of group by group Id.
+           ----------------
+		int GDService::requestGroup(std::string grpId);
+           ----------------          
+
 	1.1.4) details of messages by message Id.
-	1.1.5) newest version of each message.
+           ----------------
+		int GXService::requestMessages(multimap<grpId, pair<msgId,version> >)
+           void receiveMsgs(int token, std::list<RsGxsMsg*>); // call back		
+           ----------------		
+
+	1.1.5) newest version of each message -> get version list.
+
+		----------------
+		? newest version returned by default
+		int GDService::requestMsgVersions(multimap<grpId, msgId>)
+		int receiveMsgVersionList(list<uint32_t>)
+		----------------
+
 	1.1.6) status of message (read / unread).
+
+		----------------
+		returned with msgs see 1.1.2 & 1.1.3
+		----------------
+
 	1.1.7) access to Identity associated with Group and Messages
+
+		----------------
+		int requestMsgIdentity(multimap<grpId, pair<msgId,version> >)
+		int requestGrpIdentity(string grpId)
+		----------------
+
 	1.1.8) updates when new groups arrive.
+
+		----------------
+		int receivedNewGrp(list<string> grpIds)
+		----------------
+
 	1.1.9) updates when new messages arrive.
+		----------------
+		int receivedNewMsgs(multimap<grpId, pair<msgId,version> >)
+		----------------
+
 	1.1.10) updates when groups / messages change.
+
+		----------------
+		int receivedNewUpdates(multimap<grpId, pair<msgId,version> >)
+		int receivedNewUpdates(multimap<grpId, version> >)
+		----------------
+
 	1.1.11) Search forums for Keywords.
+
+		----------------
+           int searchForum(string keyword, grpId)
+		// all msgs and grps that contain keyword
+   		int receiveSearchResult(list<RsGxsMsg*>, list<RsGxsGrp*>)
+		----------------
+
 	1.1.12) Access new (time restricted) messages.
+		----------------
+           ? explain
+		----------------
 
 1.2) Creation of new material.
 	1.2.1) ability to create Groups.
+
+		----------------
+		GDService::createGroup(name, descrip, title, thumbnail);
+           //or rather user 
+
+   		// user needs to instantiate their top class members
+		// where RsGxpGrp is base class
+		// user provides identity to associate group to
+		bool GDService::publishGroup(const RsGxsGrp&, identity);
+		RsGixsProfile* GXIService::createIdentity(int type, string pseudonym);
+		RsGixsProfile* GXIService::getRealIdentity();
+		----------------
+
 	1.2.2) ability to create Messages.
 
+		GXService::publishMsg(const RsGxsMsg&, identity);
+
 1.3) Deletion of forums and posts.
 	1.3.1) discard forum (can't do this currently).
+
 	1.3.2) delete post.
+		----------------
+		// post is removed from system and note made in db not to syn it
+		// this is cleaned from db after grp expires
+		int GXService::deleteMsg(multimap<grpId, msgId >)
+		int GXService::deleteGrp(grpId)
+		----------------
+
 	1.3.3) discard old posts.
+		----------------
+		done automatically by GDService based on cutoff
+		----------------
 
 1.4) Control of Forums 
+	
 	1.4.1) Storage Period of subscribed forums
+
+		---------------- 		
+		int GXService::setSubscribedGrpsCutOff(uint32_t secs)
+		----------------
+
 	1.4.2) Storage Period of unsubscribed forums.
+
+		---------------- 		
+		int GXService::setUnSubscribedGrpsCutOff(uint32_t secs)
+		----------------
+
 	1.4.3) transfer unsubscribed forums and posts (yes/no)
+
+		---------------- 		
+		don't think I want this, definitely default false
+		int GXService::allUnsubscribedTransfer(bool)
+		----------------
+
 	1.4.4) modify forums we own.
+
+		---------------- 		
+		int GXService::updateForum(multimap<grpId, version>)
+		----------------
+
+		---------------- 		
+		int GXService::updateMsg(multimap<grpId, msgId>)
+		----------------
+
 	1.4.5) modify read status.
 
+		---------------- 		
+		int GXService::setMsgRead(multimap<grpId, version> >)
+		----------------
+	1.4.6) Subscribe to forums
+
+		----------------
+		bool GXService::subscribeToGroup(grpId)
+		----------------
+ 		
 1.5) Finding other forums.
 	1.5.1) Listing of other forums.
+		int GXService::requestGroupList();
+		void receiveGroupList(token, list<grpId>); //call back
 	1.5.2) ability to temporarily get forum messages.
+	? Explain
 	1.5.3) search remote forums for keywords.
+		---------------- 
+		// service will have to provide own search module (can RsGDService can 
+		// service remote search requests concurrent with GXS)
+		// module return message and groups (msgs can be marked  compile time as not 		// searchable
+		GXService::localSearch(RsGxsSearch key)
+		GXService::searchRemote(RsGxsSearch key)
+		---------------- 
 	1.5.4) optional download of friends forums.
+		----------------
+		int GXService::downloadPeersGroups(sslid)
+		int GXService::downloadPeersMessage(ssld, grpId)
+		----------------
+
 
 2) Channels
 ------------------------------------
 2.1) Mostly like Forums, additional functionality.
 	2.1.1) Download files associated with Post.
 
+		---------------- 
+		? Explain, This should not be part of interface, this is feature specific 
+		---------------- 
+
 2.2) Comments
 	2.2.1) Write a comment.
+		---------------- 
+		see 1.2.2. Message with required top level members	
+		---------------- 
+
 	2.2.2) Reject (downgrade) bad comment.
+		---------------- 
+		user just needs to verify publisher sent message
+		bool GIXService::verify(Identity, data, dataLen, signature)
+		---------------- 
+	
 	2.2.3) Control Comments: Allow / Disallow, Pseudo / Authed Comments. 
+		---------------- 
+		bool GIXService::verify(Identity, data, dataLen, signature)
+
+		---------------- 
 
 
 3) Wiki
 ------------------------------------
 3.1) Editing functionality
 	3.1.1) Access to Latest Version.
+
+		---------------- 
+		Pls see 1.1.7
+		---------------- 
+
 	3.1.2) Access to Version History. (including who edited).
 
-3.2) Controlling Editing Rights.
+		---------------- 
+		// need to include list<authors> as top level RsGxsMsg 
+		---------------- 
+
+	3.2) Controlling Editing Rights.
+
+		---------------- 
+		Pls see 1.1.7
+		---------------- 
+
+	
 	3.2.1) Rejecting an Edit.
+
+		---------------- 
+		using 1.2.2 publisher can send messages with private key signature that he 			does not accept edit 'x'
+		bool GXIService verify(Identity, data, dataLen, signature)
+		---------------- 
+
 	3.2.2) Changing Edit Rights.
+using 1.2.2, publisher sends new publish key under old private key signature, and user uses 
 
 3.3) Searching for Wikis.
 	3.3.1) Search for keyword.
+		---------------- 
+		see 1.5.3
+		---------------- 
+
 	3.3.2) Search for hashtag.
+		---------------- 
+		? Explain, anything different from keyword
+		see 1.5.3
+		---------------- 
+
+	
 	3.3.3) Search for pattern?
+		---------------- 
+		Bit more detail on search type
+		RsGxsSearch{ int searchType; const int PATTERN_TYPE, TERM_TYPE; ....}
+		---------------- 
 
 
 4) Wire (Twitter)
@@ -79,6 +273,10 @@ All of these must be provided by the basic system.
 4.1) Following Friends.
 	4.1.1) Adding Person.
 
+		----------------
+		See 1.4.6
+		---------------- 
+		
 
 4.2) Search The Wire.
 	4.2.1) Search for friends.
@@ -86,23 +284,58 @@ All of these must be provided by the basic system.
 	4.2.3) Search for keywords.
 	4.2.4) Search for Retweets.
 	4.2.5) Search for replies.
-
+		---------------- 
+		for 4.2.* see 3.3.1
+		---------------- 
 
 5) PhotoShare.
 ------------------------------------
 5.1) Controlling Access.
 	5.1.1) Friends Only.
+
+		---------------- 
+		GXService::setShareGroup(grpId, group=RsGroups::GROUP_FRIENDS)
+		---------------- 
+
 	5.1.2) Groups Only.
+
+		---------------- 
+		5.1.1
+		---------------- 
+
 	5.1.3) Everyone.
+		---------------- 
+		5.1.1 GXService::setShareGroup(grpId, group=RsGroups::GROUP_ALL)
+		---------------- 
+
 	5.1.4) Deleting Photographs.
+
+		---------------- 
+		1.3.2
+		---------------- 
+
 	5.1.4) Deleting Album.
+		---------------- 
+		1.3.2
+		---------------- 
 
 6) Acadeeb
 ------------------------------------
 6.1) Review Article.
-	6.1.1) Write Review.
+	6.1.1) Write Review/Rate.
+		---------------- 
+		see 1.2.2 for sending message 	
+		---------------- 
+
 	6.1.2) Recommend Article.
+		---------------- 
+		see 1.2.2 for sending message 	
+		---------------- 
 	6.1.3) Get Rating of Article.
+		---------------- 
+		See 3.2.1 and 2.2.2
+		---------------- 	
+
 
 6.2) Submit Review of Article
 	6.2.1) stuff.