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

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 Michael Stapelberg
parent 395dc7bebd
commit 3bc91118c8
7 changed files with 44 additions and 47 deletions

View File

@ -87,6 +87,7 @@ use base 'Exporter';
our @EXPORT = qw(i3);
use constant TYPE_RUN_COMMAND => 0;
use constant TYPE_COMMAND => 0;
use constant TYPE_GET_WORKSPACES => 1;
use constant TYPE_SUBSCRIBE => 2;
@ -99,7 +100,7 @@ use constant TYPE_GET_BINDING_MODES => 8;
use constant TYPE_GET_CONFIG => 9;
our %EXPORT_TAGS = ( 'all' => [
qw(i3 TYPE_COMMAND TYPE_GET_WORKSPACES TYPE_SUBSCRIBE TYPE_GET_OUTPUTS
qw(i3 TYPE_RUN_COMMAND TYPE_COMMAND TYPE_GET_WORKSPACES TYPE_SUBSCRIBE TYPE_GET_OUTPUTS
TYPE_GET_TREE TYPE_GET_MARKS TYPE_GET_BAR_CONFIG TYPE_GET_VERSION
TYPE_GET_BINDING_MODES TYPE_GET_CONFIG)
] );
@ -321,7 +322,7 @@ Sends a message of the specified C<type> to i3, possibly containing the data
structure C<content> (or C<content>, encoded as utf8, if C<content> is a
scalar), if specified.
my $reply = $i3->message(TYPE_COMMAND, "reload")->recv;
my $reply = $i3->message(TYPE_RUN_COMMAND, "reload")->recv;
if ($reply->{success}) {
say "Configuration successfully reloaded";
}
@ -531,7 +532,7 @@ sub command {
$self->_ensure_connection;
$self->message(TYPE_COMMAND, $content)
$self->message(TYPE_RUN_COMMAND, $content)
}
=head1 AUTHOR

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 dont 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.

View File

@ -167,7 +167,7 @@ int main(int argc, char *argv[]) {
else
socket_path = NULL;
int o, option_index = 0;
uint32_t message_type = I3_IPC_MESSAGE_TYPE_COMMAND;
uint32_t message_type = I3_IPC_MESSAGE_TYPE_RUN_COMMAND;
char *payload = NULL;
bool quiet = false;
@ -188,7 +188,9 @@ int main(int argc, char *argv[]) {
socket_path = sstrdup(optarg);
} else if (o == 't') {
if (strcasecmp(optarg, "command") == 0) {
message_type = I3_IPC_MESSAGE_TYPE_COMMAND;
message_type = I3_IPC_MESSAGE_TYPE_RUN_COMMAND;
} else if (strcasecmp(optarg, "run_command") == 0) {
message_type = I3_IPC_MESSAGE_TYPE_RUN_COMMAND;
} else if (strcasecmp(optarg, "get_workspaces") == 0) {
message_type = I3_IPC_MESSAGE_TYPE_GET_WORKSPACES;
} else if (strcasecmp(optarg, "get_outputs") == 0) {
@ -207,7 +209,7 @@ int main(int argc, char *argv[]) {
message_type = I3_IPC_MESSAGE_TYPE_GET_CONFIG;
} else {
printf("Unknown message type\n");
printf("Known types: command, get_workspaces, get_outputs, get_tree, get_marks, get_bar_config, get_binding_modes, get_version, get_config\n");
printf("Known types: run_command, get_workspaces, get_outputs, get_tree, get_marks, get_bar_config, get_binding_modes, get_version, get_config\n");
exit(EXIT_FAILURE);
}
} else if (o == 'q') {

View File

@ -522,7 +522,7 @@ void handle_button(xcb_button_press_event_t *event) {
if (binding->input_code != event->detail)
continue;
i3_send_msg(I3_IPC_MESSAGE_TYPE_COMMAND, binding->command);
i3_send_msg(I3_IPC_MESSAGE_TYPE_RUN_COMMAND, binding->command);
return;
}
@ -603,7 +603,7 @@ void handle_button(xcb_button_press_event_t *event) {
buffer[outpos] = utf8_name[inpos];
}
buffer[outpos] = '"';
i3_send_msg(I3_IPC_MESSAGE_TYPE_COMMAND, buffer);
i3_send_msg(I3_IPC_MESSAGE_TYPE_RUN_COMMAND, buffer);
free(buffer);
}

View File

@ -27,9 +27,12 @@ typedef struct i3_ipc_header {
/** Never change this, only on major IPC breakage (dont do that) */
#define I3_IPC_MAGIC "i3-ipc"
/** The payload of the message will be interpreted as a command */
/** Deprecated: use I3_IPC_MESSAGE_TYPE_RUN_COMMAND */
#define I3_IPC_MESSAGE_TYPE_COMMAND 0
/** The payload of the message will be interpreted as a command */
#define I3_IPC_MESSAGE_TYPE_RUN_COMMAND 0
/** Requests the current workspaces from i3 */
#define I3_IPC_MESSAGE_TYPE_GET_WORKSPACES 1

View File

@ -113,7 +113,7 @@ void ipc_shutdown(shutdown_reason_t reason) {
* or not (at the moment, always returns true).
*
*/
IPC_HANDLER(command) {
IPC_HANDLER(run_command) {
/* To get a properly terminated buffer, we copy
* message_size bytes out of the buffer */
char *command = scalloc(message_size + 1, 1);
@ -1121,7 +1121,7 @@ IPC_HANDLER(get_config) {
/* The index of each callback function corresponds to the numeric
* value of the message type (see include/i3/ipc.h) */
handler_t handlers[10] = {
handle_command,
handle_run_command,
handle_get_workspaces,
handle_subscribe,
handle_get_outputs,

View File

@ -418,7 +418,7 @@ int main(int argc, char *argv[]) {
if (connect(sockfd, (const struct sockaddr *)&addr, sizeof(struct sockaddr_un)) < 0)
err(EXIT_FAILURE, "Could not connect to i3");
if (ipc_send_message(sockfd, strlen(payload), I3_IPC_MESSAGE_TYPE_COMMAND,
if (ipc_send_message(sockfd, strlen(payload), I3_IPC_MESSAGE_TYPE_RUN_COMMAND,
(uint8_t *)payload) == -1)
err(EXIT_FAILURE, "IPC: write()");
FREE(payload);
@ -432,8 +432,8 @@ int main(int argc, char *argv[]) {
err(EXIT_FAILURE, "IPC: read()");
return 1;
}
if (reply_type != I3_IPC_MESSAGE_TYPE_COMMAND)
errx(EXIT_FAILURE, "IPC: received reply of type %d but expected %d (COMMAND)", reply_type, I3_IPC_MESSAGE_TYPE_COMMAND);
if (reply_type != I3_IPC_REPLY_TYPE_COMMAND)
errx(EXIT_FAILURE, "IPC: received reply of type %d but expected %d (COMMAND)", reply_type, I3_IPC_REPLY_TYPE_COMMAND);
printf("%.*s\n", reply_length, reply);
FREE(reply);
return 0;