qapi/ui.json

   1 # -*- Mode: Python -*-
   2 #
   3
   4 ##
   5 # = Remote desktop
   6 ##
   7
   8 { 'include': 'sockets.json' }
   9
  10 ##
  11 # @set_password:
  12 #
  13 # Sets the password of a remote display session.
  14 #
  15 # @protocol: `vnc' to modify the VNC server password
  16 #            `spice' to modify the Spice server password
  17 #
  18 # @password: the new password
  19 #
  20 # @connected: how to handle existing clients when changing the
  21 #                       password.  If nothing is specified, defaults to `keep'
  22 #                       `fail' to fail the command if clients are connected
  23 #                       `disconnect' to disconnect existing clients
  24 #                       `keep' to maintain existing clients
  25 #
  26 # Returns: Nothing on success
  27 #          If Spice is not enabled, DeviceNotFound
  28 #
  29 # Since: 0.14.0
  30 #
  31 # Example:
  32 #
  33 # -> { "execute": "set_password", "arguments": { "protocol": "vnc",
  34 #                                                "password": "secret" } }
  35 # <- { "return": {} }
  36 #
  37 ##
  38 { 'command': 'set_password',
  39   'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
  40
  41 ##
  42 # @expire_password:
  43 #
  44 # Expire the password of a remote display server.
  45 #
  46 # @protocol: the name of the remote display protocol `vnc' or `spice'
  47 #
  48 # @time: when to expire the password.
  49 #        `now' to expire the password immediately
  50 #        `never' to cancel password expiration
  51 #        `+INT' where INT is the number of seconds from now (integer)
  52 #        `INT' where INT is the absolute time in seconds
  53 #
  54 # Returns: Nothing on success
  55 #          If @protocol is `spice' and Spice is not active, DeviceNotFound
  56 #
  57 # Since: 0.14.0
  58 #
  59 # Notes: Time is relative to the server and currently there is no way to
  60 #        coordinate server time with client time.  It is not recommended to
  61 #        use the absolute time version of the @time parameter unless you're
  62 #        sure you are on the same machine as the QEMU instance.
  63 #
  64 # Example:
  65 #
  66 # -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
  67 #                                                   "time": "+60" } }
  68 # <- { "return": {} }
  69 #
  70 ##
  71 { 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
  72
  73 ##
  74 # @screendump:
  75 #
  76 # Write a PPM of the VGA screen to a file.
  77 #
  78 # @filename: the path of a new PPM file to store the image
  79 #
  80 # @device: ID of the display device that should be dumped. If this parameter
  81 #          is missing, the primary display will be used. (Since 2.12)
  82 #
  83 # @head: head to use in case the device supports multiple heads. If this
  84 #        parameter is missing, head #0 will be used. Also note that the head
  85 #        can only be specified in conjunction with the device ID. (Since 2.12)
  86 #
  87 # Returns: Nothing on success
  88 #
  89 # Since: 0.14.0
  90 #
  91 # Example:
  92 #
  93 # -> { "execute": "screendump",
  94 #      "arguments": { "filename": "/tmp/image" } }
  95 # <- { "return": {} }
  96 #
  97 ##
  98 { 'command': 'screendump',
  99   'data': {'filename': 'str', '*device': 'str', '*head': 'int'} }
 100
 101 ##
 102 # == Spice
 103 ##
 104
 105 ##
 106 # @SpiceBasicInfo:
 107 #
 108 # The basic information for SPICE network connection
 109 #
 110 # @host: IP address
 111 #
 112 # @port: port number
 113 #
 114 # @family: address family
 115 #
 116 # Since: 2.1
 117 ##
 118 { 'struct': 'SpiceBasicInfo',
 119   'data': { 'host': 'str',
 120             'port': 'str',
 121             'family': 'NetworkAddressFamily' } }
 122
 123 ##
 124 # @SpiceServerInfo:
 125 #
 126 # Information about a SPICE server
 127 #
 128 # @auth: authentication method
 129 #
 130 # Since: 2.1
 131 ##
 132 { 'struct': 'SpiceServerInfo',
 133   'base': 'SpiceBasicInfo',
 134   'data': { '*auth': 'str' } }
 135
 136 ##
 137 # @SpiceChannel:
 138 #
 139 # Information about a SPICE client channel.
 140 #
 141 # @connection-id: SPICE connection id number.  All channels with the same id
 142 #                 belong to the same SPICE session.
 143 #
 144 # @channel-type: SPICE channel type number.  "1" is the main control
 145 #                channel, filter for this one if you want to track spice
 146 #                sessions only
 147 #
 148 # @channel-id: SPICE channel ID number.  Usually "0", might be different when
 149 #              multiple channels of the same type exist, such as multiple
 150 #              display channels in a multihead setup
 151 #
 152 # @tls: true if the channel is encrypted, false otherwise.
 153 #
 154 # Since: 0.14.0
 155 ##
 156 { 'struct': 'SpiceChannel',
 157   'base': 'SpiceBasicInfo',
 158   'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
 159            'tls': 'bool'} }
 160
 161 ##
 162 # @SpiceQueryMouseMode:
 163 #
 164 # An enumeration of Spice mouse states.
 165 #
 166 # @client: Mouse cursor position is determined by the client.
 167 #
 168 # @server: Mouse cursor position is determined by the server.
 169 #
 170 # @unknown: No information is available about mouse mode used by
 171 #           the spice server.
 172 #
 173 # Note: spice/enums.h has a SpiceMouseMode already, hence the name.
 174 #
 175 # Since: 1.1
 176 ##
 177 { 'enum': 'SpiceQueryMouseMode',
 178   'data': [ 'client', 'server', 'unknown' ] }
 179
 180 ##
 181 # @SpiceInfo:
 182 #
 183 # Information about the SPICE session.
 184 #
 185 # @enabled: true if the SPICE server is enabled, false otherwise
 186 #
 187 # @migrated: true if the last guest migration completed and spice
 188 #            migration had completed as well. false otherwise. (since 1.4)
 189 #
 190 # @host: The hostname the SPICE server is bound to.  This depends on
 191 #        the name resolution on the host and may be an IP address.
 192 #
 193 # @port: The SPICE server's port number.
 194 #
 195 # @compiled-version: SPICE server version.
 196 #
 197 # @tls-port: The SPICE server's TLS port number.
 198 #
 199 # @auth: the current authentication type used by the server
 200 #        'none'  if no authentication is being used
 201 #        'spice' uses SASL or direct TLS authentication, depending on command
 202 #                line options
 203 #
 204 # @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
 205 #              be determined by the client or the server, or unknown if spice
 206 #              server doesn't provide this information. (since: 1.1)
 207 #
 208 # @channels: a list of @SpiceChannel for each active spice channel
 209 #
 210 # Since: 0.14.0
 211 ##
 212 { 'struct': 'SpiceInfo',
 213   'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int',
 214            '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
 215            'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']} }
 216
 217 ##
 218 # @query-spice:
 219 #
 220 # Returns information about the current SPICE server
 221 #
 222 # Returns: @SpiceInfo
 223 #
 224 # Since: 0.14.0
 225 #
 226 # Example:
 227 #
 228 # -> { "execute": "query-spice" }
 229 # <- { "return": {
 230 #          "enabled": true,
 231 #          "auth": "spice",
 232 #          "port": 5920,
 233 #          "tls-port": 5921,
 234 #          "host": "0.0.0.0",
 235 #          "channels": [
 236 #             {
 237 #                "port": "54924",
 238 #                "family": "ipv4",
 239 #                "channel-type": 1,
 240 #                "connection-id": 1804289383,
 241 #                "host": "127.0.0.1",
 242 #                "channel-id": 0,
 243 #                "tls": true
 244 #             },
 245 #             {
 246 #                "port": "36710",
 247 #                "family": "ipv4",
 248 #                "channel-type": 4,
 249 #                "connection-id": 1804289383,
 250 #                "host": "127.0.0.1",
 251 #                "channel-id": 0,
 252 #                "tls": false
 253 #             },
 254 #             [ ... more channels follow ... ]
 255 #          ]
 256 #       }
 257 #    }
 258 #
 259 ##
 260 { 'command': 'query-spice', 'returns': 'SpiceInfo' }
 261
 262 ##
 263 # @SPICE_CONNECTED:
 264 #
 265 # Emitted when a SPICE client establishes a connection
 266 #
 267 # @server: server information
 268 #
 269 # @client: client information
 270 #
 271 # Since: 0.14.0
 272 #
 273 # Example:
 274 #
 275 # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
 276 #      "event": "SPICE_CONNECTED",
 277 #      "data": {
 278 #        "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
 279 #        "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
 280 #    }}
 281 #
 282 ##
 283 { 'event': 'SPICE_CONNECTED',
 284   'data': { 'server': 'SpiceBasicInfo',
 285             'client': 'SpiceBasicInfo' } }
 286
 287 ##
 288 # @SPICE_INITIALIZED:
 289 #
 290 # Emitted after initial handshake and authentication takes place (if any)
 291 # and the SPICE channel is up and running
 292 #
 293 # @server: server information
 294 #
 295 # @client: client information
 296 #
 297 # Since: 0.14.0
 298 #
 299 # Example:
 300 #
 301 # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
 302 #      "event": "SPICE_INITIALIZED",
 303 #      "data": {"server": {"auth": "spice", "port": "5921",
 304 #                          "family": "ipv4", "host": "127.0.0.1"},
 305 #               "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
 306 #                          "connection-id": 1804289383, "host": "127.0.0.1",
 307 #                          "channel-id": 0, "tls": true}
 308 #    }}
 309 #
 310 ##
 311 { 'event': 'SPICE_INITIALIZED',
 312   'data': { 'server': 'SpiceServerInfo',
 313             'client': 'SpiceChannel' } }
 314
 315 ##
 316 # @SPICE_DISCONNECTED:
 317 #
 318 # Emitted when the SPICE connection is closed
 319 #
 320 # @server: server information
 321 #
 322 # @client: client information
 323 #
 324 # Since: 0.14.0
 325 #
 326 # Example:
 327 #
 328 # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
 329 #      "event": "SPICE_DISCONNECTED",
 330 #      "data": {
 331 #        "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
 332 #        "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
 333 #    }}
 334 #
 335 ##
 336 { 'event': 'SPICE_DISCONNECTED',
 337   'data': { 'server': 'SpiceBasicInfo',
 338             'client': 'SpiceBasicInfo' } }
 339
 340 ##
 341 # @SPICE_MIGRATE_COMPLETED:
 342 #
 343 # Emitted when SPICE migration has completed
 344 #
 345 # Since: 1.3
 346 #
 347 # Example:
 348 #
 349 # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
 350 #      "event": "SPICE_MIGRATE_COMPLETED" }
 351 #
 352 ##
 353 { 'event': 'SPICE_MIGRATE_COMPLETED' }
 354
 355 ##
 356 # == VNC
 357 ##
 358
 359 ##
 360 # @VncBasicInfo:
 361 #
 362 # The basic information for vnc network connection
 363 #
 364 # @host: IP address
 365 #
 366 # @service: The service name of the vnc port. This may depend on the host
 367 #           system's service database so symbolic names should not be relied
 368 #           on.
 369 #
 370 # @family: address family
 371 #
 372 # @websocket: true in case the socket is a websocket (since 2.3).
 373 #
 374 # Since: 2.1
 375 ##
 376 { 'struct': 'VncBasicInfo',
 377   'data': { 'host': 'str',
 378             'service': 'str',
 379             'family': 'NetworkAddressFamily',
 380             'websocket': 'bool' } }
 381
 382 ##
 383 # @VncServerInfo:
 384 #
 385 # The network connection information for server
 386 #
 387 # @auth: authentication method used for
 388 #        the plain (non-websocket) VNC server
 389 #
 390 # Since: 2.1
 391 ##
 392 { 'struct': 'VncServerInfo',
 393   'base': 'VncBasicInfo',
 394   'data': { '*auth': 'str' } }
 395
 396 ##
 397 # @VncClientInfo:
 398 #
 399 # Information about a connected VNC client.
 400 #
 401 # @x509_dname: If x509 authentication is in use, the Distinguished
 402 #              Name of the client.
 403 #
 404 # @sasl_username: If SASL authentication is in use, the SASL username
 405 #                 used for authentication.
 406 #
 407 # Since: 0.14.0
 408 ##
 409 { 'struct': 'VncClientInfo',
 410   'base': 'VncBasicInfo',
 411   'data': { '*x509_dname': 'str', '*sasl_username': 'str' } }
 412
 413 ##
 414 # @VncInfo:
 415 #
 416 # Information about the VNC session.
 417 #
 418 # @enabled: true if the VNC server is enabled, false otherwise
 419 #
 420 # @host: The hostname the VNC server is bound to.  This depends on
 421 #        the name resolution on the host and may be an IP address.
 422 #
 423 # @family: 'ipv6' if the host is listening for IPv6 connections
 424 #                    'ipv4' if the host is listening for IPv4 connections
 425 #                    'unix' if the host is listening on a unix domain socket
 426 #                    'unknown' otherwise
 427 #
 428 # @service: The service name of the server's port.  This may depends
 429 #           on the host system's service database so symbolic names should not
 430 #           be relied on.
 431 #
 432 # @auth: the current authentication type used by the server
 433 #        'none' if no authentication is being used
 434 #        'vnc' if VNC authentication is being used
 435 #        'vencrypt+plain' if VEncrypt is used with plain text authentication
 436 #        'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
 437 #        'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
 438 #        'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
 439 #        'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
 440 #        'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
 441 #        'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
 442 #        'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
 443 #        'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
 444 #
 445 # @clients: a list of @VncClientInfo of all currently connected clients
 446 #
 447 # Since: 0.14.0
 448 ##
 449 { 'struct': 'VncInfo',
 450   'data': {'enabled': 'bool', '*host': 'str',
 451            '*family': 'NetworkAddressFamily',
 452            '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']} }
 453
 454 ##
 455 # @VncPrimaryAuth:
 456 #
 457 # vnc primary authentication method.
 458 #
 459 # Since: 2.3
 460 ##
 461 { 'enum': 'VncPrimaryAuth',
 462   'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra',
 463             'tls', 'vencrypt', 'sasl' ] }
 464
 465 ##
 466 # @VncVencryptSubAuth:
 467 #
 468 # vnc sub authentication method with vencrypt.
 469 #
 470 # Since: 2.3
 471 ##
 472 { 'enum': 'VncVencryptSubAuth',
 473   'data': [ 'plain',
 474             'tls-none',  'x509-none',
 475             'tls-vnc',   'x509-vnc',
 476             'tls-plain', 'x509-plain',
 477             'tls-sasl',  'x509-sasl' ] }
 478
 479
 480 ##
 481 # @VncServerInfo2:
 482 #
 483 # The network connection information for server
 484 #
 485 # @auth: The current authentication type used by the servers
 486 #
 487 # @vencrypt: The vencrypt sub authentication type used by the
 488 #            servers, only specified in case auth == vencrypt.
 489 #
 490 # Since: 2.9
 491 ##
 492 { 'struct': 'VncServerInfo2',
 493   'base': 'VncBasicInfo',
 494   'data': { 'auth'      : 'VncPrimaryAuth',
 495             '*vencrypt' : 'VncVencryptSubAuth' } }
 496
 497
 498 ##
 499 # @VncInfo2:
 500 #
 501 # Information about a vnc server
 502 #
 503 # @id: vnc server name.
 504 #
 505 # @server: A list of @VncBasincInfo describing all listening sockets.
 506 #          The list can be empty (in case the vnc server is disabled).
 507 #          It also may have multiple entries: normal + websocket,
 508 #          possibly also ipv4 + ipv6 in the future.
 509 #
 510 # @clients: A list of @VncClientInfo of all currently connected clients.
 511 #           The list can be empty, for obvious reasons.
 512 #
 513 # @auth: The current authentication type used by the non-websockets servers
 514 #
 515 # @vencrypt: The vencrypt authentication type used by the servers,
 516 #            only specified in case auth == vencrypt.
 517 #
 518 # @display: The display device the vnc server is linked to.
 519 #
 520 # Since: 2.3
 521 ##
 522 { 'struct': 'VncInfo2',
 523   'data': { 'id'        : 'str',
 524             'server'    : ['VncServerInfo2'],
 525             'clients'   : ['VncClientInfo'],
 526             'auth'      : 'VncPrimaryAuth',
 527             '*vencrypt' : 'VncVencryptSubAuth',
 528             '*display'  : 'str' } }
 529
 530 ##
 531 # @query-vnc:
 532 #
 533 # Returns information about the current VNC server
 534 #
 535 # Returns: @VncInfo
 536 #
 537 # Since: 0.14.0
 538 #
 539 # Example:
 540 #
 541 # -> { "execute": "query-vnc" }
 542 # <- { "return": {
 543 #          "enabled":true,
 544 #          "host":"0.0.0.0",
 545 #          "service":"50402",
 546 #          "auth":"vnc",
 547 #          "family":"ipv4",
 548 #          "clients":[
 549 #             {
 550 #                "host":"127.0.0.1",
 551 #                "service":"50401",
 552 #                "family":"ipv4"
 553 #             }
 554 #          ]
 555 #       }
 556 #    }
 557 #
 558 ##
 559 { 'command': 'query-vnc', 'returns': 'VncInfo' }
 560
 561 ##
 562 # @query-vnc-servers:
 563 #
 564 # Returns a list of vnc servers.  The list can be empty.
 565 #
 566 # Returns: a list of @VncInfo2
 567 #
 568 # Since: 2.3
 569 ##
 570 { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'] }
 571
 572 ##
 573 # @change-vnc-password:
 574 #
 575 # Change the VNC server password.
 576 #
 577 # @password:  the new password to use with VNC authentication
 578 #
 579 # Since: 1.1
 580 #
 581 # Notes:  An empty password in this command will set the password to the empty
 582 #         string.  Existing clients are unaffected by executing this command.
 583 ##
 584 { 'command': 'change-vnc-password', 'data': {'password': 'str'} }
 585
 586 ##
 587 # @VNC_CONNECTED:
 588 #
 589 # Emitted when a VNC client establishes a connection
 590 #
 591 # @server: server information
 592 #
 593 # @client: client information
 594 #
 595 # Note: This event is emitted before any authentication takes place, thus
 596 # the authentication ID is not provided
 597 #
 598 # Since: 0.13.0
 599 #
 600 # Example:
 601 #
 602 # <- { "event": "VNC_CONNECTED",
 603 #      "data": {
 604 #            "server": { "auth": "sasl", "family": "ipv4",
 605 #                        "service": "5901", "host": "0.0.0.0" },
 606 #            "client": { "family": "ipv4", "service": "58425",
 607 #                        "host": "127.0.0.1" } },
 608 #      "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
 609 #
 610 ##
 611 { 'event': 'VNC_CONNECTED',
 612   'data': { 'server': 'VncServerInfo',
 613             'client': 'VncBasicInfo' } }
 614
 615 ##
 616 # @VNC_INITIALIZED:
 617 #
 618 # Emitted after authentication takes place (if any) and the VNC session is
 619 # made active
 620 #
 621 # @server: server information
 622 #
 623 # @client: client information
 624 #
 625 # Since: 0.13.0
 626 #
 627 # Example:
 628 #
 629 # <-  { "event": "VNC_INITIALIZED",
 630 #       "data": {
 631 #            "server": { "auth": "sasl", "family": "ipv4",
 632 #                        "service": "5901", "host": "0.0.0.0"},
 633 #            "client": { "family": "ipv4", "service": "46089",
 634 #                        "host": "127.0.0.1", "sasl_username": "luiz" } },
 635 #       "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
 636 #
 637 ##
 638 { 'event': 'VNC_INITIALIZED',
 639   'data': { 'server': 'VncServerInfo',
 640             'client': 'VncClientInfo' } }
 641
 642 ##
 643 # @VNC_DISCONNECTED:
 644 #
 645 # Emitted when the connection is closed
 646 #
 647 # @server: server information
 648 #
 649 # @client: client information
 650 #
 651 # Since: 0.13.0
 652 #
 653 # Example:
 654 #
 655 # <- { "event": "VNC_DISCONNECTED",
 656 #      "data": {
 657 #            "server": { "auth": "sasl", "family": "ipv4",
 658 #                        "service": "5901", "host": "0.0.0.0" },
 659 #            "client": { "family": "ipv4", "service": "58425",
 660 #                        "host": "127.0.0.1", "sasl_username": "luiz" } },
 661 #      "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
 662 #
 663 ##
 664 { 'event': 'VNC_DISCONNECTED',
 665   'data': { 'server': 'VncServerInfo',
 666             'client': 'VncClientInfo' } }
 667
 668 ##
 669 # = Input
 670 ##
 671
 672 ##
 673 # @MouseInfo:
 674 #
 675 # Information about a mouse device.
 676 #
 677 # @name: the name of the mouse device
 678 #
 679 # @index: the index of the mouse device
 680 #
 681 # @current: true if this device is currently receiving mouse events
 682 #
 683 # @absolute: true if this device supports absolute coordinates as input
 684 #
 685 # Since: 0.14.0
 686 ##
 687 { 'struct': 'MouseInfo',
 688   'data': {'name': 'str', 'index': 'int', 'current': 'bool',
 689            'absolute': 'bool'} }
 690
 691 ##
 692 # @query-mice:
 693 #
 694 # Returns information about each active mouse device
 695 #
 696 # Returns: a list of @MouseInfo for each device
 697 #
 698 # Since: 0.14.0
 699 #
 700 # Example:
 701 #
 702 # -> { "execute": "query-mice" }
 703 # <- { "return": [
 704 #          {
 705 #             "name":"QEMU Microsoft Mouse",
 706 #             "index":0,
 707 #             "current":false,
 708 #             "absolute":false
 709 #          },
 710 #          {
 711 #             "name":"QEMU PS/2 Mouse",
 712 #             "index":1,
 713 #             "current":true,
 714 #             "absolute":true
 715 #          }
 716 #       ]
 717 #    }
 718 #
 719 ##
 720 { 'command': 'query-mice', 'returns': ['MouseInfo'] }
 721
 722 ##
 723 # @QKeyCode:
 724 #
 725 # An enumeration of key name.
 726 #
 727 # This is used by the @send-key command.
 728 #
 729 # @unmapped: since 2.0
 730 # @pause: since 2.0
 731 # @ro: since 2.4
 732 # @kp_comma: since 2.4
 733 # @kp_equals: since 2.6
 734 # @power: since 2.6
 735 # @hiragana: since 2.9
 736 # @henkan: since 2.9
 737 # @yen: since 2.9
 738 #
 739 # @sleep: since 2.10
 740 # @wake: since 2.10
 741 # @audionext: since 2.10
 742 # @audioprev: since 2.10
 743 # @audiostop: since 2.10
 744 # @audioplay: since 2.10
 745 # @audiomute: since 2.10
 746 # @volumeup: since 2.10
 747 # @volumedown: since 2.10
 748 # @mediaselect: since 2.10
 749 # @mail: since 2.10
 750 # @calculator: since 2.10
 751 # @computer: since 2.10
 752 # @ac_home: since 2.10
 753 # @ac_back: since 2.10
 754 # @ac_forward: since 2.10
 755 # @ac_refresh: since 2.10
 756 # @ac_bookmarks: since 2.10
 757 # altgr, altgr_r: dropped in 2.10
 758 #
 759 # @muhenkan: since 2.12
 760 # @katakanahiragana: since 2.12
 761 #
 762 # 'sysrq' was mistakenly added to hack around the fact that
 763 # the ps2 driver was not generating correct scancodes sequences
 764 # when 'alt+print' was pressed. This flaw is now fixed and the
 765 # 'sysrq' key serves no further purpose. Any further use of
 766 # 'sysrq' will be transparently changed to 'print', so they
 767 # are effectively synonyms.
 768 #
 769 # Since: 1.3.0
 770 #
 771 ##
 772 { 'enum': 'QKeyCode',
 773   'data': [ 'unmapped',
 774             'shift', 'shift_r', 'alt', 'alt_r', 'ctrl',
 775             'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8',
 776             '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e',
 777             'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right',
 778             'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon',
 779             'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b',
 780             'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock',
 781             'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
 782             'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply',
 783             'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0',
 784             'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8',
 785             'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end',
 786             'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again',
 787             'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut',
 788             'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause',
 789             'ro', 'hiragana', 'henkan', 'yen', 'muhenkan', 'katakanahiragana',
 790             'kp_comma', 'kp_equals', 'power', 'sleep', 'wake',
 791             'audionext', 'audioprev', 'audiostop', 'audioplay', 'audiomute',
 792             'volumeup', 'volumedown', 'mediaselect',
 793             'mail', 'calculator', 'computer',
 794             'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks' ] }
 795
 796 ##
 797 # @KeyValue:
 798 #
 799 # Represents a keyboard key.
 800 #
 801 # Since: 1.3.0
 802 ##
 803 { 'union': 'KeyValue',
 804   'data': {
 805     'number': 'int',
 806     'qcode': 'QKeyCode' } }
 807
 808 ##
 809 # @send-key:
 810 #
 811 # Send keys to guest.
 812 #
 813 # @keys: An array of @KeyValue elements. All @KeyValues in this array are
 814 #        simultaneously sent to the guest. A @KeyValue.number value is sent
 815 #        directly to the guest, while @KeyValue.qcode must be a valid
 816 #        @QKeyCode value
 817 #
 818 # @hold-time: time to delay key up events, milliseconds. Defaults
 819 #             to 100
 820 #
 821 # Returns: Nothing on success
 822 #          If key is unknown or redundant, InvalidParameter
 823 #
 824 # Since: 1.3.0
 825 #
 826 # Example:
 827 #
 828 # -> { "execute": "send-key",
 829 #      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
 830 #                               { "type": "qcode", "data": "alt" },
 831 #                               { "type": "qcode", "data": "delete" } ] } }
 832 # <- { "return": {} }
 833 #
 834 ##
 835 { 'command': 'send-key',
 836   'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
 837
 838 ##
 839 # @InputButton:
 840 #
 841 # Button of a pointer input device (mouse, tablet).
 842 #
 843 # @side: front side button of a 5-button mouse (since 2.9)
 844 #
 845 # @extra: rear side button of a 5-button mouse (since 2.9)
 846 #
 847 # Since: 2.0
 848 ##
 849 { 'enum'  : 'InputButton',
 850   'data'  : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side',
 851   'extra' ] }
 852
 853 ##
 854 # @InputAxis:
 855 #
 856 # Position axis of a pointer input device (mouse, tablet).
 857 #
 858 # Since: 2.0
 859 ##
 860 { 'enum'  : 'InputAxis',
 861   'data'  : [ 'x', 'y' ] }
 862
 863 ##
 864 # @InputKeyEvent:
 865 #
 866 # Keyboard input event.
 867 #
 868 # @key:    Which key this event is for.
 869 # @down:   True for key-down and false for key-up events.
 870 #
 871 # Since: 2.0
 872 ##
 873 { 'struct'  : 'InputKeyEvent',
 874   'data'  : { 'key'     : 'KeyValue',
 875               'down'    : 'bool' } }
 876
 877 ##
 878 # @InputBtnEvent:
 879 #
 880 # Pointer button input event.
 881 #
 882 # @button: Which button this event is for.
 883 # @down:   True for key-down and false for key-up events.
 884 #
 885 # Since: 2.0
 886 ##
 887 { 'struct'  : 'InputBtnEvent',
 888   'data'  : { 'button'  : 'InputButton',
 889               'down'    : 'bool' } }
 890
 891 ##
 892 # @InputMoveEvent:
 893 #
 894 # Pointer motion input event.
 895 #
 896 # @axis:   Which axis is referenced by @value.
 897 # @value:  Pointer position.  For absolute coordinates the
 898 #          valid range is 0 -> 0x7ffff
 899 #
 900 # Since: 2.0
 901 ##
 902 { 'struct'  : 'InputMoveEvent',
 903   'data'  : { 'axis'    : 'InputAxis',
 904               'value'   : 'int' } }
 905
 906 ##
 907 # @InputEvent:
 908 #
 909 # Input event union.
 910 #
 911 # @type: the input type, one of:
 912 #  - 'key': Input event of Keyboard
 913 #  - 'btn': Input event of pointer buttons
 914 #  - 'rel': Input event of relative pointer motion
 915 #  - 'abs': Input event of absolute pointer motion
 916 #
 917 # Since: 2.0
 918 ##
 919 { 'union' : 'InputEvent',
 920   'data'  : { 'key'     : 'InputKeyEvent',
 921               'btn'     : 'InputBtnEvent',
 922               'rel'     : 'InputMoveEvent',
 923               'abs'     : 'InputMoveEvent' } }
 924
 925 ##
 926 # @input-send-event:
 927 #
 928 # Send input event(s) to guest.
 929 #
 930 # @device: display device to send event(s) to.
 931 # @head: head to send event(s) to, in case the
 932 #        display device supports multiple scanouts.
 933 # @events: List of InputEvent union.
 934 #
 935 # Returns: Nothing on success.
 936 #
 937 # The @device and @head parameters can be used to send the input event
 938 # to specific input devices in case (a) multiple input devices of the
 939 # same kind are added to the virtual machine and (b) you have
 940 # configured input routing (see docs/multiseat.txt) for those input
 941 # devices.  The parameters work exactly like the device and head
 942 # properties of input devices.  If @device is missing, only devices
 943 # that have no input routing config are admissible.  If @device is
 944 # specified, both input devices with and without input routing config
 945 # are admissible, but devices with input routing config take
 946 # precedence.
 947 #
 948 # Since: 2.6
 949 #
 950 # Note: The consoles are visible in the qom tree, under
 951 # /backend/console[$index]. They have a device link and head property,
 952 # so it is possible to map which console belongs to which device and
 953 # display.
 954 #
 955 # Example:
 956 #
 957 # 1. Press left mouse button.
 958 #
 959 # -> { "execute": "input-send-event",
 960 #     "arguments": { "device": "video0",
 961 #                    "events": [ { "type": "btn",
 962 #                    "data" : { "down": true, "button": "left" } } ] } }
 963 # <- { "return": {} }
 964 #
 965 # -> { "execute": "input-send-event",
 966 #     "arguments": { "device": "video0",
 967 #                    "events": [ { "type": "btn",
 968 #                    "data" : { "down": false, "button": "left" } } ] } }
 969 # <- { "return": {} }
 970 #
 971 # 2. Press ctrl-alt-del.
 972 #
 973 # -> { "execute": "input-send-event",
 974 #      "arguments": { "events": [
 975 #         { "type": "key", "data" : { "down": true,
 976 #           "key": {"type": "qcode", "data": "ctrl" } } },
 977 #         { "type": "key", "data" : { "down": true,
 978 #           "key": {"type": "qcode", "data": "alt" } } },
 979 #         { "type": "key", "data" : { "down": true,
 980 #           "key": {"type": "qcode", "data": "delete" } } } ] } }
 981 # <- { "return": {} }
 982 #
 983 # 3. Move mouse pointer to absolute coordinates (20000, 400).
 984 #
 985 # -> { "execute": "input-send-event" ,
 986 #   "arguments": { "events": [
 987 #                { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
 988 #                { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
 989 # <- { "return": {} }
 990 #
 991 ##
 992 { 'command': 'input-send-event',
 993   'data': { '*device': 'str',
 994             '*head'  : 'int',
 995             'events' : [ 'InputEvent' ] } }
 996
 997
 998 ##
 999 # @DisplayNoOpts:
1000 #
1001 # Empty struct for displays without config options.
1002 #
1003 # Since: 2.12
1004 #
1005 ##
1006 { 'struct'  : 'DisplayNoOpts',
1007   'data'    : { } }
1008
1009 ##
1010 # @DisplayGTK:
1011 #
1012 # GTK display options.
1013 #
1014 # @grab-on-hover: Grab keyboard input on mouse hover.
1015 #
1016 # Since: 2.12
1017 #
1018 ##
1019 { 'struct'  : 'DisplayGTK',
1020   'data'    : { '*grab-on-hover' : 'bool' } }
1021
1022  ##
1023  # @DisplayGLMode:
1024  #
1025  # Display OpenGL mode.
1026  #
1027  # @off: Disable OpenGL (default).
1028  # @on: Use OpenGL, pick context type automatically.
1029  #      Would better be named 'auto' but is called 'on' for backward
1030  #      compatibility with bool type.
1031  # @core: Use OpenGL with Core (desktop) Context.
1032  # @es: Use OpenGL with ES (embedded systems) Context.
1033  #
1034  # Since: 2.13
1035  #
1036  ##
1037  { 'enum'    : 'DisplayGLMode',
1038    'data'    : [ 'off', 'on', 'core', 'es' ] }
1039
1040 ##
1041 # @DisplayType:
1042 #
1043 # Display (user interface) type.
1044 #
1045 # Since: 2.12
1046 #
1047 ##
1048 { 'enum'    : 'DisplayType',
1049   'data'    : [ 'default', 'none', 'gtk', 'sdl',
1050                 'egl-headless', 'curses', 'cocoa' ] }
1051
1052 ##
1053 # @DisplayOptions:
1054 #
1055 # Display (user interface) options.
1056 #
1057 # @type:          Which DisplayType qemu should use.
1058 # @full-screen:   Start user interface in fullscreen mode (default: off).
1059 # @window-close:  Allow to quit qemu with window close button (default: on).
1060 # @gl:            Enable OpenGL support (default: off).
1061 #
1062 # Since: 2.12
1063 #
1064 ##
1065 { 'union'   : 'DisplayOptions',
1066   'base'    : { 'type'           : 'DisplayType',
1067                 '*full-screen'   : 'bool',
1068                 '*window-close'  : 'bool',
1069                 '*gl'            : 'DisplayGLMode' },
1070   'discriminator' : 'type',
1071   'data'    : { 'default'        : 'DisplayNoOpts',
1072                 'none'           : 'DisplayNoOpts',
1073                 'gtk'            : 'DisplayGTK',
1074                 'sdl'            : 'DisplayNoOpts',
1075                 'egl-headless'   : 'DisplayNoOpts',
1076                 'curses'         : 'DisplayNoOpts',
1077                 'cocoa'          : 'DisplayNoOpts' } }