This repository has been archived by the owner on Apr 18, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
ipc
1085 lines (928 loc) · 35.7 KB
/
ipc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
IPC interface (interprocess communication)
==========================================
Michael Stapelberg <michael@i3wm.org>
September 2017
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
to get various information like the current workspaces to implement an external
workspace bar.
The method of choice for IPC in our case is a unix socket because it has very
little overhead on both sides and is usually available without headaches in
most languages. In the default configuration file, the ipc-socket gets created
in +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is
the PID of i3 and XXXXXX is a string of random characters from the portable
filename character set (see mkdtemp(3)). You can get the socketpath from i3 by
calling +i3 --get-socketpath+.
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
snippet illustrates this in Perl:
-------------------------------------------------------------
use IO::Socket::UNIX;
chomp(my $path = qx(i3 --get-socketpath));
my $sock = IO::Socket::UNIX->new(Peer => $path);
-------------------------------------------------------------
== Sending messages to i3
To send a message to i3, you have to format in the binary message format which
i3 expects. This format specifies a magic string in the beginning to ensure
the integrity of messages (to prevent follow-up errors). Following the magic
string comes the length of the payload of the message as 32-bit integer, and
the type of the message as 32-bit integer (the integers are not converted, so
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
[options="header",cols="^10%,^20%,^20%,^50%"]
|======================================================
| Type (numeric) | Type (name) | Reply type | Purpose
| 0 | +RUN_COMMAND+ | <<_command_reply,COMMAND>> | Run the payload as an i3 command (like the commands you can bind to keys).
| 1 | +GET_WORKSPACES+ | <<_workspaces_reply,WORKSPACES>> | Get the list of current workspaces.
| 2 | +SUBSCRIBE+ | <<_subscribe_reply,SUBSCRIBE>> | Subscribe this IPC connection to the event types specified in the message payload. See <<events>>.
| 3 | +GET_OUTPUTS+ | <<_outputs_reply,OUTPUTS>> | Get the list of current outputs.
| 4 | +GET_TREE+ | <<_tree_reply,TREE>> | Get the i3 layout tree.
| 5 | +GET_MARKS+ | <<_marks_reply,MARKS>> | Gets the names of all currently set marks.
| 6 | +GET_BAR_CONFIG+ | <<_bar_config_reply,BAR_CONFIG>> | Gets the specified bar configuration or the names of all bar configurations if payload is empty.
| 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.
| 12 | +GET_BINDING_STATE+ | <<_binding_state_reply,BINDING_STATE>> | Request the current binding state, e.g. the currently active binding mode name.
|======================================================
So, a typical message could look like this:
--------------------------------------------------
"i3-ipc" <message length> <message type> <payload>
--------------------------------------------------
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 |it|
------------------------------------------------------------------------------
To generate and send such a message, you could use the following code in Perl:
-------------------------------------------------------------------------------
sub format_ipc_command {
my ($msg) = @_;
my $len;
# Get the real byte count (vs. amount of characters)
{ use bytes; $len = length($msg); }
return "i3-ipc" . pack("LL", $len, 0) . $msg;
}
$sock->write(format_ipc_command("exit"));
-------------------------------------------------------------------------------
== Receiving replies from i3
Replies from i3 usually consist of a simple string (the length of the string
is the message_length, so you can consider them length-prefixed) which in turn
contain the JSON serialization of a data structure. For example, the
GET_WORKSPACES message returns an array of workspaces (each workspace is a map
with certain attributes).
=== Reply format
The reply format is identical to the normal message format. There also is
the magic string, then the message length, then the message type and the
payload.
The following reply types are implemented:
COMMAND (0)::
Confirmation/Error code for the RUN_COMMAND message.
WORKSPACES (1)::
Reply to the GET_WORKSPACES message.
SUBSCRIBE (2)::
Confirmation/Error code for the SUBSCRIBE message.
OUTPUTS (3)::
Reply to the GET_OUTPUTS message.
TREE (4)::
Reply to the GET_TREE message.
MARKS (5)::
Reply to the GET_MARKS message.
BAR_CONFIG (6)::
Reply to the GET_BAR_CONFIG message.
VERSION (7)::
Reply to the GET_VERSION message.
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.
GET_BINDING_STATE (12)::
Reply to the GET_BINDING_STATE message.
[[_command_reply]]
=== COMMAND reply
The reply consists of a list of serialized maps for each command that was
parsed. Each has the property +success (bool)+ and may also include a
human-readable error message in the property +error (string)+.
NOTE: When sending the `restart` command, you will get a singular reply once the
restart completed. All IPC connection states (e.g. subscriptions) will reset and
all but one socket will be closed. Libraries must be able to cope with this by
aligning their internal states. It is also recommended that libraries close
the last remaining socket(one which replied to `restart` command) to achieve
the full reset.
NOTE: It is easiest to always send the `restart` command alone: due to i3’s
state reset, the reply messages of preceding commands are lost, and following
commands will not be executed.
NOTE: When processing the `exit` command, i3 will immediately exit without
sending a reply. Expect the socket to be shut down.
*Example:*
-------------------
[{ "success": true }]
-------------------
[[_workspaces_reply]]
=== WORKSPACES reply
The reply consists of a serialized list of workspaces. Each workspace has the
following properties:
id (integer)::
The internal ID (actually a C pointer value) of this container. Do not
make any assumptions about it. You can use it to (re-)identify and
address containers when talking to i3.
num (integer)::
The logical number of the workspace. Corresponds to the command
to switch to this workspace. For named workspaces, this will be -1.
name (string)::
The name of this workspace (by default num+1), as changed by the
user. Encoded in UTF-8.
visible (boolean)::
Whether this workspace is currently visible on an output (multiple
workspaces can be visible at the same time).
focused (boolean)::
Whether this workspace currently has the focus (only one workspace
can have the focus at the same time).
urgent (boolean)::
Whether a window on this workspace has the "urgent" flag set.
rect (map)::
The rectangle of this workspace (equals the rect of the output it
is on), consists of x, y, width, height.
output (string)::
The video output this workspace is on (LVDS1, VGA1, …).
*Example:*
-------------------
[
{
"num": 0,
"name": "1",
"visible": true,
"focused": true,
"urgent": false,
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
},
"output": "LVDS1"
},
{
"num": 1,
"name": "2",
"visible": false,
"focused": false,
"urgent": false,
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
},
"output": "LVDS1"
}
]
-------------------
[[_subscribe_reply]]
=== SUBSCRIBE reply
The reply consists of a single serialized map. The only property is
+success (bool)+, indicating whether the subscription was successful (the
default) or whether a JSON parse error occurred.
*Example:*
-------------------
{ "success": true }
-------------------
[[_outputs_reply]]
=== OUTPUTS reply
The reply consists of a serialized list of outputs. Each output has the
following properties:
name (string)::
The name of this output (as seen in +xrandr(1)+). Encoded in UTF-8.
active (boolean)::
Whether this output is currently active (has a valid mode).
primary (boolean)::
Whether this output is currently the primary output.
current_workspace (string)::
The name of the current workspace that is visible on this output. +null+ if
the output is not active.
rect (map)::
The rectangle of this output (equals the rect of the output it
is on), consists of x, y, width, height.
*Example:*
-------------------
[
{
"name": "LVDS1",
"active": true,
"current_workspace": "4",
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
}
},
{
"name": "VGA1",
"active": true,
"current_workspace": "1",
"rect": {
"x": 1280,
"y": 0,
"width": 1280,
"height": 1024
}
}
]
-------------------
[[_tree_reply]]
=== TREE reply
The reply consists of a serialized tree. Each node in the tree (representing
one container) has at least the properties listed below. While the nodes might
have more properties, please do not use any properties which are not documented
here. They are not yet finalized and will probably change!
id (integer)::
The internal ID (actually a C pointer value) of this container. Do not
make any assumptions about it. You can use it to (re-)identify and
address containers when talking to i3.
name (string)::
The internal name of this container. For all containers which are part
of the tree structure down to the workspace contents, this is set to a
nice human-readable name of the container.
For containers that have an X11 window, the content is the title
(_NET_WM_NAME property) of that window.
For all other containers, the content is not defined (yet).
type (string)::
Type of this container. Can be one of "root", "output", "con",
"floating_con", "workspace" or "dockarea".
border (string)::
Can be either "normal", "none" or "pixel", depending on the
container’s border style.
current_border_width (integer)::
Number of pixels of the border width.
layout (string)::
Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or
"output".
Other values might be possible in the future, should we add new
layouts.
orientation (string)::
Can be either "none" (for non-split containers), "horizontal" or
"vertical".
THIS FIELD IS OBSOLETE. It is still present, but your code should not
use it. Instead, rely on the layout field.
percent (float)::
The percentage which this container takes in its parent. A value of
+null+ means that the percent property does not make sense for this
container, for example for the root container.
rect (map)::
The absolute display coordinates for this container. Display
coordinates means that when you have two 1600x1200 monitors on a single
X11 Display (the standard way), the coordinates of the first window on
the second monitor are +{ "x": 1600, "y": 0, "width": 1600, "height":
1200 }+.
window_rect (map)::
The coordinates of the *actual client window* inside its container.
These coordinates are relative to the container and do not include the
window decoration (which is actually rendered on the parent container).
So, when using the +default+ layout, you will have a 2 pixel border on
each side, making the window_rect +{ "x": 2, "y": 0, "width": 632,
"height": 366 }+ (for example).
deco_rect (map)::
The coordinates of the *window decoration* inside its container. These
coordinates are relative to the container and do not include the actual
client window.
geometry (map)::
The original geometry the window specified when i3 mapped it. Used when
switching a window to floating mode, for example.
window (integer)::
The X11 window ID of the *actual client window* inside this container.
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)::
This optional field contains all available X11 window properties from the
following list: *title*, *instance*, *class*, *window_role* and *transient_for*.
window_type (string)::
The window type (_NET_WM_WINDOW_TYPE). Possible values are undefined, normal,
dialog, utility, toolbar, splash, menu, dropdown_menu, popup_menu, tooltip and
notification.
urgent (bool)::
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.
marks (array of string)::
List of marks assigned to container
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.
fullscreen_mode (integer)::
Whether this container is in fullscreen state or not.
Possible values are
+0+ (no fullscreen),
+1+ (fullscreened on output) or
+2+ (fullscreened globally).
Note that all workspaces are considered fullscreened on their respective output.
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
be by far too long (it already is quite long, despite showing only 1 window and
one dock window).
It is useful to have an overview of the structure before taking a look at the
JSON dump:
* root
** LVDS1
*** topdock
*** content
**** workspace 1
***** window 1
*** bottomdock
**** dock window 1
** VGA1
*Example:*
-----------------------
{
"id": 6875648,
"name": "root",
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
},
"nodes": [
{
"id": 6878320,
"name": "LVDS1",
"layout": "output",
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 800
},
"nodes": [
{
"id": 6878784,
"name": "topdock",
"layout": "dockarea",
"orientation": "vertical",
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 0
}
},
{
"id": 6879344,
"name": "content",
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 782
},
"nodes": [
{
"id": 6880464,
"name": "1",
"orientation": "horizontal",
"rect": {
"x": 0,
"y": 0,
"width": 1280,
"height": 782
},
"window_properties": {
"class": "Evince",
"instance": "evince",
"title": "Properties",
"transient_for": 52428808
},
"floating_nodes": [],
"nodes": [
{
"id": 6929968,
"name": "#aa0000",
"border": "normal",
"percent": 1,
"rect": {
"x": 0,
"y": 18,
"width": 1280,
"height": 782
}
}
]
}
]
},
{
"id": 6880208,
"name": "bottomdock",
"layout": "dockarea",
"orientation": "vertical",
"rect": {
"x": 0,
"y": 782,
"width": 1280,
"height": 18
},
"nodes": [
{
"id": 6931312,
"name": "#00aa00",
"percent": 1,
"rect": {
"x": 0,
"y": 782,
"width": 1280,
"height": 18
}
}
]
}
]
}
]
}
-----------------------
[[_marks_reply]]
=== MARKS reply
The reply consists of a single array of strings for each container that has a
mark. A mark can only be set on one container, so the array is unique.
The order of that array is undefined.
If no window has a mark the response will be the empty array [].
[[_bar_config_reply]]
=== BAR_CONFIG reply
This can be used by third-party workspace bars (especially i3bar, but others
are free to implement compatible alternatives) to get the +bar+ block
configuration from i3.
Depending on the input, the reply is either:
empty input::
An array of configured bar IDs
Bar ID::
A JSON map containing the configuration for the specified bar.
Each bar configuration has the following properties:
id (string)::
The ID for this bar. Included in case you request multiple
configurations and want to differentiate the different replies.
mode (string)::
Either +dock+ (the bar sets the dock window type) or +hide+ (the bar
does not show unless a specific key is pressed).
position (string)::
Either +bottom+ or +top+ at the moment.
status_command (string)::
Command which will be run to generate a statusline. Each line on stdout
of this command will be displayed in the bar. At the moment, no
formatting is supported.
font (string)::
The font to use for text on the bar.
workspace_buttons (boolean)::
Display workspace buttons or not? Defaults to true.
binding_mode_indicator (boolean)::
Display the mode indicator or not? Defaults to true.
verbose (boolean)::
Should the bar enable verbose output for debugging? Defaults to false.
colors (map)::
Contains key/value pairs of colors. Each value is a color code in hex,
formatted #rrggbb (like in HTML).
The following colors can be configured at the moment:
background::
Background color of the bar.
statusline::
Text color to be used for the statusline.
separator::
Text color to be used for the separator.
focused_background::
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 to be used for the separator on the currently focused
monitor output.
focused_workspace_text/focused_workspace_bg/focused_workspace_border::
Text/background/border color for a workspace button when the workspace
has focus.
active_workspace_text/active_workspace_bg/active_workspace_border::
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.
inactive_workspace_text/inactive_workspace_bg/inactive_workspace_border::
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.
urgent_workspace_text/urgent_workspace_bg/urgent_workspace_border::
Text/background/border color for workspaces which contain at least one
window with the urgency hint set.
binding_mode_text/binding_mode_bg/binding_mode_border::
Text/background/border color for the binding mode indicator.
*Example of configured bars:*
--------------
["bar-bxuqzf"]
--------------
*Example of bar configuration:*
--------------
{
"id": "bar-bxuqzf",
"mode": "dock",
"position": "bottom",
"status_command": "i3status",
"font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",
"workspace_buttons": true,
"binding_mode_indicator": true,
"verbose": false,
"colors": {
"background": "#c0c0c0",
"statusline": "#00ff00",
"focused_workspace_text": "#ffffff",
"focused_workspace_bg": "#000000"
}
}
--------------
[[_version_reply]]
=== VERSION reply
The reply consists of a single JSON dictionary with the following keys:
major (integer)::
The major version of i3, such as +4+.
minor (integer)::
The minor version of i3, such as +2+. Changes in the IPC interface (new
features) will only occur with new minor (or major) releases. However,
bugfixes might be introduced in patch releases, too.
patch (integer)::
The patch version of i3, such as +1+ (when the complete version is
+4.2.1+). For versions such as +4.2+, patch will be set to +0+.
human_readable (string)::
A human-readable version of i3 containing the precise git version,
build date and branch name. When you need to display the i3 version to
your users, use the human-readable version whenever possible (since
this is what +i3 --version+ displays, too).
loaded_config_file_name (string)::
The current config path.
*Example:*
-------------------
{
"human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",
"loaded_config_file_name" : "/home/hwangcc23/.i3/config",
"minor" : 2,
"patch" : 0,
"major" : 4
}
-------------------
[[_binding_modes_reply]]
=== BINDING_MODES reply
The reply consists of an array of all currently configured binding modes.
*Example:*
---------------------
["default", "resize"]
---------------------
[[_config_reply]]
=== 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.
*Example:*
-------------------
{ "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 }
-------------------
[[_binding_state_reply]]
=== GET_BINDING_STATE reply
The binding_state reply is a map which currently only contains the "name"
member, which is the name of the currently active binding mode as a string.
*Example:*
-------------------
{ "name": "default" }
-------------------
== Events
[[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). 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
situation can happen: You send a GET_WORKSPACES request but you receive a
"workspace" event before receiving the reply to GET_WORKSPACES. If your
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
you can register to an event.
*Example:*
---------------------------------
type: SUBSCRIBE
payload: [ "workspace", "output" ]
---------------------------------
=== Available events
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 (1)::
Sent when RandR issues a change notification (of either screens,
outputs, CRTCs or output properties).
mode (2)::
Sent whenever i3 changes its binding mode.
window (3)::
Sent when a client's window is successfully reparented (that is when i3
has finished fitting it into a container), when a window received input
focus or when certain properties of the window have changed.
barconfig_update (4)::
Sent when the hidden_state or mode field in the barconfig of any bar
instance was updated and when the config is reloaded.
binding (5)::
Sent when a configured command binding is triggered with the keyboard or
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:*
--------------------------------------------------------------------
# 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
+change (string)+ which indicates the type of the change ("focus", "init",
"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
+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",
"current": {
"id": 28489712,
"type": "workspace",
...
}
"old": {
"id": 28489715,
"type": "workspace",
...
}
}
---------------------
=== output event
This event consists of a single serialized map containing a property
+change (string)+ which indicates the type of the change (currently only
"unspecified").
*Example:*
---------------------------
{ "change": "unspecified" }
---------------------------
=== mode event
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. It contains a second property, +pango_markup+, which
defines whether pango markup shall be used for displaying this mode.
*Example:*
---------------------------
{
"change": "default",
"pango_markup": true
}
---------------------------
=== window event
This event consists of a single serialized map containing a property
+change (string)+ which indicates the type of the change
* +new+ – the window has become managed by i3
* +close+ – the window has closed
* +focus+ – the window has received input focus
* +title+ – the window's title has changed
* +fullscreen_mode+ – the window has entered or exited fullscreen mode
* +move+ – the window has changed its position in the tree
* +floating+ – the window has transitioned to or from floating
* +urgent+ – the window has become urgent or lost its urgent status
* +mark+ – a mark has been added to or removed from the window
Additionally a +container (object)+ field will be present, which consists
of the window's parent container. Be aware that for the "new" event, the
container will hold the initial name of the newly reparented window (e.g.
if you run urxvt with a shell that changes the title, you will still at
this point get the window title as "urxvt").
*Example:*
---------------------------
{
"change": "new",
"container": {
"id": 35569536,
"type": "con",
...
}
}
---------------------------
=== barconfig_update event
This event consists of a single serialized map reporting on options from the
barconfig of the specified bar_id that were updated in i3. This event is the
same as a +GET_BAR_CONFIG+ reply for the bar with the given id.
=== 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 (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:
command (string)::
The i3 command that is configured to run for this binding.
event_state_mask (array of strings)::
The group and modifier keys that were configured with this binding.
input_code (integer)::
If the binding was configured with +bindcode+, this will be the key code
that was given for the binding. If the binding is a mouse binding, it will be
the number of the mouse button that was pressed. Otherwise it will be 0.
symbol (string or null)::
If this is a keyboard binding that was configured with +bindsym+, this
field will contain the given symbol. Otherwise it will be +null+.
input_type (string)::
This will be +"keyboard"+ or +"mouse"+ depending on whether or not this was
a keyboard or a mouse binding.
*Example:*
---------------------------
{
"change": "run",
"binding": {
"command": "nop",
"event_state_mask": [
"shift",
"ctrl"
],
"input_code": 0,
"symbol": "t",
"input_type": "keyboard"
}
}
---------------------------
=== shutdown event
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"
}
---------------------------
=== 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]]
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
know):
C::
* i3 includes a headerfile +i3/ipc.h+ which provides you all constants.
* https://github.com/acrisci/i3ipc-glib
C++::