Added Directory structure for new rsctrl protocol.

* see NOTES.txt for how to implement it.
 * protobuf definitions are in rsctrl/src/definition

This does not compile yet, and just early thoughts.
Suggestions and help developing this are welcome.



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

rsctrl/src/NOTES.txt

@@ -0,0 +1,60 @@
+
+This document proposes the finer details of how to communicate with RS, 
+using SSH and protobuf classes.
+==========================================================================
+
+Message Format
+====================
+
+Protobuf serialisation does not identify Message Types or Message Size.
+So we need to have an encapsulation header system 
+
+These headers describe the actual message via a MsgId and MsgSize.
+Care must be taken to ensure these IDS are correct, as this is NOT enforced
+by protobuf, and will lead to incorrect deserialisation!
+
+In Each .proto there is a list of MsgIds as an ENUM.
+
+The protocol message format is as follows: 
+	[HEADER: 16 bytes: 4 x Network Order uint32_t][ VARIABLE LENGTH BODY ] 
+
+	[ MAGIC_CODE ] [ MSG_ID ] [ REQ_ID ] [ BODY_SIZE ] [ ..... BODY ..... ]
+	MagicCode = 0x137f0001. will be incremented for new versions of the protocol.
+ 	MsgID = Corresponds to the format of the Body.
+	ReqID = Generated by Requester, Returned in Response, 
+		make sure its unique. (undefined behaviour for duplicates)
+        BodySize = Byte Length of Body.
+
+	The Body will consist of a protobuf encoded message.
+
+
+Usage
+=================
+ * Create SSH connection to retroshare-nogui.
+ * Create Request Message(s), and send over SSH channel - You can send as meny requests as you want. 
+ * They will processed, and responses sent back (potentially in an arbitary order).
+
+MsgIDs
+=================
+In Each .proto there is a list of MsgIds as an ENUM.
+
+0x00 XX XX xx	=> Reserved for libretroshare Requests. (XX - area, xxxx specific msg)
+0x01 XX XX xx	=> Reserved for libretroshare Responses
+
+eg. 0x00 (fa bc) [01] -> Request, 0x01 (fa bc) [01/02/03] -> responses
+
+0x10 YY YY yy   => Extensions for project YY (16k), with sub commands yy (256)
+0x11 YY YY yy
+
+... if we run out of YY's will use 0x20 etc.
+
+
+Extensions
+=================
+
+These are welcome and encouraged.
+We just need to make sure that MsgIDs don't clash.
+
+
+
+

rsctrl/src/definition/base.proto

@@ -0,0 +1,61 @@
+package rsctrl.base:
+
+///////////////////////////////////////////////////////////////
+// These are basic Messages, which are used as building blocks
+// throughout the rest of the interface.
+// They should not be sent RAW, but should be wrapped in another msg.
+///////////////////////////////////////////////////////////////
+
+///////////////////////////////////////////////////////////////
+// Basic Status Response, should be in all responses
+
+message Status {
+  enum StatusCode {
+    FAILED        = 0;
+    INVALID_QUERY = 1;
+    SUCCESS       = 2;
+    READMSG       = 3;
+  }
+  required StatusCode code = 1;
+  optional string msg = 2;
+}
+
+///////////////////////////////////////////////////////////////
+// Peer structures, mainly rsctrl.peers related.
+
+message Location {
+  required string ssl_id = 1;
+  required string location = 2;
+
+  required string localaddr = 3;
+  required string extaddr   = 4;
+}
+
+message Person {
+  required string gpg_id = 1;
+  required string name = 2;
+
+  repeated Location locations = 3;
+}
+
+///////////////////////////////////////////////////////////////
+// File structures, mainly rsctrl.files related.
+
+message File {
+  required string name = 1;
+  required string hash = 2;
+  required int64  size = 3;
+
+  optional string path = 4;
+  optional string avail = 5;
+
+}
+
+message Dir {
+  required string name = 1;
+  required string path = 2;
+
+  repeated Dir subdirs = 3;
+  repeated File files = 4;
+}
+

rsctrl/src/definition/peers.proto

@@ -0,0 +1,106 @@
+package rsctrl.peers:
+///////////////////////////////////////////////////////////////
+// Access, and Control your Friends / Peers and related Settings.
+///////////////////////////////////////////////////////////////
+
+enum ExtensionId { BASE = 0; }
+enum PackageId { PEERS = 1; }
+
+enum RequestMsgIds {
+    RequestPeers = 1;
+    RequestAddPeer = 2;
+    RequestModifyPeer = 2;
+}
+
+enum ResponseMsgIds {
+    ResponsePeerList = 1;
+    ResponseAddPeer = 2;
+    ResponseModifyPeer = 2;
+}
+
+///////////////////////////////////////////////////////////////
+
+// REQUEST: RequestPeers
+message RequestPeers {
+
+  // About Who?
+  enum SetOption {
+    LISTED  = 1; 
+    ONLINE  = 2; 
+    FRIENDS = 3;
+    VALID   = 4; 	
+    ALL     = 5; 	
+  }
+
+  // What do you want?
+  enum InfoOption {
+    NAMEONLY = 1;
+    BASIC    = 2;
+    LOCATION = 3;
+    ALL      = 4;
+  }
+
+  required SetOption set = 1;
+  required InfoOption info = 2;
+  repeated string gpg_ids = 3;
+}
+
+
+// RESPONSE: ResponsePeerList
+message ResponsePeerList {
+  required rsctrl.base.Status status = 1;
+  repeated rsctrl.base.Person peers = 2;
+}
+
+///////////////////////////////////////////////////////////////
+
+// REQUEST: RequestAddPeer
+message RequestAddPeer {
+
+  enum AddCmd {
+    NOOP = 0; 		// No op.
+    ADD = 1; 		// Add existing from gpg_id.
+    REMOVE = 2; 	// Remove existing from gpg_id.
+    IMPORT = 3; 	// Import from cert, with gpg_id.
+    EXAMINE = 4; 	// Examine cert, but no action.
+  }
+
+  required string gpg_id = 1;
+  required AddCmd cmd = 2;
+  optional string cert = 3;
+}
+
+// RESPONSE: ResponseAddPeer
+message ResponseAddPeer {
+  required rsctrl.base.Status status = 1;
+  repeated rsctrl.base.Person peers = 2;
+}
+
+///////////////////////////////////////////////////////////////
+
+// REQUEST: RequestModifyPeer
+message RequestModifyPeer {
+
+  enum ModCmd {
+    NOOP    		= 0; 	
+    ADDRESS 		= 1;
+    DYNDNS  		= 2;
+    //SOMETHING_ELSE  	= 0x0000010; 
+    //SOMETHING_ELSE  	= 0x0000020; 
+    //SOMETHING_ELSE  	= 0x0000040; 
+    //SOMETHING_ELSE  	= 0x0000080; 
+  }
+
+  required ModCmd cmd = 1; 
+  //required int64 cmd = 1; // Could we OR the Cmds together?
+  repeated rsctrl.base.Person peers = 2;
+}
+
+// RESPONSE: ResponseModifyPeer
+message ResponseModifyPeer {
+  required rsctrl.base.Status status = 1;
+  repeated rsctrl.base.Person peers = 2;
+}
+
+///////////////////////////////////////////////////////////////
+