Merge pull request #3372 from orestisf1993/direction

[i3/i3] / docs / ipc

diff --git a/docs/ipc b/docs/ipc
index 997a3055fb1c22b5393e4409d8fc18e450f08372..bcf8df1aa4abe5ba1c86fced66f689aba2fd05b4 100644 (file)
--- a/docs/ipc
+++ b/docs/ipc
@@ -64,6 +64,8 @@ to do that).
 | 7 | +GET_VERSION+ | <<_version_reply,VERSION>> | Gets the i3 version.
 | 8 | +GET_BINDING_MODES+ | <<_binding_modes_reply,BINDING_MODES>> | Gets the names of all currently configured binding modes.
 | 9 | +GET_CONFIG+ | <<_config_reply,CONFIG>> | Returns the last loaded i3 config.
+| 10 | +SEND_TICK+ | <<_tick_reply,TICK>> | Sends a tick event with the specified payload.
+| 11 | +SYNC+ | <<_sync_reply,SYNC>> | Sends an i3 sync event with the specified random value to the specified window.
 |======================================================
 
 So, a typical message could look like this:
@@ -126,6 +128,8 @@ BINDING_MODES (8)::
         Reply to the GET_BINDING_MODES message.
 GET_CONFIG (9)::
        Reply to the GET_CONFIG message.
+TICK (10)::
+       Reply to the SEND_TICK message.
 
 [[_command_reply]]
 === COMMAND reply
@@ -324,6 +328,8 @@ window (integer)::
        This field is set to null for split containers or otherwise empty
        containers. This ID corresponds to what xwininfo(1) and other
        X11-related tools display (usually in hex).
+window_properties (map)::
+       X11 window properties title, instance, class, window_role and transient_for.
 urgent (bool)::
        Whether this container (window, split container, floating container or
        workspace) has the urgency hint set, directly or indirectly. All parent
@@ -419,6 +425,12 @@ JSON dump:
            "width": 1280,
            "height": 782
          },
+         "window_properties": {
+           "class": "Evince",
+           "instance": "evince",
+           "title": "Properties",
+           "transient_for": 52428808
+         },
          "floating_nodes": [],
          "nodes": [
 
@@ -637,6 +649,31 @@ which is a string containing the config file as loaded by i3 most recently.
 { "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" }
 -------------------
 
+[[_tick_reply]]
+=== TICK reply
+
+The reply is a map containing the "success" member. After the reply was
+received, the tick event has been written to all IPC connections which subscribe
+to tick events. UNIX sockets are usually buffered, but you can be certain that
+once you receive the tick event you just triggered, you must have received all
+events generated prior to the +SEND_TICK+ message (happened-before relation).
+
+*Example:*
+-------------------
+{ "success": true }
+-------------------
+
+[[_sync_reply]]
+=== SYNC reply
+
+The reply is a map containing the "success" member. After the reply was
+received, the https://i3wm.org/docs/testsuite.html#i3_sync[i3 sync message] was
+responded to.
+
+*Example:*
+-------------------
+{ "success": true }
+-------------------
 
 == Events
 
@@ -656,6 +693,14 @@ program does not want to cope which such kinds of race conditions (an
 event based library may not have a problem here), I suggest you create a
 separate connection to receive events.
 
+If an event message needs to be sent and the socket is not writeable (write
+returns EAGAIN, happens when the socket doesn't have enough buffer space for
+writing new data) then i3 uses a queue system to store outgoing messages for
+each client. This is combined with a timer: if the message queue for a client is
+not empty and no data where successfully written in the past 10 seconds, the
+connection is killed. Practically, this means that your client should try to
+always read events from the socket to avoid having its connection closed.
+
 === Subscribing to events
 
 By sending a message of type SUBSCRIBE with a JSON-encoded array as payload
@@ -694,6 +739,10 @@ binding (5)::
        mouse
 shutdown (6)::
        Sent when the ipc shuts down because of a restart or exit by user command
+tick (7)::
+       Sent when the ipc client subscribes to the tick event (with +"first":
+       true+) or when any ipc client sends a SEND_TICK message (with +"first":
+       false+).
 
 *Example:*
 --------------------------------------------------------------------
@@ -866,6 +915,27 @@ because of a user action such as a +restart+ or +exit+ command. The +change
 }
 ---------------------------
 
+=== tick event
+
+This event is triggered by a subscription to tick events or by a +SEND_TICK+
+message.
+
+*Example (upon subscription):*
+--------------------------------------------------------------------------------
+{
+ "first": true,
+ "payload": ""
+}
+--------------------------------------------------------------------------------
+
+*Example (upon +SEND_TICK+ with a payload of +arbitrary string+):*
+--------------------------------------------------------------------------------
+{
+ "first": false,
+ "payload": "arbitrary string"
+}
+--------------------------------------------------------------------------------
+
 == See also (existing libraries)
 
 [[libraries]]
@@ -881,6 +951,7 @@ C++::
        * https://github.com/drmgc/i3ipcpp
 Go::
        * https://github.com/mdirkse/i3ipc-go
+       * https://github.com/i3/go-i3
 JavaScript::
        * https://github.com/acrisci/i3ipc-gjs
 Lua::
@@ -958,3 +1029,6 @@ detect the byte order i3 is using:
      payload. Then, receive the pending +COMMAND+ message reply in big endian.
 
 5. From here on out, send/receive all messages using the detected byte order.
+
+Find an example implementation of this technique in
+https://github.com/i3/go-i3/blob/master/byteorder.go