-
Notifications
You must be signed in to change notification settings - Fork 30
/
org.opensuse.tukit.Transaction.xml
278 lines (278 loc) · 12.1 KB
/
org.opensuse.tukit.Transaction.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<interface name="org.opensuse.tukit.Transaction">
<method name="Execute">
<doc:doc><doc:description>
<doc:para>
Creates a new snapshot and execute the given command. If execution was successful
the snapshot will be set as the new snapshot, if the command returned with an error
code the snapshot will be discarded.
</doc:para>
<doc:para>
This command combines the "Open", "Call" and "Close" / "Abort" calls in one method.
For more fine-grained control, e.g. to execute several commands in one snapshot
or to control snapshot deletion use the individual commands.
</doc:para>
<doc:para>
As it can take a long time until a command is executed the command is executed
asynchronously. The actual result is returned either via a "CommandExecuted" signal
on success or an "Error" signal if the command returned with an error code.
Additionally the "TransactionOpened" signal is sent as soon as the new snapshot
has been created.
</doc:para>
</doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured before the snapshot
could be created - errors after that point will be communicated via the "Error"
signal (see below).</doc:error>
</doc:errors>
<arg type="s" name="base" direction="in">
<doc:doc><doc:summary>The snapshot id to use as a base for the new snapshot.
Can be "active" to base the snapshot on the currently running system, "default" to
use the current default snapshot as a base (which may or may not be identical to
"active" or any specific existing snapshot id.</doc:summary></doc:doc>
</arg>
<arg type="s" name="command" direction="in">
<doc:doc><doc:summary>The command to execute. To execute several commands at once
a syntax such as "bash -c 'command1; command2'" may be used.</doc:summary></doc:doc>
</arg>
<arg type="s" name="snapshot" direction="out">
<doc:doc><doc:summary>The id of the new snapshot. Returns as soon the snapshot has
been created.</doc:summary></doc:doc>
</arg>
</method>
<method name="ExecuteAndReboot">
<doc:doc><doc:description><doc:para>
Same as "ExecuteWithOpts" with the "Reboot" value set.
</doc:para></doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured before the snapshot
could be created - errors after that point will be communicated via the "Error"
signal (see below).</doc:error>
</doc:errors>
<arg type="s" name="base" direction="in">
<doc:doc><doc:summary>Same as in "Execute".</doc:summary></doc:doc>
</arg>
<arg type="s" name="command" direction="in">
<doc:doc><doc:summary>Same as in "Execute".</doc:summary></doc:doc>
</arg>
<arg type="s" name="rebootmethod" direction="in">
<doc:doc><doc:summary>Same as the "Reboot" option in "ExecuteWithOpts".
</doc:summary></doc:doc>
</arg>
<arg type="s" name="snapshot" direction="out">
<doc:doc><doc:summary>Same as in "Execute".</doc:summary></doc:doc>
</arg>
</method>
<method name="ExecuteWithOpts">
<doc:doc><doc:description><doc:para>
Same as "Execute", but allow setting additional options.
</doc:para></doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured before the snapshot
could be created - errors after that point will be communicated via the "Error"
signal (see below).</doc:error>
</doc:errors>
<arg type="s" name="base" direction="in">
<doc:doc><doc:summary>Same as in "Execute".</doc:summary></doc:doc>
</arg>
<arg type="s" name="command" direction="in">
<doc:doc><doc:summary>Same as in "Execute".</doc:summary></doc:doc>
</arg>
<arg type="a{sv}" name="options" direction="in">
<doc:doc><doc:summary>
<doc:para>Accepts the following options:</doc:para>
<doc:list>
<doc:item>
<doc:term>Description</doc:term>
<doc:definition>Sets a custom description for the snapshot.
The description in the variant value has to be of type
"string".
</doc:definition>
</doc:item>
<doc:item>
<doc:term>Reboot</doc:term>
<doc:definition>Indicate the reboot method to use; see the
transactional-update.conf man page for supported reboot
methods. The variant value containing the reboot method has
to be of type "string".</doc:definition>
</doc:item>
</doc:list>
</doc:summary></doc:doc>
</arg>
<arg type="s" name="snapshot" direction="out">
<doc:doc><doc:summary>Same as in "Execute".</doc:summary></doc:doc>
</arg>
</method>
<method name="Open">
<doc:doc><doc:description><doc:para>
Creates a new snapshot. The new snapshot id is returned both as a return value and
announced via the "TransactionOpened" signal.
</doc:para></doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured.</doc:error>
</doc:errors>
<arg type="s" name="base" direction="in">
<doc:doc><doc:summary>The snapshot id to use as a base for the new snapshot.
Can be "active" to base the snapshot on the currently running system, "default" to
use the current default snapshot as a base (which may or may not be identical to
"active" or any specific existing snapshot id.</doc:summary></doc:doc>
</arg>
<arg type="s" name="snapshot" direction="out">
<doc:doc><doc:summary>The id of the new snapshot.</doc:summary></doc:doc>
</arg>
</method>
<method name="OpenWithOpts">
<doc:doc><doc:description><doc:para>
Same as "Open", but allow setting additional options.
</doc:para></doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured.</doc:error>
</doc:errors>
<arg type="s" name="base" direction="in">
<doc:doc><doc:summary>Same as in "Open".</doc:summary></doc:doc>
</arg>
<arg type="a{sv}" name="options" direction="in">
<doc:doc><doc:summary>
<doc:para>Accepts the following options:</doc:para>
<doc:list>
<doc:item>
<doc:term>Description</doc:term>
<doc:definition>Sets a custom description for the snapshot.
The description in the variant value has to be of type
"string".
</doc:definition>
</doc:item>
</doc:list>
</doc:summary></doc:doc>
</arg>
<arg type="s" name="snapshot" direction="out">
<doc:doc><doc:summary>Same as in "Open".</doc:summary></doc:doc>
</arg>
</method>
<method name="Call">
<doc:doc><doc:description>
<doc:para>
Execute the given command in the specified snapshot. The snapshot will not
automatically be discarded if the command should return with error.
</doc:para>
<doc:para>
As it can take a long time until a command returns the command is executed
asynchronously. The actual result and output is returned either via a
"CommandExecuted" signal on success or an "Error" signal if the command returned
with an error code.
</doc:para>
</doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured before the snapshot
could be resumed - errors after that point will be communicated via the "Error"
signal (see below).</doc:error>
</doc:errors>
<arg type="s" name="transaction" direction="in">
<doc:doc><doc:summary>The snapshot id. The snapshot must still be in open state, i.e.
it must not have been finalized with "Close" yet.</doc:summary></doc:doc>
</arg>
<arg type="s" name="command" direction="in">
<doc:doc><doc:summary>The command to execute.</doc:summary></doc:doc>
</arg>
</method>
<method name="CallExt">
<doc:doc><doc:description>
<doc:para>
Replace any standalone occurrence of '{}' in in command parameter with the
snapshot's mount directory and execute the given command *outside* of the snapshot
in the running system, but while the update environment is mounted. This may
be useful if the command needs access to the current environment, e.g. to copy a file
from a directory not accessible from within the chroot environment.
</doc:para>
<doc:para>
As it can take a long time until a command returns the command is executed
asynchronously. The actual result and output is returned either via a
"CommandExecuted" signal on success or an "Error" signal if the command returned
with an error code.
</doc:para>
</doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured before the snapshot
could be resumed - errors after that point will be communicated via the "Error"
signal (see below).</doc:error>
</doc:errors>
<arg type="s" name="transaction" direction="in">
<doc:doc><doc:summary>The snapshot id. The snapshot must still be in open state, i.e.
it must not have been finalized with "Close" yet.</doc:summary></doc:doc>
</arg>
<arg type="s" name="command" direction="in">
<doc:doc><doc:summary>The command to execute. Any occurence of '{}' will be replaced
with the (writable) directory of the snapshot.</doc:summary></doc:doc>
</arg>
</method>
<method name="Close">
<doc:doc><doc:description><doc:para>
Sets the snapshot as the new default snapshot and prevents any further modification.
</doc:para></doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured.</doc:error>
</doc:errors>
<arg type="s" name="transaction" direction="in">
<doc:doc><doc:summary>The snapshot id.</doc:summary></doc:doc>
</arg>
</method>
<method name="Abort">
<doc:doc><doc:description><doc:para>
Discards the snapshot completely.
</doc:para></doc:description></doc:doc>
<doc:errors>
<doc:error name="org.opensuse.tukit.Error">if an error occured.</doc:error>
</doc:errors>
<arg type="s" name="transaction" direction="in">
<doc:doc><doc:summary>The snapshot id. The snapshot must still be in open state, i.e.
it must not have been finalized with "Close" yet.</doc:summary></doc:doc>
</arg>
</method>
<signal name="TransactionOpened">
<doc:doc><doc:description><doc:para>
Sent when a new snapshot was created with the D-Bus interface. Snapshots created via
the command line or API will not trigger this event.
</doc:para></doc:description></doc:doc>
<arg type="s" name="snapshot">
<doc:doc><doc:summary>The snapshot id.</doc:summary></doc:doc>
</arg>
</signal>
<signal name="CommandExecuted">
<doc:doc><doc:description><doc:para>
Sent when the anyncronously executed commands initiated by the "Execute..." or
"Call..." methods return.
</doc:para></doc:description></doc:doc>
<arg type="s" name="snapshot">
<doc:doc><doc:summary>The snapshot id the command was executed in.
</doc:summary></doc:doc>
</arg>
<arg type="i" name="returncode">
<doc:doc><doc:summary>The exit code of the command.</doc:summary></doc:doc>
</arg>
<arg type="s" name="output">
<doc:doc><doc:summary>The output (stdout and stderr) of the command while it was
executed.</doc:summary></doc:doc>
</arg>
</signal>
<signal name="Error">
<doc:doc><doc:description><doc:para>
Any error occuring during the asyncronous execution of commands initiated with the
"Execute..." or "Call..." methods after the method returned is signalled via this
signal. The exit code of the command itself is returned via the "CommandExecuted"
signal (if the error didn't occur before the execution).
</doc:para></doc:description></doc:doc>
<arg type="s" name="snapshot">
<doc:doc><doc:summary>The snapshot id the error happened in.
</doc:summary></doc:doc>
</arg>
<arg type="i" name="returncode">
<doc:doc><doc:summary>The return code of the failing function.</doc:summary></doc:doc>
</arg>
<arg type="s" name="output">
<doc:doc><doc:summary>The error message of the failed function.</doc:summary></doc:doc>
</arg>
</signal>
</interface>
</node>