creek

 1<?xml version="1.0" encoding="UTF-8"?>
 2<protocol name="river_control_unstable_v1">
 3  <copyright>
 4    Copyright 2020 The River Developers
 5
 6    Permission to use, copy, modify, and/or distribute this software for any
 7    purpose with or without fee is hereby granted, provided that the above
 8    copyright notice and this permission notice appear in all copies.
 9
10    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17  </copyright>
18
19  <interface name="zriver_control_v1" version="1">
20    <description summary="run compositor commands">
21      This interface allows clients to run compositor commands and receive a
22      success/failure response with output or a failure message respectively.
23
24      Each command is built up in a series of add_argument requests and
25      executed with a run_command request. The first argument is the command
26      to be run.
27
28      A complete list of commands should be made available in the man page of
29      the compositor.
30    </description>
31
32    <request name="destroy" type="destructor">
33      <description summary="destroy the river_control object">
34        This request indicates that the client will not use the
35        river_control object any more. Objects that have been created
36        through this instance are not affected.
37      </description>
38    </request>
39
40    <request name="add_argument">
41      <description summary="add an argument to the current command">
42        Arguments are stored by the server in the order they were sent until
43        the run_command request is made.
44      </description>
45      <arg name="argument" type="string" summary="the argument to add"/>
46    </request>
47
48    <request name="run_command">
49      <description summary="run the current command">
50        Execute the command built up using the add_argument request for the
51        given seat.
52      </description>
53      <arg name="seat" type="object" interface="wl_seat"/>
54      <arg name="callback" type="new_id" interface="zriver_command_callback_v1"
55        summary="callback object"/>
56    </request>
57  </interface>
58
59  <interface name="zriver_command_callback_v1" version="1">
60    <description summary="callback object">
61      This object is created by the run_command request. Exactly one of the
62      success or failure events will be sent. This object will be destroyed
63      by the compositor after one of the events is sent.
64    </description>
65
66    <event name="success">
67      <description summary="command successful">
68        Sent when the command has been successfully received and executed by
69        the compositor. Some commands may produce output, in which case the
70        output argument will be a non-empty string.
71      </description>
72      <arg name="output" type="string" summary="the output of the command"/>
73    </event>
74
75    <event name="failure">
76      <description summary="command failed">
77        Sent when the command could not be carried out. This could be due to
78        sending a non-existent command, no command, not enough arguments, too
79        many arguments, invalid arguments, etc.
80      </description>
81      <arg name="failure_message" type="string"
82        summary="a message explaining why failure occurred"/>
83    </event>
84  </interface>
85</protocol>