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 # @GuestAgentCommandInfo:
  41 #
  42 # Information about guest agent commands.
  43 #
  44 # @name: name of the command
  45 #
  46 # @enabled: whether command is currently enabled by guest admin
  47 #
  48 # Since 1.1.0
  49 ##
  50 { 'type': 'GuestAgentCommandInfo',
  51   'data': { 'name': 'str', 'enabled': 'bool' } }
  52
  53 ##
  54 # @GuestAgentInfo
  55 #
  56 # Information about guest agent.
  57 #
  58 # @version: guest agent version
  59 #
  60 # @supported_commands: Information about guest agent commands
  61 #
  62 # Since 0.15.0
  63 ##
  64 { 'type': 'GuestAgentInfo',
  65   'data': { 'version': 'str',
  66             'supported_commands': ['GuestAgentCommandInfo'] } }
  67 ##
  68 # @guest-info:
  69 #
  70 # Get some information about the guest agent.
  71 #
  72 # Returns: @GuestAgentInfo
  73 #
  74 # Since: 0.15.0
  75 ##
  76 { 'command': 'guest-info',
  77   'returns': 'GuestAgentInfo' }
  78
  79 ##
  80 # @guest-shutdown:
  81 #
  82 # Initiate guest-activated shutdown. Note: this is an asynchronous
  83 # shutdown request, with no guaruntee of successful shutdown. Errors
  84 # will be logged to guest's syslog.
  85 #
  86 # @mode: #optional "halt", "powerdown" (default), or "reboot"
  87 #
  88 # Returns: Nothing on success
  89 #
  90 # Since: 0.15.0
  91 ##
  92 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' } }
  93
  94 ##
  95 # @guest-file-open:
  96 #
  97 # Open a file in the guest and retrieve a file handle for it
  98 #
  99 # @filepath: Full path to the file in the guest to open.
 100 #
 101 # @mode: #optional open mode, as per fopen(), "r" is the default.
 102 #
 103 # Returns: Guest file handle on success.
 104 #
 105 # Since: 0.15.0
 106 ##
 107 { 'command': 'guest-file-open',
 108   'data':    { 'path': 'str', '*mode': 'str' },
 109   'returns': 'int' }
 110
 111 ##
 112 # @guest-file-close:
 113 #
 114 # Close an open file in the guest
 115 #
 116 # @handle: filehandle returned by guest-file-open
 117 #
 118 # Returns: Nothing on success.
 119 #
 120 # Since: 0.15.0
 121 ##
 122 { 'command': 'guest-file-close',
 123   'data': { 'handle': 'int' } }
 124
 125 ##
 126 # @GuestFileRead
 127 #
 128 # Result of guest agent file-read operation
 129 #
 130 # @count: number of bytes read (note: count is *before*
 131 #         base64-encoding is applied)
 132 #
 133 # @buf-b64: base64-encoded bytes read
 134 #
 135 # @eof: whether EOF was encountered during read operation.
 136 #
 137 # Since: 0.15.0
 138 ##
 139 { 'type': 'GuestFileRead',
 140   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
 141
 142 ##
 143 # @guest-file-read:
 144 #
 145 # Read from an open file in the guest. Data will be base64-encoded
 146 #
 147 # @handle: filehandle returned by guest-file-open
 148 #
 149 # @count: #optional maximum number of bytes to read (default is 4KB)
 150 #
 151 # Returns: @GuestFileRead on success.
 152 #
 153 # Since: 0.15.0
 154 ##
 155 { 'command': 'guest-file-read',
 156   'data':    { 'handle': 'int', '*count': 'int' },
 157   'returns': 'GuestFileRead' }
 158
 159 ##
 160 # @GuestFileWrite
 161 #
 162 # Result of guest agent file-write operation
 163 #
 164 # @count: number of bytes written (note: count is actual bytes
 165 #         written, after base64-decoding of provided buffer)
 166 #
 167 # @eof: whether EOF was encountered during write operation.
 168 #
 169 # Since: 0.15.0
 170 ##
 171 { 'type': 'GuestFileWrite',
 172   'data': { 'count': 'int', 'eof': 'bool' } }
 173
 174 ##
 175 # @guest-file-write:
 176 #
 177 # Write to an open file in the guest.
 178 #
 179 # @handle: filehandle returned by guest-file-open
 180 #
 181 # @buf-b64: base64-encoded string representing data to be written
 182 #
 183 # @count: #optional bytes to write (actual bytes, after base64-decode),
 184 #         default is all content in buf-b64 buffer after base64 decoding
 185 #
 186 # Returns: @GuestFileWrite on success.
 187 #
 188 # Since: 0.15.0
 189 ##
 190 { 'command': 'guest-file-write',
 191   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
 192   'returns': 'GuestFileWrite' }
 193
 194
 195 ##
 196 # @GuestFileSeek
 197 #
 198 # Result of guest agent file-seek operation
 199 #
 200 # @position: current file position
 201 #
 202 # @eof: whether EOF was encountered during file seek
 203 #
 204 # Since: 0.15.0
 205 ##
 206 { 'type': 'GuestFileSeek',
 207   'data': { 'position': 'int', 'eof': 'bool' } }
 208
 209 ##
 210 # @guest-file-seek:
 211 #
 212 # Seek to a position in the file, as with fseek(), and return the
 213 # current file position afterward. Also encapsulates ftell()'s
 214 # functionality, just Set offset=0, whence=SEEK_CUR.
 215 #
 216 # @handle: filehandle returned by guest-file-open
 217 #
 218 # @offset: bytes to skip over in the file stream
 219 #
 220 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
 221 #
 222 # Returns: @GuestFileSeek on success.
 223 #
 224 # Since: 0.15.0
 225 ##
 226 { 'command': 'guest-file-seek',
 227   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
 228   'returns': 'GuestFileSeek' }
 229
 230 ##
 231 # @guest-file-flush:
 232 #
 233 # Write file changes bufferred in userspace to disk/kernel buffers
 234 #
 235 # @handle: filehandle returned by guest-file-open
 236 #
 237 # Returns: Nothing on success.
 238 #
 239 # Since: 0.15.0
 240 ##
 241 { 'command': 'guest-file-flush',
 242   'data': { 'handle': 'int' } }
 243
 244 ##
 245 # @GuestFsFreezeStatus
 246 #
 247 # An enumation of filesystem freeze states
 248 #
 249 # @thawed: filesystems thawed/unfrozen
 250 #
 251 # @frozen: all non-network guest filesystems frozen
 252 #
 253 # @error: failure to thaw 1 or more
 254 #         previously frozen filesystems, or failure to open a previously
 255 #         cached filesytem (filesystem unmounted/directory changes, etc).
 256 #
 257 # Since: 0.15.0
 258 ##
 259 { 'enum': 'GuestFsfreezeStatus',
 260   'data': [ 'thawed', 'frozen', 'error' ] }
 261
 262 ##
 263 # @guest-fsfreeze-status:
 264 #
 265 # Get guest fsfreeze state. error state indicates
 266 #
 267 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
 268 #
 269 # Since: 0.15.0
 270 ##
 271 { 'command': 'guest-fsfreeze-status',
 272   'returns': 'GuestFsfreezeStatus' }
 273
 274 ##
 275 # @guest-fsfreeze-freeze:
 276 #
 277 # Sync and freeze all non-network guest filesystems
 278 #
 279 # Returns: Number of file systems frozen on success
 280 #
 281 # Since: 0.15.0
 282 ##
 283 { 'command': 'guest-fsfreeze-freeze',
 284   'returns': 'int' }
 285
 286 ##
 287 # @guest-fsfreeze-thaw:
 288 #
 289 # Unfreeze frozen guest fileystems
 290 #
 291 # Returns: Number of file systems thawed
 292 #          If error, -1 (unknown error) or -errno
 293 #
 294 # Since: 0.15.0
 295 ##
 296 { 'command': 'guest-fsfreeze-thaw',
 297   'returns': 'int' }