Michael Roth | e3d4d25 | 2011-07-19 15:41:55 -0500 | [diff] [blame] | 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 | # |
Stefan Weil | e7d8100 | 2011-12-10 00:19:46 +0100 | [diff] [blame] | 16 | # Such clients should also precede this command |
Michael Roth | e3d4d25 | 2011-07-19 15:41:55 -0500 | [diff] [blame] | 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 | ## |
Michael Roth | bf95c0d | 2011-12-06 22:03:43 -0600 | [diff] [blame] | 46 | { 'type': 'GuestAgentCommandInfo', |
| 47 | 'data': { 'name': 'str', 'enabled': 'bool' } } |
| 48 | { 'type': 'GuestAgentInfo', |
| 49 | 'data': { 'version': 'str', |
| 50 | 'supported_commands': ['GuestAgentCommandInfo'] } } |
Michael Roth | e3d4d25 | 2011-07-19 15:41:55 -0500 | [diff] [blame] | 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' } |