xC/xP: mark highlights and buffer activity

And more or less finalize out the protocol for this use case.

1 files changed, 17 insertions, 1 deletions

diff --git a/xC-proto b/xC-proto
index d25a118..46955e7 100644
--- a/xC-proto
+++ b/xC-proto
@@ -3,6 +3,8 @@ const VERSION = 1;
 
 // From the frontend to the relay.
 struct CommandMessage {
+	// The command sequence number will be repeated in responses
+	// in the respective fields.
 	u32 command_seq;
 	union CommandData switch (enum Command {
 		HELLO,
@@ -15,6 +17,9 @@ struct CommandMessage {
 	} command) {
 	case HELLO:
 		u32 version;
+		// If the version check succeeds, the client will receive
+		// an initial stream of BUFFER_UPDATE, BUFFER_LINE,
+		// and finally a BUFFER_ACTIVATE message.
 	case PING:
 		void;
 	case ACTIVE:
@@ -51,6 +56,15 @@ struct EventMessage {
 		void;
 	case BUFFER_UPDATE:
 		string buffer_name;
+		// These are cumulative, even for lines flushed out from buffers.
+		// Updates to these values aren't broadcasted, thus handle:
+		//  - BUFFER_LINE by bumping/setting them as appropriate,
+		//  - BUFFER_ACTIVATE by clearing them for the previous buffer
+		//    (this way, they can be used to mark unread messages).
+		// Any updates received after the initial sync should be ignored.
+		u32 new_messages;
+		u32 new_unimportant_messages;
+		bool highlighted;
 	case BUFFER_RENAME:
 		string buffer_name;
 		string new;
@@ -60,6 +74,7 @@ struct EventMessage {
 		string buffer_name;
 	case BUFFER_LINE:
 		string buffer_name;
+		// Whether the line should also be displayed in the active buffer.
 		bool leak_to_active;
 		bool is_unimportant;
 		bool is_highlight;
@@ -106,7 +121,8 @@ struct EventMessage {
 	case BUFFER_CLEAR:
 		string buffer_name;
 
-	// Restriction: command_seq is strictly increasing, across both of these.
+	// Restriction: command_seq strictly follows the sequence received
+	// by the relay, across both of these replies.
 	case ERROR:
 		u32 command_seq;
 		string error;