Annotation of qemu/qapi-schema-guest.json, revision 1.1.1.1

1.1       root        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 preceed 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': 'GuestAgentInfo', 'data': {'version': 'str'} }
                     47: { 'command': 'guest-info',
                     48:   'returns': 'GuestAgentInfo' }
                     49: 
                     50: ##
                     51: # @guest-shutdown:
                     52: #
                     53: # Initiate guest-activated shutdown. Note: this is an asynchronous
                     54: # shutdown request, with no guaruntee of successful shutdown. Errors
                     55: # will be logged to guest's syslog.
                     56: #
                     57: # @mode: #optional "halt", "powerdown" (default), or "reboot"
                     58: #
                     59: # Returns: Nothing on success
                     60: #
                     61: # Since: 0.15.0
                     62: ##
                     63: { 'command': 'guest-shutdown', 'data': { '*mode': 'str' } }
                     64: 
                     65: ##
                     66: # @guest-file-open:
                     67: #
                     68: # Open a file in the guest and retrieve a file handle for it
                     69: #
                     70: # @filepath: Full path to the file in the guest to open.
                     71: #
                     72: # @mode: #optional open mode, as per fopen(), "r" is the default.
                     73: #
                     74: # Returns: Guest file handle on success.
                     75: #
                     76: # Since: 0.15.0
                     77: ##
                     78: { 'command': 'guest-file-open',
                     79:   'data':    { 'path': 'str', '*mode': 'str' },
                     80:   'returns': 'int' }
                     81: 
                     82: ##
                     83: # @guest-file-close:
                     84: #
                     85: # Close an open file in the guest
                     86: #
                     87: # @handle: filehandle returned by guest-file-open
                     88: #
                     89: # Returns: Nothing on success.
                     90: #
                     91: # Since: 0.15.0
                     92: ##
                     93: { 'command': 'guest-file-close',
                     94:   'data': { 'handle': 'int' } }
                     95: 
                     96: ##
                     97: # @guest-file-read:
                     98: #
                     99: # Read from an open file in the guest. Data will be base64-encoded
                    100: #
                    101: # @handle: filehandle returned by guest-file-open
                    102: #
                    103: # @count: #optional maximum number of bytes to read (default is 4KB)
                    104: #
                    105: # Returns: GuestFileRead on success. Note: count is number of bytes read
                    106: #          *before* base64 encoding bytes read.
                    107: #
                    108: # Since: 0.15.0
                    109: ##
                    110: { 'type': 'GuestFileRead',
                    111:   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
                    112: 
                    113: { 'command': 'guest-file-read',
                    114:   'data':    { 'handle': 'int', '*count': 'int' },
                    115:   'returns': 'GuestFileRead' }
                    116: 
                    117: ##
                    118: # @guest-file-write:
                    119: #
                    120: # Write to an open file in the guest.
                    121: #
                    122: # @handle: filehandle returned by guest-file-open
                    123: #
                    124: # @buf-b64: base64-encoded string representing data to be written
                    125: #
                    126: # @count: #optional bytes to write (actual bytes, after base64-decode),
                    127: #         default is all content in buf-b64 buffer after base64 decoding
                    128: #
                    129: # Returns: GuestFileWrite on success. Note: count is the number of bytes
                    130: #          base64-decoded bytes written
                    131: #
                    132: # Since: 0.15.0
                    133: ##
                    134: { 'type': 'GuestFileWrite',
                    135:   'data': { 'count': 'int', 'eof': 'bool' } }
                    136: { 'command': 'guest-file-write',
                    137:   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
                    138:   'returns': 'GuestFileWrite' }
                    139: 
                    140: ##
                    141: # @guest-file-seek:
                    142: #
                    143: # Seek to a position in the file, as with fseek(), and return the
                    144: # current file position afterward. Also encapsulates ftell()'s
                    145: # functionality, just Set offset=0, whence=SEEK_CUR.
                    146: #
                    147: # @handle: filehandle returned by guest-file-open
                    148: #
                    149: # @offset: bytes to skip over in the file stream
                    150: #
                    151: # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
                    152: #
                    153: # Returns: GuestFileSeek on success.
                    154: #
                    155: # Since: 0.15.0
                    156: ##
                    157: { 'type': 'GuestFileSeek',
                    158:   'data': { 'position': 'int', 'eof': 'bool' } }
                    159: 
                    160: { 'command': 'guest-file-seek',
                    161:   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
                    162:   'returns': 'GuestFileSeek' }
                    163: 
                    164: ##
                    165: # @guest-file-flush:
                    166: #
                    167: # Write file changes bufferred in userspace to disk/kernel buffers
                    168: #
                    169: # @handle: filehandle returned by guest-file-open
                    170: #
                    171: # Returns: Nothing on success.
                    172: #
                    173: # Since: 0.15.0
                    174: ##
                    175: { 'command': 'guest-file-flush',
                    176:   'data': { 'handle': 'int' } }
                    177: 
                    178: ##
                    179: # @guest-fsfreeze-status:
                    180: #
                    181: # Get guest fsfreeze state. error state indicates failure to thaw 1 or more
                    182: # previously frozen filesystems, or failure to open a previously cached
                    183: # filesytem (filesystem unmounted/directory changes, etc).
                    184: #
                    185: # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
                    186: #
                    187: # Since: 0.15.0
                    188: ##
                    189: { 'enum': 'GuestFsfreezeStatus',
                    190:   'data': [ 'thawed', 'frozen', 'error' ] }
                    191: { 'command': 'guest-fsfreeze-status',
                    192:   'returns': 'GuestFsfreezeStatus' }
                    193: 
                    194: ##
                    195: # @guest-fsfreeze-freeze:
                    196: #
                    197: # Sync and freeze all non-network guest filesystems
                    198: #
                    199: # Returns: Number of file systems frozen on success
                    200: #
                    201: # Since: 0.15.0
                    202: ##
                    203: { 'command': 'guest-fsfreeze-freeze',
                    204:   'returns': 'int' }
                    205: 
                    206: ##
                    207: # @guest-fsfreeze-thaw:
                    208: #
                    209: # Unfreeze frozen guest fileystems
                    210: #
                    211: # Returns: Number of file systems thawed
                    212: #          If error, -1 (unknown error) or -errno
                    213: #
                    214: # Since: 0.15.0
                    215: ##
                    216: { 'command': 'guest-fsfreeze-thaw',
                    217:   'returns': 'int' }

unix.superglobalmegacorp.com