mirror of
https://github.com/RetroShare/RetroShare.git
synced 2024-10-01 02:35:48 -04:00
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
This commit is contained in:
parent
bb10b6b400
commit
8a7c011c5d
60
rsctrl/src/NOTES.txt
Normal file
60
rsctrl/src/NOTES.txt
Normal file
@ -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.
|
||||
|
||||
|
||||
|
||||
|
61
rsctrl/src/definition/base.proto
Normal file
61
rsctrl/src/definition/base.proto
Normal file
@ -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;
|
||||
}
|
||||
|
106
rsctrl/src/definition/peers.proto
Normal file
106
rsctrl/src/definition/peers.proto
Normal file
@ -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;
|
||||
}
|
||||
|
||||
///////////////////////////////////////////////////////////////
|
||||
|
Loading…
Reference in New Issue
Block a user