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.
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;
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)
] );
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";
}
$self->_ensure_connection;
- $self->message(TYPE_COMMAND, $content)
+ $self->message(TYPE_RUN_COMMAND, $content)
}
=head1 AUTHOR
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:
--------------------------------------------------
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)::
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
[{ "success": true }]
-------------------
+[[_workspaces_reply]]
=== WORKSPACES reply
The reply consists of a serialized list of workspaces. Each workspace has the
]
-------------------
+[[_subscribe_reply]]
=== SUBSCRIBE reply
The reply consists of a single serialized map. The only property is
{ "success": true }
-------------------
+[[_outputs_reply]]
=== OUTPUTS reply
The reply consists of a serialized list of outputs. Each output has the
]
-------------------
+[[_tree_reply]]
=== TREE reply
The reply consists of a serialized tree. Each node in the tree (representing
}
------------------------
+[[_marks_reply]]
=== MARKS reply
The reply consists of a single array of strings for each container that has a
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
}
--------------
+[[_version_reply]]
=== VERSION reply
The reply consists of a single JSON dictionary with the following keys:
}
-------------------
+[[_binding_modes_reply]]
=== BINDING_MODES reply
The reply consists of an array of all currently configured binding modes.
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;
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) {
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') {
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;
}
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);
}
/** 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
* 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);
/* 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,
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);
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;
projects / i3 / i3 / commitdiff