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
GitHub
parent
d726d09d49
commit
607e97e651
@ -88,6 +88,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;
|
||||
@ -100,7 +101,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)
|
||||
] );
|
||||
@ -322,7 +323,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";
|
||||
}
|
||||
@ -532,7 +533,7 @@ sub command {
|
||||
|
||||
$self->_ensure_connection;
|
||||
|
||||
$self->message(TYPE_COMMAND, $content)
|
||||
$self->message(TYPE_RUN_COMMAND, $content)
|
||||
}
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
57
docs/ipc
57
docs/ipc
@ -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.
|
||||
|
||||
@ -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') {
|
||||
|
||||
@ -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);
|
||||
}
|
||||
|
||||
|
||||
@ -27,9 +27,12 @@ typedef struct i3_ipc_header {
|
||||
/** Never change this, only on major IPC breakage (don’t 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
|
||||
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user