| 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:
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
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
"width": 1280,
"height": 782
},
+ "window_properties": {
+ "class": "Evince",
+ "instance": "evince",
+ "title": "Properties",
+ "transient_for": 52428808
+ },
"floating_nodes": [],
"nodes": [
{ "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
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. 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.
+(like I3_IPC_EVENT_WORKSPACE). Events sent by i3 follow a format similar to
+replies but with the highest bit of the message type set to 1 to indicate an
+event reply instead of a normal reply. Note that event types and reply types
+do not follow the same enumeration scheme (e.g. event type 0 corresponds to the
+workspace event however reply type 0 corresponds to the COMMAND 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
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
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:*
--------------------------------------------------------------------
}
---------------------------
+=== 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]]
* 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::
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