koma/i3
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

ipc: rename COMMAND to RUN_COMMAND for consistency (#2956)

Browse Source 
All other message types are verbs, only our first-ever message COMMAND wasn’t.

While we’re here, also change the message type dictionary into a table with
clickable links to the corresponding reply type.

Authors of downstream IPC libraries are encouraged to keep the old name around
so as to not break existing code, but mark it as deprecated.
This commit is contained in:
Michael Stapelberg
2017-09-17 15:25:00 +02:00
committed by GitHub
parent d726d09d49
commit 607e97e651
7 changed files with 44 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
docs/ipc
View File

@ -50,38 +50,20 @@ 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.
GET_BINDING_MODES (8)::
Gets a list of currently configured binding modes.
.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.
|======================================================
So, a typical message could look like this:
--------------------------------------------------
@ -124,7 +106,7 @@ payload.
The following reply types are implemented:
COMMAND (0)::
Confirmation/Error code for the COMMAND message.
Confirmation/Error code for the RUN_COMMAND message.
WORKSPACES (1)::
Reply to the GET_WORKSPACES message.
SUBSCRIBE (2)::
@ -142,6 +124,7 @@ VERSION (7)::
BINDING_MODES (8)::
Reply to the GET_BINDING_MODES message.
[[_command_reply]]
=== COMMAND reply
The reply consists of a list of serialized maps for each command that was
@ -153,6 +136,7 @@ human-readable error message in the property +error (string)+.
[{ "success": true }]
-------------------
[[_workspaces_reply]]
=== WORKSPACES reply
The reply consists of a serialized list of workspaces. Each workspace has the
@ -212,6 +196,7 @@ output (string)::
]
-------------------
[[_subscribe_reply]]
=== SUBSCRIBE reply
The reply consists of a single serialized map. The only property is
@ -223,6 +208,7 @@ default) or whether a JSON parse error occurred.
{ "success": true }
-------------------
[[_outputs_reply]]
=== OUTPUTS reply
The reply consists of a serialized list of outputs. Each output has the
@ -269,6 +255,7 @@ rect (map)::
]
-------------------
[[_tree_reply]]
=== TREE reply
The reply consists of a serialized tree. Each node in the tree (representing
@ -481,6 +468,7 @@ JSON dump:
}
------------------------
[[_marks_reply]]
=== MARKS reply
The reply consists of a single array of strings for each container that has a
@ -489,6 +477,7 @@ 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
@ -588,6 +577,7 @@ binding_mode_text/binding_mode_bg/binding_mode_border::
}
--------------
[[_version_reply]]
=== VERSION reply
The reply consists of a single JSON dictionary with the following keys:
@ -620,6 +610,7 @@ loaded_config_file_name (string)::
}
-------------------
[[_binding_modes_reply]]
=== BINDING_MODES reply
The reply consists of an array of all currently configured binding modes.