docs/ipc: Add descriptions of all message payloads
These seemed to be inconsistently specified. Particularly, the "SYNC" message payload was not described anywhere. Even when the payload is empty, it is helpful to specify that explicitly, as it prevents the reader from having to guess whether if it's really empty, or otherwise somehow implicitly obvious. The "Reply format" section is now "Messages and replies", and covers both the reply format and the format of sent messages.
This commit is contained in:
Vladimir Panteleev
Michael Stapelberg
parent
8db3bef66d
commit
d4c23ec24b
135
docs/ipc
135
docs/ipc
@ -150,8 +150,20 @@ SYNC (11)::
|
||||
GET_BINDING_STATE (12)::
|
||||
Reply to the GET_BINDING_STATE message.
|
||||
|
||||
== Messages and replies
|
||||
|
||||
[[_command_reply]]
|
||||
=== COMMAND reply
|
||||
=== RUN_COMMAND / COMMAND
|
||||
|
||||
Run the payload as an https://i3wm.org/docs/userguide.html#list_of_commands[i3
|
||||
command] (like the commands you can bind to keys).
|
||||
|
||||
*Message:*
|
||||
|
||||
The message payload is the string containing the command to execute. There is
|
||||
no JSON encoding or trailing newline.
|
||||
|
||||
*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
|
||||
@ -185,7 +197,15 @@ When the specified command cannot be parsed, `success` will be false and
|
||||
-------------------
|
||||
|
||||
[[_workspaces_reply]]
|
||||
=== WORKSPACES reply
|
||||
=== GET_WORKSPACES / WORKSPACES
|
||||
|
||||
Get the list of current workspaces.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload.
|
||||
|
||||
*Reply:*
|
||||
|
||||
The reply consists of a serialized list of workspaces. Each workspace has the
|
||||
following properties:
|
||||
@ -249,7 +269,16 @@ output (string)::
|
||||
-------------------
|
||||
|
||||
[[_subscribe_reply]]
|
||||
=== SUBSCRIBE reply
|
||||
=== SUBSCRIBE
|
||||
|
||||
Subscribe this IPC connection to the event types specified in the message
|
||||
payload. See <<events>>.
|
||||
|
||||
*Message:*
|
||||
|
||||
A JSON-encoded array of event types to subscribe to.
|
||||
|
||||
*Reply:*
|
||||
|
||||
The reply consists of a single serialized map. The only property is
|
||||
+success (bool)+, indicating whether the subscription was successful (the
|
||||
@ -261,7 +290,15 @@ default) or whether a JSON parse error occurred.
|
||||
-------------------
|
||||
|
||||
[[_outputs_reply]]
|
||||
=== OUTPUTS reply
|
||||
=== GET_OUTPUTS / OUTPUTS
|
||||
|
||||
Get the list of current outputs.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload.
|
||||
|
||||
*Reply:*
|
||||
|
||||
The reply consists of a serialized list of outputs. Each output has the
|
||||
following properties:
|
||||
@ -308,7 +345,15 @@ rect (map)::
|
||||
-------------------
|
||||
|
||||
[[_tree_reply]]
|
||||
=== TREE reply
|
||||
=== GET_TREE / TREE
|
||||
|
||||
Get the i3 layout tree.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload.
|
||||
|
||||
*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
|
||||
@ -551,7 +596,15 @@ JSON dump:
|
||||
-----------------------
|
||||
|
||||
[[_marks_reply]]
|
||||
=== MARKS reply
|
||||
=== GET_MARKS / MARKS
|
||||
|
||||
Gets the names of all currently set marks.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload.
|
||||
|
||||
*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.
|
||||
@ -560,7 +613,15 @@ 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
|
||||
=== GET_BAR_CONFIG / BAR_CONFIG
|
||||
|
||||
Gets the specified bar configuration or the names of all bar configurations if payload is empty.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload, or the ID of the bar whose configuration to retrieve.
|
||||
|
||||
*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
|
||||
@ -660,7 +721,15 @@ binding_mode_text/binding_mode_bg/binding_mode_border::
|
||||
--------------
|
||||
|
||||
[[_version_reply]]
|
||||
=== VERSION reply
|
||||
=== GET_VERSION / VERSION
|
||||
|
||||
Gets the i3 version.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload.
|
||||
|
||||
*Reply:*
|
||||
|
||||
The reply consists of a single JSON dictionary with the following keys:
|
||||
|
||||
@ -693,7 +762,15 @@ loaded_config_file_name (string)::
|
||||
-------------------
|
||||
|
||||
[[_binding_modes_reply]]
|
||||
=== BINDING_MODES reply
|
||||
=== GET_BINDING_MODES / BINDING_MODES
|
||||
|
||||
Gets the names of all currently configured binding modes.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload.
|
||||
|
||||
*Reply:*
|
||||
|
||||
The reply consists of an array of all currently configured binding modes.
|
||||
|
||||
@ -703,7 +780,15 @@ The reply consists of an array of all currently configured binding modes.
|
||||
---------------------
|
||||
|
||||
[[_config_reply]]
|
||||
=== CONFIG reply
|
||||
=== GET_CONFIG / CONFIG
|
||||
|
||||
Returns the last loaded i3 config.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload.
|
||||
|
||||
*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.
|
||||
@ -714,7 +799,15 @@ which is a string containing the config file as loaded by i3 most recently.
|
||||
-------------------
|
||||
|
||||
[[_tick_reply]]
|
||||
=== TICK reply
|
||||
=== SEND_TICK / TICK
|
||||
|
||||
Sends a tick event with the specified payload.
|
||||
|
||||
*Message:*
|
||||
|
||||
The payload of the tick event to send to IPC event listeners.
|
||||
|
||||
*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
|
||||
@ -728,7 +821,15 @@ events generated prior to the +SEND_TICK+ message (happened-before relation).
|
||||
-------------------
|
||||
|
||||
[[_sync_reply]]
|
||||
=== SYNC reply
|
||||
=== SYNC
|
||||
|
||||
Sends an i3 sync event with the specified random value to the specified window.
|
||||
|
||||
*Message:*
|
||||
|
||||
A JSON-encoded map with the properties "rnd" and "window" (both integer).
|
||||
|
||||
*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
|
||||
@ -740,7 +841,15 @@ responded to.
|
||||
-------------------
|
||||
|
||||
[[_binding_state_reply]]
|
||||
=== GET_BINDING_STATE reply
|
||||
=== GET_BINDING_STATE
|
||||
|
||||
Request the current binding state, i.e. the currently active binding mode name.
|
||||
|
||||
*Message:*
|
||||
|
||||
No payload.
|
||||
|
||||
*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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user