Add access control support to qemu bridge helper
[qemu.git] / qapi-schema-guest.json
1 # *-*- Mode: Python -*-*
2
3 ##
4 # @guest-sync:
5 #
6 # Echo back a unique integer value
7 #
8 # This is used by clients talking to the guest agent over the
9 # wire to ensure the stream is in sync and doesn't contain stale
10 # data from previous client. All guest agent responses should be
11 # ignored until the provided unique integer value is returned,
12 # and it is up to the client to handle stale whole or
13 # partially-delivered JSON text in such a way that this response
14 # can be obtained.
15 #
16 # Such clients should also precede this command
17 # with a 0xFF byte to make such the guest agent flushes any
18 # partially read JSON data from a previous session.
19 #
20 # @id: randomly generated 64-bit integer
21 #
22 # Returns: The unique integer id passed in by the client
23 #
24 # Since: 0.15.0
25 ##
26 { 'command': 'guest-sync'
27   'data':    { 'id': 'int' },
28   'returns': 'int' }
29
30 ##
31 # @guest-ping:
32 #
33 # Ping the guest agent, a non-error return implies success
34 #
35 # Since: 0.15.0
36 ##
37 { 'command': 'guest-ping' }
38
39 ##
40 # @guest-info:
41 #
42 # Get some information about the guest agent.
43 #
44 # Since: 0.15.0
45 ##
46 { 'type': 'GuestAgentCommandInfo',
47   'data': { 'name': 'str', 'enabled': 'bool' } }
48 { 'type': 'GuestAgentInfo',
49   'data': { 'version': 'str',
50             'supported_commands': ['GuestAgentCommandInfo'] } }
51 { 'command': 'guest-info',
52   'returns': 'GuestAgentInfo' }
53
54 ##
55 # @guest-shutdown:
56 #
57 # Initiate guest-activated shutdown. Note: this is an asynchronous
58 # shutdown request, with no guaruntee of successful shutdown. Errors
59 # will be logged to guest's syslog.
60 #
61 # @mode: #optional "halt", "powerdown" (default), or "reboot"
62 #
63 # Returns: Nothing on success
64 #
65 # Since: 0.15.0
66 ##
67 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' } }
68
69 ##
70 # @guest-file-open:
71 #
72 # Open a file in the guest and retrieve a file handle for it
73 #
74 # @filepath: Full path to the file in the guest to open.
75 #
76 # @mode: #optional open mode, as per fopen(), "r" is the default.
77 #
78 # Returns: Guest file handle on success.
79 #
80 # Since: 0.15.0
81 ##
82 { 'command': 'guest-file-open',
83   'data':    { 'path': 'str', '*mode': 'str' },
84   'returns': 'int' }
85
86 ##
87 # @guest-file-close:
88 #
89 # Close an open file in the guest
90 #
91 # @handle: filehandle returned by guest-file-open
92 #
93 # Returns: Nothing on success.
94 #
95 # Since: 0.15.0
96 ##
97 { 'command': 'guest-file-close',
98   'data': { 'handle': 'int' } }
99
100 ##
101 # @guest-file-read:
102 #
103 # Read from an open file in the guest. Data will be base64-encoded
104 #
105 # @handle: filehandle returned by guest-file-open
106 #
107 # @count: #optional maximum number of bytes to read (default is 4KB)
108 #
109 # Returns: GuestFileRead on success. Note: count is number of bytes read
110 #          *before* base64 encoding bytes read.
111 #
112 # Since: 0.15.0
113 ##
114 { 'type': 'GuestFileRead',
115   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
116
117 { 'command': 'guest-file-read',
118   'data':    { 'handle': 'int', '*count': 'int' },
119   'returns': 'GuestFileRead' }
120
121 ##
122 # @guest-file-write:
123 #
124 # Write to an open file in the guest.
125 #
126 # @handle: filehandle returned by guest-file-open
127 #
128 # @buf-b64: base64-encoded string representing data to be written
129 #
130 # @count: #optional bytes to write (actual bytes, after base64-decode),
131 #         default is all content in buf-b64 buffer after base64 decoding
132 #
133 # Returns: GuestFileWrite on success. Note: count is the number of bytes
134 #          base64-decoded bytes written
135 #
136 # Since: 0.15.0
137 ##
138 { 'type': 'GuestFileWrite',
139   'data': { 'count': 'int', 'eof': 'bool' } }
140 { 'command': 'guest-file-write',
141   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
142   'returns': 'GuestFileWrite' }
143
144 ##
145 # @guest-file-seek:
146 #
147 # Seek to a position in the file, as with fseek(), and return the
148 # current file position afterward. Also encapsulates ftell()'s
149 # functionality, just Set offset=0, whence=SEEK_CUR.
150 #
151 # @handle: filehandle returned by guest-file-open
152 #
153 # @offset: bytes to skip over in the file stream
154 #
155 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
156 #
157 # Returns: GuestFileSeek on success.
158 #
159 # Since: 0.15.0
160 ##
161 { 'type': 'GuestFileSeek',
162   'data': { 'position': 'int', 'eof': 'bool' } }
163
164 { 'command': 'guest-file-seek',
165   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
166   'returns': 'GuestFileSeek' }
167
168 ##
169 # @guest-file-flush:
170 #
171 # Write file changes bufferred in userspace to disk/kernel buffers
172 #
173 # @handle: filehandle returned by guest-file-open
174 #
175 # Returns: Nothing on success.
176 #
177 # Since: 0.15.0
178 ##
179 { 'command': 'guest-file-flush',
180   'data': { 'handle': 'int' } }
181
182 ##
183 # @guest-fsfreeze-status:
184 #
185 # Get guest fsfreeze state. error state indicates failure to thaw 1 or more
186 # previously frozen filesystems, or failure to open a previously cached
187 # filesytem (filesystem unmounted/directory changes, etc).
188 #
189 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
190 #
191 # Since: 0.15.0
192 ##
193 { 'enum': 'GuestFsfreezeStatus',
194   'data': [ 'thawed', 'frozen', 'error' ] }
195 { 'command': 'guest-fsfreeze-status',
196   'returns': 'GuestFsfreezeStatus' }
197
198 ##
199 # @guest-fsfreeze-freeze:
200 #
201 # Sync and freeze all non-network guest filesystems
202 #
203 # Returns: Number of file systems frozen on success
204 #
205 # Since: 0.15.0
206 ##
207 { 'command': 'guest-fsfreeze-freeze',
208   'returns': 'int' }
209
210 ##
211 # @guest-fsfreeze-thaw:
212 #
213 # Unfreeze frozen guest fileystems
214 #
215 # Returns: Number of file systems thawed
216 #          If error, -1 (unknown error) or -errno
217 #
218 # Since: 0.15.0
219 ##
220 { 'command': 'guest-fsfreeze-thaw',
221   'returns': 'int' }