git.sur5r.net Git - i3/i3/blob - docs/ipc

   1 IPC interface (interprocess communication)
   2 ==========================================
   3 Michael Stapelberg <michael+i3@stapelberg.de>
   4 March 2010
   5
   6 This document describes how to interface with i3 from a separate process. This
   7 is useful for example to remote-control i3 (to write test cases for example) or
   8 to get various information like the current workspaces to implement an external
   9 workspace bar.
  10
  11 The method of choice for IPC in our case is a unix socket because it has very
  12 little overhead on both sides and is usually available without headaches in
  13 most languages. In the default configuration file, the ipc-socket gets created
  14 in +/tmp/i3-%u/ipc-socket.%p+ where +%u+ is your UNIX username and +%p+ is the
  15 PID of i3.
  16
  17 All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+
  18 X11 property, stored on the X11 root window.
  19
  20 == Establishing a connection
  21
  22 To establish a connection, simply open the IPC socket. The following code
  23 snippet illustrates this in Perl:
  24
  25 -------------------------------------------------------------
  26 use IO::Socket::UNIX;
  27 my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock');
  28 -------------------------------------------------------------
  29
  30 == Sending messages to i3
  31
  32 To send a message to i3, you have to format in the binary message format which
  33 i3 expects. This format specifies a magic string in the beginning to ensure
  34 the integrity of messages (to prevent follow-up errors). Following the magic
  35 string comes the length of the payload of the message as 32-bit integer, and
  36 the type of the message as 32-bit integer (the integers are not converted, so
  37 they are in native byte order).
  38
  39 The magic string currently is "i3-ipc" and will only be changed when a change
  40 in the IPC API is done which breaks compatibility (we hope that we don’t need
  41 to do that).
  42
  43 Currently implemented message types are the following:
  44
  45 COMMAND (0)::
  46         The payload of the message is a command for i3 (like the commands you
  47         can bind to keys in the configuration file) and will be executed
  48         directly after receiving it. There is no reply to this message.
  49 GET_WORKSPACES (1)::
  50         Gets the current workspaces. The reply will be a JSON-encoded list of
  51         workspaces (see the reply section).
  52 SUBSCRIBE (2)::
  53         Subscribes your connection to certain events. See <<events>> for a
  54         description of this message and the concept of events.
  55 GET_OUTPUTS (3)::
  56         Gets the current outputs. The reply will be a JSON-encoded list of outputs
  57         (see the reply section).
  58 GET_TREE (4)::
  59         Gets the layout tree. i3 uses a tree as data structure which includes
  60         every container. The reply will be the JSON-encoded tree (see the reply
  61         section).
  62 GET_MARKS (5)::
  63         Gets a list of marks (identifiers for containers to easily jump to them
  64         later). The reply will be a JSON-encoded list of window marks (see
  65         reply section).
  66
  67 So, a typical message could look like this:
  68 --------------------------------------------------
  69 "i3-ipc" <message length> <message type> <payload>
  70 --------------------------------------------------
  71
  72 Or, as a hexdump:
  73 ------------------------------------------------------------------------------
  74 00000000  69 33 2d 69 70 63 04 00  00 00 00 00 00 00 65 78  |i3-ipc........ex|
  75 00000010  69 74 0a                                          |it.|
  76 ------------------------------------------------------------------------------
  77
  78 To generate and send such a message, you could use the following code in Perl:
  79 ------------------------------------------------------------
  80 sub format_ipc_command {
  81     my ($msg) = @_;
  82     my $len;
  83     # Get the real byte count (vs. amount of characters)
  84     { use bytes; $len = length($msg); }
  85     return "i3-ipc" . pack("LL", $len, 0) . $msg;
  86 }
  87
  88 $sock->write(format_ipc_command("exit"));
  89 ------------------------------------------------------------------------------
  90
  91 == Receiving replies from i3
  92
  93 Replies from i3 usually consist of a simple string (the length of the string
  94 is the message_length, so you can consider them length-prefixed) which in turn
  95 contain the JSON serialization of a data structure. For example, the
  96 GET_WORKSPACES message returns an array of workspaces (each workspace is a map
  97 with certain attributes).
  98
  99 === Reply format
 100
 101 The reply format is identical to the normal message format. There also is
 102 the magic string, then the message length, then the message type and the
 103 payload.
 104
 105 The following reply types are implemented:
 106
 107 COMMAND (0)::
 108         Confirmation/Error code for the COMMAND message.
 109 GET_WORKSPACES (1)::
 110         Reply to the GET_WORKSPACES message.
 111 SUBSCRIBE (2)::
 112         Confirmation/Error code for the SUBSCRIBE message.
 113 GET_OUTPUTS (3)::
 114         Reply to the GET_OUTPUTS message.
 115 GET_TREE (4)::
 116         Reply to the GET_TREE message.
 117 GET_MARKS (5)::
 118         Reply to the GET_MARKS message.
 119
 120 === COMMAND reply
 121
 122 The reply consists of a single serialized map. At the moment, the only
 123 property is +success (bool)+, but this will be expanded in future versions.
 124
 125 *Example:*
 126 -------------------
 127 { "success": true }
 128 -------------------
 129
 130 === GET_WORKSPACES reply
 131
 132 The reply consists of a serialized list of workspaces. Each workspace has the
 133 following properties:
 134
 135 num (integer)::
 136         The logical number of the workspace. Corresponds to the command
 137         to switch to this workspace.
 138 name (string)::
 139         The name of this workspace (by default num+1), as changed by the
 140         user. Encoded in UTF-8.
 141 visible (boolean)::
 142         Whether this workspace is currently visible on an output (multiple
 143         workspaces can be visible at the same time).
 144 focused (boolean)::
 145         Whether this workspace currently has the focus (only one workspace
 146         can have the focus at the same time).
 147 urgent (boolean)::
 148         Whether a window on this workspace has the "urgent" flag set.
 149 rect (map)::
 150         The rectangle of this workspace (equals the rect of the output it
 151         is on), consists of x, y, width, height.
 152 output (string)::
 153         The video output this workspace is on (LVDS1, VGA1, …).
 154
 155 *Example:*
 156 -------------------
 157 [
 158  {
 159   "num": 0,
 160   "name": "1",
 161   "visible": true,
 162   "focused": true,
 163   "urgent": false,
 164   "rect": {
 165    "x": 0,
 166    "y": 0,
 167    "width": 1280,
 168    "height": 800
 169   },
 170   "output": "LVDS1"
 171  },
 172  {
 173   "num": 1,
 174   "name": "2",
 175   "visible": false,
 176   "focused": false,
 177   "urgent": false,
 178   "rect": {
 179    "x": 0,
 180    "y": 0,
 181    "width": 1280,
 182    "height": 800
 183   },
 184   "output": "LVDS1"
 185  }
 186 ]
 187 -------------------
 188
 189 === SUBSCRIBE reply
 190
 191 The reply consists of a single serialized map. The only property is
 192 +success (bool)+, indicating whether the subscription was successful (the
 193 default) or whether a JSON parse error occurred.
 194
 195 *Example:*
 196 -------------------
 197 { "success": true }
 198 -------------------
 199
 200 === GET_OUTPUTS reply
 201
 202 The reply consists of a serialized list of outputs. Each output has the
 203 following properties:
 204
 205 name (string)::
 206         The name of this output (as seen in +xrandr(1)+). Encoded in UTF-8.
 207 active (boolean)::
 208         Whether this output is currently active (has a valid mode).
 209 current_workspace (integer)::
 210         The current workspace which is visible on this output. +null+ if the
 211         output is not active.
 212 rect (map)::
 213         The rectangle of this output (equals the rect of the output it
 214         is on), consists of x, y, width, height.
 215
 216 *Example:*
 217 -------------------
 218 [
 219  {
 220   "name": "LVDS1",
 221   "active": true,
 222   "current_workspace": 4,
 223   "rect": {
 224    "x": 0,
 225    "y": 0,
 226    "width": 1280,
 227    "height": 800
 228   }
 229  },
 230  {
 231   "name": "VGA1",
 232   "active": true,
 233   "current_workspace": 1,
 234   "rect": {
 235    "x": 1280,
 236    "y": 0,
 237    "width": 1280,
 238    "height": 1024
 239   },
 240  }
 241 ]
 242 -------------------
 243
 244 === GET_TREE reply
 245
 246 The reply consists of a serialized tree. Each node in the tree (representing
 247 one container) has at least the properties listed below. While the nodes might
 248 have more properties, please do not use any properties which are not documented
 249 here. They are not yet finalized and will probably change!
 250
 251 id (integer)::
 252         The internal ID (actually a C pointer value) of this container. Do not
 253         make any assumptions about it. You can use it to (re-)identify and
 254         address containers when talking to i3.
 255 name (string)::
 256         The internal name of this container. For all containers which are part
 257         of the tree structure down to the workspace contents, this is set to a
 258         nice human-readable name of the container.
 259         For all other containers, the content is not defined (yet).
 260 border (string)::
 261         Can be either "normal", "none" or "1pixel", dependending on the
 262         container’s border style.
 263 layout (string)::
 264         Can be either "default", "stacked", "tabbed", "dockarea" or "output".
 265         Other values might be possible in the future, should we add new
 266         layouts.
 267 orientation (string)::
 268         Can be either "none" (for non-split containers), "horizontal" or
 269         "vertical".
 270 percent (float)::
 271         The percentage which this container takes in its parent. A value of
 272         +null+ means that the percent property does not make sense for this
 273         container, for example for the root container.
 274 rect (map)::
 275         The absolute display coordinates for this container. Display
 276         coordinates means that when you have two 1600x1200 monitors on a single
 277         X11 Display (the standard way), the coordinates of the first window on
 278         the second monitor are +{ "x": 1600, "y": 0, "width": 1600, "height":
 279         1200 }+.
 280 window_rect (map)::
 281         The coordinates of the *actual client window* inside its container.
 282         These coordinates are relative to the container and do not include the
 283         window decoration (which is actually rendered on the parent container).
 284         So, when using the +default+ layout, you will have a 2 pixel border on
 285         each side, making the window_rect +{ "x": 2, "y": 0, "width": 632,
 286         "height": 366 }+ (for example).
 287 geometry (map)::
 288         The original geometry the window specified when i3 mapped it. Used when
 289         switching a window to floating mode, for example.
 290 urgent (bool)::
 291         Whether this container (window or workspace) has the urgency hint set.
 292 focused (bool)::
 293         Whether this container is currently focused.
 294
 295 Please note that in the following example, I have left out some keys/values
 296 which are not relevant for the type of the node. Otherwise, the example would
 297 be by far too long (it already is quite long, despite showing only 1 window and
 298 one dock window).
 299
 300 It is useful to have an overview of the structure before taking a look at the
 301 JSON dump:
 302
 303 * root
 304 ** LVDS1
 305 *** topdock
 306 *** content
 307 **** workspace 1
 308 ***** window 1
 309 *** bottomdock
 310 **** dock window 1
 311 ** VGA1
 312
 313 *Example:*
 314 -----------------------
 315 {
 316  "id": 6875648,
 317  "name": "root",
 318  "rect": {
 319    "x": 0,
 320    "y": 0,
 321    "width": 1280,
 322    "height": 800
 323  },
 324  "nodes": [
 325
 326    {
 327     "id": 6878320,
 328     "name": "LVDS1",
 329     "layout": "output",
 330     "rect": {
 331       "x": 0,
 332       "y": 0,
 333       "width": 1280,
 334       "height": 800
 335     },
 336     "nodes": [
 337
 338       {
 339        "id": 6878784,
 340        "name": "topdock",
 341        "layout": "dockarea",
 342        "orientation": "vertical",
 343        "rect": {
 344          "x": 0,
 345          "y": 0,
 346          "width": 1280,
 347          "height": 0
 348        },
 349       },
 350
 351       {
 352        "id": 6879344,
 353        "name": "content",
 354        "rect": {
 355          "x": 0,
 356          "y": 0,
 357          "width": 1280,
 358          "height": 782
 359        },
 360        "nodes": [
 361
 362          {
 363           "id": 6880464,
 364           "name": "1",
 365           "orientation": "horizontal",
 366           "rect": {
 367             "x": 0,
 368             "y": 0,
 369             "width": 1280,
 370             "height": 782
 371           },
 372           "floating_nodes": [],
 373           "nodes": [
 374
 375             {
 376              "id": 6929968,
 377              "name": "#aa0000",
 378              "border": "normal",
 379              "percent": 1,
 380              "rect": {
 381                "x": 0,
 382                "y": 18,
 383                "width": 1280,
 384                "height": 782
 385              }
 386             }
 387
 388           ]
 389          }
 390
 391        ]
 392       },
 393
 394       {
 395        "id": 6880208,
 396        "name": "bottomdock",
 397        "layout": "dockarea",
 398        "orientation": "vertical",
 399        "rect": {
 400          "x": 0,
 401          "y": 782,
 402          "width": 1280,
 403          "height": 18
 404        },
 405        "nodes": [
 406
 407          {
 408           "id": 6931312,
 409           "name": "#00aa00",
 410           "percent": 1,
 411           "rect": {
 412             "x": 0,
 413             "y": 782,
 414             "width": 1280,
 415             "height": 18
 416           }
 417          }
 418
 419        ]
 420       }
 421     ]
 422    }
 423  ]
 424 }
 425
 426
 427 === GET_MARKS reply
 428
 429 The reply consists of a single array of strings for each container that has a
 430 mark. The order of that array is undefined. If more than one container has the
 431 same mark, it will be represented multiple times in the reply (the array
 432 contents are not unique).
 433
 434 If no window has a mark the response will be the empty array [].
 435 ------------------------
 436
 437
 438 == Events
 439
 440 [[events]]
 441
 442 To get informed when certain things happen in i3, clients can subscribe to
 443 events. Events consist of a name (like "workspace") and an event reply type
 444 (like I3_IPC_EVENT_WORKSPACE). The events sent by i3 are in the same format
 445 as replies to specific commands. However, the highest bit of the message type
 446 is set to 1 to indicate that this is an event reply instead of a normal reply.
 447
 448 Caveat: As soon as you subscribe to an event, it is not guaranteed any longer
 449 that the requests to i3 are processed in order. This means, the following
 450 situation can happen: You send a GET_WORKSPACES request but you receive a
 451 "workspace" event before receiving the reply to GET_WORKSPACES. If your
 452 program does not want to cope which such kinds of race conditions (an
 453 event based library may not have a problem here), I suggest you create a
 454 separate connection to receive events.
 455
 456 === Subscribing to events
 457
 458 By sending a message of type SUBSCRIBE with a JSON-encoded array as payload
 459 you can register to an event.
 460
 461 *Example:*
 462 ---------------------------------
 463 type: SUBSCRIBE
 464 payload: [ "workspace", "focus" ]
 465 ---------------------------------
 466
 467
 468 === Available events
 469
 470 The numbers in parenthesis is the event type (keep in mind that you need to
 471 strip the highest bit first).
 472
 473 workspace (0)::
 474         Sent when the user switches to a different workspace, when a new
 475         workspace is initialized or when a workspace is removed (because the
 476         last client vanished).
 477 output (1)::
 478         Sent when RandR issues a change notification (of either screens,
 479         outputs, CRTCs or output properties).
 480
 481 *Example:*
 482 --------------------------------------------------------------------
 483 # the appropriate 4 bytes read from the socket are stored in $input
 484
 485 # unpack a 32-bit unsigned integer
 486 my $message_type = unpack("L", $input);
 487
 488 # check if the highest bit is 1
 489 my $is_event = (($message_type >> 31) == 1);
 490
 491 # use the other bits
 492 my $event_type = ($message_type & 0x7F);
 493
 494 if ($is_event) {
 495   say "Received event of type $event_type";
 496 }
 497 --------------------------------------------------------------------
 498
 499 === workspace event
 500
 501 This event consists of a single serialized map containing a property
 502 +change (string)+ which indicates the type of the change ("focus", "init",
 503 "empty", "urgent").
 504
 505 *Example:*
 506 ---------------------
 507 { "change": "focus" }
 508 ---------------------
 509
 510 === output event
 511
 512 This event consists of a single serialized map containing a property
 513 +change (string)+ which indicates the type of the change (currently only
 514 "unspecified").
 515
 516 *Example:*
 517 ---------------------------
 518 { "change": "unspecified" }
 519 ---------------------------
 520
 521 == See also
 522
 523 For some languages, libraries are available (so you don’t have to implement
 524 all this on your own). This list names some (if you wrote one, please let me
 525 know):
 526
 527 C::
 528         i3 includes a headerfile +i3/ipc.h+ which provides you all constants.
 529         However, there is no library yet.
 530 Ruby::
 531         http://github.com/badboy/i3-ipc
 532 Perl::
 533         http://search.cpan.org/search?query=AnyEvent::I3
 534 Python::
 535         http://github.com/thepub/i3ipc