IPC interface (interprocess communication)
==========================================
Michael Stapelberg <michael@i3wm.org>
-August 2012
+October 2012
This document describes how to interface with i3 from a separate process. This
is useful for example to remote-control i3 (to write test cases for example) or
All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+
X11 property, stored on the X11 root window.
+[WARNING]
+.Use an existing library!
+There are existing libraries for many languages. You can have a look at
+<<libraries>> or search the web if your language of choice is not mentioned.
+Usually, it is not necessary to implement low-level communication with i3
+directly.
+
== Establishing a connection
To establish a connection, simply open the IPC socket. The following code
Or, as a hexdump:
------------------------------------------------------------------------------
00000000 69 33 2d 69 70 63 04 00 00 00 00 00 00 00 65 78 |i3-ipc........ex|
-00000010 69 74 0a |it.|
+00000010 69 74 |it|
------------------------------------------------------------------------------
To generate and send such a message, you could use the following code in Perl:
+change (string)+ which indicates the type of the change ("focus", "init",
"empty", "urgent").
+Moreover, when the change is "focus", an +old (object)+ and a +current
+(object)+ properties will be present with the previous and current
+workspace respectively. When the first switch occurs (when i3 focuses
+the workspace visible at the beginning) there is no previous
+workspace, and the +old+ property will be set to +null+. Also note
+that if the previous is empty it will get destroyed when switching,
+but will still be present in the "old" property.
+
*Example:*
---------------------
-{ "change": "focus" }
+{
+ "change": "focus",
+ "current": {
+ "id": 28489712,
+ "type":4,
+ ...
+ }
+ "old": {
+ "id": 28489715,
+ "type": 4,
+ ...
+ }
+}
---------------------
=== output event
{ "change": "default" }
---------------------------
-== See also
+== See also (existing libraries)
+
+[[libraries]]
For some languages, libraries are available (so you don’t have to implement
all this on your own). This list names some (if you wrote one, please let me
Python::
* https://github.com/whitelynx/i3ipc
* https://github.com/ziberna/i3-py (includes higher-level features)
+Go::
+ * https://github.com/proxypoke/i3ipc