@@ -31,7 +32,7 @@ document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes(); a
IPC interface (interprocess communication)
Michael Stapelberg <michael@i3wm.org>
-October 2014
+September 2017
Table of Contents
@@ -91,85 +92,94 @@ they are in native byte order).
The magic string currently is "i3-ipc" and will only be changed when a change
in the IPC API is done which breaks compatibility (we hope that we donât need
to do that).
-
Currently implemented message types are the following:
-
-
-COMMAND (0)
-
-
-
- The payload of the message is a command for i3 (like the commands you
- can bind to keys in the configuration file) and will be executed
- directly after receiving it.
-
-
-
-GET_WORKSPACES (1)
-
-
-
- Gets the current workspaces. The reply will be a JSON-encoded list of
- workspaces (see the reply section).
-
-
-
-SUBSCRIBE (2)
-
-
-
- Subscribes your connection to certain events. See [events] for a
- description of this message and the concept of events.
-
-
-
-GET_OUTPUTS (3)
-
-
-
- Gets the current outputs. The reply will be a JSON-encoded list of outputs
- (see the reply section).
-
-
-
-GET_TREE (4)
-
-
-
- Gets the layout tree. i3 uses a tree as data structure which includes
- every container. The reply will be the JSON-encoded tree (see the reply
- section).
-
-
-
-GET_MARKS (5)
-
-
-
- Gets a list of marks (identifiers for containers to easily jump to them
- later). The reply will be a JSON-encoded list of window marks (see
- reply section).
-
-
-
-GET_BAR_CONFIG (6)
-
-
-
- Gets the configuration (as JSON map) of the workspace bar with the
- given ID. If no ID is provided, an array with all configured bar IDs is
- returned instead.
-
-
-
-GET_VERSION (7)
-
-
-
- Gets the version of i3. The reply will be a JSON-encoded dictionary
- with the major, minor, patch and human-readable version.
-
- Can be either "normal", "none" or "1pixel", dependending on the
+ Can be either "normal", "none" or "pixel", depending on the
containerâs border style.
@@ -618,7 +660,10 @@ urgent (bool)
- Whether this container (window or workspace) has the urgency hint set.
+ Whether this container (window, split container, floating container or
+ workspace) has the urgency hint set, directly or indirectly. All parent
+ containers up until the workspace container will be marked urgent if they
+ have at least one urgent child.
@@ -629,6 +674,34 @@ focused (bool)
Whether this container is currently focused.
+
+focus (array of integer)
+
+
+
+ List of child node IDs (see nodes, floating_nodes and id) in focus
+ order. Traversing the tree by following the first entry in this array
+ will result in eventually reaching the one node with focused set to
+ true.
+
+
+
+nodes (array of node)
+
+
+
+ The tiling (i.e. non-floating) child containers of this node.
+
+
+
+floating_nodes (array of node)
+
+
+
+ The floating child containers of this node. Only non-empty on nodes with
+ type workspace.
+
+
Please note that in the following example, I have left out some keys/values
which are not relevant for the type of the node. Otherwise, the example would
@@ -729,7 +802,7 @@ VGA1
"y": 0,
"width": 1280,
"height": 0
- },
+ }
},
{
@@ -946,44 +1019,78 @@ separator
+ Background color of the bar on the currently focused monitor output.
+
+
+
+focused_statusline
+
+
+
+ Text color to be used for the statusline on the currently focused
+ monitor output.
+
+
+
+focused_separator
- Text color/background color for a workspace button when the workspace
+ Text color to be used for the separator on the currently focused
+ monitor output.
+
- Text color/background color for a workspace button when the workspace
+ Text/background/border color for a workspace button when the workspace
is active (visible) on some output, but the focus is on another one.
You can only tell this apart from the focused workspace when you are
using multiple monitors.
- Text color/background color for a workspace button when the workspace
+ Text/background/border color for a workspace button when the workspace
does not have focus and is not active (visible) on any output. This
will be the case for most workspaces.
- Text color/background color for workspaces which contain at least one
+ Text/background/border color for workspaces which contain at least one
window with the urgency hint set.
The reply consists of an array of all currently configured binding modes.
+
Example:
+
+
+
["default", "resize"]
+
+
+
+
3.11. CONFIG reply
+
The config reply is a map which currently only contains the "config" member,
+which is a string containing the config file as loaded by i3 most recently.
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 }
+
+
@@ -1153,6 +1301,24 @@ 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:
@@ -1177,9 +1343,9 @@ if ($is_event) {
4.3. workspace event
This event consists of a single serialized map containing a property
change (string) which indicates the type of the change ("focus", "init",
-"empty", "urgent"). A current (object) property will be present with the
-affected workspace whenever the type of event affects a workspace (otherwise,
-it will be +null).
+"empty", "urgent", "reload", "rename", "restored", "move"). A
+current (object) property will be present with the affected workspace
+whenever the type of event affects a workspace (otherwise, it will be +null).
When the change is "focus", an old (object) property will be present with the
previous workspace. When the first switch occurs (when i3 focuses the
workspace visible at the beginning) there is no previous workspace, and the
@@ -1220,11 +1386,15 @@ property.
This event consists of a single serialized map containing a property
change (string) which holds the name of current mode in use. The name
is the same as specified in config when creating a mode. The default
-mode is simply named default.
+mode is simply named default. It contains a second property, pango_markup, which
+defines whether pango markup shall be used for displaying this mode.
@@ -1234,42 +1404,47 @@ mode is simply named default.
-new - the window has become managed by i3
+new â the window has become managed by i3
+
+
+
+
+close â the window has closed
-close - the window has closed
+focus â the window has received input focus
-focus - the window has received input focus
+title â the window’s title has changed
-title - the window’s title has changed
+fullscreen_mode â the window has entered or exited fullscreen mode
-fullscreen_mode - the window has entered or exited fullscreen mode
+move â the window has changed its position in the tree
-move - the window has changed its position in the tree
+floating â the window has transitioned to or from floating
-floating - the window has transitioned to or from floating
+urgent â the window has become urgent or lost its urgent status
-urgent - the window has become urgent or lost its urgent status
+mark â a mark has been added to or removed from the window
@@ -1300,7 +1475,7 @@ same as a GET_BAR_CONFIG reply for the bar with the given id.
4.8. binding event
This event consists of a single serialized map reporting on the details of a
-binding that ran a command because of user input. The change (sring) field
+binding that ran a command because of user input. The change (string) field
indicates what sort of binding event was triggered (right now it will always be
"run" but may be expanded in the future).
The binding (object) field contains details about the binding that was run:
@@ -1314,11 +1489,11 @@ command (string)
-mods (array of strings)
+event_state_mask (array of strings)
- The modifier keys that were configured with this binding.
+ The group and modifier keys that were configured with this binding.
This event is triggered when the connection to the ipc is about to shutdown
+because of a user action such as a restart or exit command. The change
+(string) field indicates why the ipc is shutting down. It can be either
+"restart" or "exit".
+
Example:
+
+
+
{
+ "change": "restart"
+}
+
+
+
+
4.10. 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):
6. Appendix A: Detecting byte order in memory-safe languages
+
+
Some programming languages such as Go donât offer a way to serialize data in the
+native byte order of the machine theyâre running on without resorting to tricks
+involving the unsafe package.
+
The following technique can be used (and will not be broken by changes to i3) to
+detect the byte order i3 is using:
+
+
+
+The byte order dependent fields of an IPC message are message type and
+ payload length.
+
+
+
+
+The message type RUN_COMMAND (0) is the same in big and little endian, so
+ we can use it in either byte order to elicit a reply from i3.
+
+
+
+
+The payload length 65536 + 256 (0x00 01 01 00) is the same in big and
+ little endian, and also small enough to not worry about memory allocations
+ of that size. We must use payloads of length 65536 + 256 in every message
+ we send, so that i3 will be able to read the entire message regardless of
+ the byte order it uses.
+
+
+
+
+
+
+Send a big endian encoded message of type SUBSCRIBE (2) with payload []
+ followed by 65536 + 256 - 2 SPACE (ASCII 0x20) bytes.
+
+
+
+
+If i3 is running in big endian, this message is treated as a noop,
+ resulting in a SUBSCRIBE reply with payload {"success":true}
+ [A small payload is important: that way, we circumvent dealing
+ with UNIX domain socket buffer sizes, whose size depends on the
+ implementation/operating system. Exhausting such a buffer results in an i3
+ deadlock unless you concurrently read and write, which â depending on the
+ programming language â makes the technique much more complicated.] .
+
+
+
+
+If i3 is running in little endian, this message is read in its entirety due
+ to the byte order independent payload length, then
+ silently
+ discarded due to the unknown message type.
+
+
+
+
+
+
+Send a byte order independent message, i.e. type RUN_COMMAND (0) with
+ payload nop byte order detection. padding:, padded to 65536 + 256 bytes
+ with a (ASCII 0x61) bytes. i3 will reply to this message with a reply of
+ type COMMAND (0).
+
+
+
+
+The human-readable prefix is in there to not confuse readers of the i3 log.
+
+
+
+
+This messages serves as a synchronization primitive so that we know whether
+ i3 discarded the SUBSCRIBE message or didnât answer it yet.
+
+
+
+
+
+
+Receive a message header from i3, decoding the message type as big endian.
+
+
+
+
+If the messageâs reply type is COMMAND (0), i3 is running in little
+ endian (because the SUBSCRIBE message was discarded). Decode the message
+ payload length as little endian, receive the message payload.
+
+
+
+
+If the messageâs reply type is anything else, i3 is running in big endian
+ (because our big endian encoded SUBSCRIBE message was answered). Decode
+ the message payload length in big endian, receive the message
+ payload. Then, receive the pending COMMAND message reply in big endian.
+
+
+
+
+
+
+From here on out, send/receive all messages using the detected byte order.
+