From 3a634f9ca0a8e201aa73823b62fcf21ff56210a2 Mon Sep 17 00:00:00 2001
From: Michael Stapelberg <michael@stapelberg.de>
Date: Sat, 29 Jan 2011 18:06:56 +0100
Subject: [PATCH] docs/ipc: document that the highest bit is 1 for event
 replies

---
 docs/ipc | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/docs/ipc b/docs/ipc
index d6f1a253..36a5d2b9 100644
--- a/docs/ipc
+++ b/docs/ipc
@@ -233,7 +233,8 @@ rect (map)::
 To get informed when certain things happen in i3, clients can subscribe to
 events. Events consist of a name (like "workspace") and an event reply type
 (like I3_IPC_EVENT_WORKSPACE). The events sent by i3 are in the same format
-as replies to specific commands.
+as replies to specific commands. However, the highest bit of the message type
+is set to 1 to indicate that this is an event reply instead of a normal reply.
 
 Caveat: As soon as you subscribe to an event, it is not guaranteed any longer
 that the requests to i3 are processed in order. This means, the following
@@ -254,16 +255,38 @@ type: SUBSCRIBE
 payload: [ "workspace", "focus" ]
 ---------------------------------
 
+
 === Available events
 
-workspace::
+The numbers in parenthesis is the event type (keep in mind that you need to
+strip the highest bit first).
+
+workspace (0)::
 	Sent when the user switches to a different workspace, when a new
 	workspace is initialized or when a workspace is removed (because the
 	last client vanished).
-output::
+output (1)::
 	Sent when RandR issues a change notification (of either screens,
 	outputs, CRTCs or output properties).
 
+*Example:*
+--------------------------------------------------------------------
+# the appropriate 4 bytes read from the socket are stored in $input
+
+# unpack a 32-bit unsigned integer
+my $message_type = unpack("L", $input);
+
+# check if the highest bit is 1
+my $is_event = (($message_type >> 31) == 1);
+
+# use the other bits
+my $event_type = ($message_type & 0x7F);
+
+if ($is_event) {
+  say "Received event of type $event_type";
+}
+--------------------------------------------------------------------
+
 === workspace event
 
 This event consists of a single serialized map containing a property