docs/ipc: document that the highest bit is 1 for event replies

diff --git a/docs/ipc b/docs/ipc
index 4596039a28386b6e2bcfb40a169c00e378be38d9..5db6f00e55653f597ed4d8cd8c1f565b408e52c3 100644 (file)
--- 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