1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4 5## 6# = Remote desktop 7## 8 9{ 'include': 'common.json' } 10{ 'include': 'sockets.json' } 11 12## 13# @DisplayProtocol: 14# 15# Display protocols which support changing password options. 16# 17# Since: 7.0 18# 19## 20{ 'enum': 'DisplayProtocol', 21 'data': [ 'vnc', 'spice' ] } 22 23## 24# @SetPasswordAction: 25# 26# An action to take on changing a password on a connection with active clients. 27# 28# @keep: maintain existing clients 29# 30# @fail: fail the command if clients are connected 31# 32# @disconnect: disconnect existing clients 33# 34# Since: 7.0 35# 36## 37{ 'enum': 'SetPasswordAction', 38 'data': [ 'keep', 'fail', 'disconnect' ] } 39 40## 41# @SetPasswordOptions: 42# 43# Options for set_password. 44# 45# @protocol: - 'vnc' to modify the VNC server password 46# - 'spice' to modify the Spice server password 47# 48# @password: the new password 49# 50# @connected: How to handle existing clients when changing the 51# password. If nothing is specified, defaults to 'keep'. 52# For VNC, only 'keep' is currently implemented. 53# 54# Since: 7.0 55# 56## 57{ 'union': 'SetPasswordOptions', 58 'base': { 'protocol': 'DisplayProtocol', 59 'password': 'str', 60 '*connected': 'SetPasswordAction' }, 61 'discriminator': 'protocol', 62 'data': { 'vnc': 'SetPasswordOptionsVnc' } } 63 64## 65# @SetPasswordOptionsVnc: 66# 67# Options for set_password specific to the VNC procotol. 68# 69# @display: The id of the display where the password should be changed. 70# Defaults to the first. 71# 72# Since: 7.0 73# 74## 75{ 'struct': 'SetPasswordOptionsVnc', 76 'data': { '*display': 'str' } } 77 78## 79# @set_password: 80# 81# Set the password of a remote display server. 82# 83# Returns: - Nothing on success 84# - If Spice is not enabled, DeviceNotFound 85# 86# Since: 0.14 87# 88# Example: 89# 90# -> { "execute": "set_password", "arguments": { "protocol": "vnc", 91# "password": "secret" } } 92# <- { "return": {} } 93# 94## 95{ 'command': 'set_password', 'boxed': true, 'data': 'SetPasswordOptions' } 96 97## 98# @ExpirePasswordOptions: 99# 100# General options for expire_password. 101# 102# @protocol: - 'vnc' to modify the VNC server expiration 103# - 'spice' to modify the Spice server expiration 104# 105# @time: when to expire the password. 106# 107# - 'now' to expire the password immediately 108# - 'never' to cancel password expiration 109# - '+INT' where INT is the number of seconds from now (integer) 110# - 'INT' where INT is the absolute time in seconds 111# 112# Notes: Time is relative to the server and currently there is no way to 113# coordinate server time with client time. It is not recommended to 114# use the absolute time version of the @time parameter unless you're 115# sure you are on the same machine as the QEMU instance. 116# 117# Since: 7.0 118# 119## 120{ 'union': 'ExpirePasswordOptions', 121 'base': { 'protocol': 'DisplayProtocol', 122 'time': 'str' }, 123 'discriminator': 'protocol', 124 'data': { 'vnc': 'ExpirePasswordOptionsVnc' } } 125 126## 127# @ExpirePasswordOptionsVnc: 128# 129# Options for expire_password specific to the VNC procotol. 130# 131# @display: The id of the display where the expiration should be changed. 132# Defaults to the first. 133# 134# Since: 7.0 135# 136## 137 138{ 'struct': 'ExpirePasswordOptionsVnc', 139 'data': { '*display': 'str' } } 140 141## 142# @expire_password: 143# 144# Expire the password of a remote display server. 145# 146# Returns: - Nothing on success 147# - If @protocol is 'spice' and Spice is not active, DeviceNotFound 148# 149# Since: 0.14 150# 151# Example: 152# 153# -> { "execute": "expire_password", "arguments": { "protocol": "vnc", 154# "time": "+60" } } 155# <- { "return": {} } 156# 157## 158{ 'command': 'expire_password', 'boxed': true, 'data': 'ExpirePasswordOptions' } 159 160## 161# @ImageFormat: 162# 163# Supported image format types. 164# 165# @png: PNG format 166# 167# @ppm: PPM format 168# 169# Since: 7.1 170# 171## 172{ 'enum': 'ImageFormat', 173 'data': ['ppm', 'png'] } 174 175## 176# @screendump: 177# 178# Capture the contents of a screen and write it to a file. 179# 180# @filename: the path of a new file to store the image 181# 182# @device: ID of the display device that should be dumped. If this parameter 183# is missing, the primary display will be used. (Since 2.12) 184# 185# @head: head to use in case the device supports multiple heads. If this 186# parameter is missing, head #0 will be used. Also note that the head 187# can only be specified in conjunction with the device ID. (Since 2.12) 188# 189# @format: image format for screendump. (default: ppm) (Since 7.1) 190# 191# Returns: Nothing on success 192# 193# Since: 0.14 194# 195# Example: 196# 197# -> { "execute": "screendump", 198# "arguments": { "filename": "/tmp/image" } } 199# <- { "return": {} } 200# 201## 202{ 'command': 'screendump', 203 'data': {'filename': 'str', '*device': 'str', '*head': 'int', 204 '*format': 'ImageFormat'}, 205 'coroutine': true } 206 207## 208# == Spice 209## 210 211## 212# @SpiceBasicInfo: 213# 214# The basic information for SPICE network connection 215# 216# @host: IP address 217# 218# @port: port number 219# 220# @family: address family 221# 222# Since: 2.1 223## 224{ 'struct': 'SpiceBasicInfo', 225 'data': { 'host': 'str', 226 'port': 'str', 227 'family': 'NetworkAddressFamily' }, 228 'if': 'CONFIG_SPICE' } 229 230## 231# @SpiceServerInfo: 232# 233# Information about a SPICE server 234# 235# @auth: authentication method 236# 237# Since: 2.1 238## 239{ 'struct': 'SpiceServerInfo', 240 'base': 'SpiceBasicInfo', 241 'data': { '*auth': 'str' }, 242 'if': 'CONFIG_SPICE' } 243 244## 245# @SpiceChannel: 246# 247# Information about a SPICE client channel. 248# 249# @connection-id: SPICE connection id number. All channels with the same id 250# belong to the same SPICE session. 251# 252# @channel-type: SPICE channel type number. "1" is the main control 253# channel, filter for this one if you want to track spice 254# sessions only 255# 256# @channel-id: SPICE channel ID number. Usually "0", might be different when 257# multiple channels of the same type exist, such as multiple 258# display channels in a multihead setup 259# 260# @tls: true if the channel is encrypted, false otherwise. 261# 262# Since: 0.14 263## 264{ 'struct': 'SpiceChannel', 265 'base': 'SpiceBasicInfo', 266 'data': {'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int', 267 'tls': 'bool'}, 268 'if': 'CONFIG_SPICE' } 269 270## 271# @SpiceQueryMouseMode: 272# 273# An enumeration of Spice mouse states. 274# 275# @client: Mouse cursor position is determined by the client. 276# 277# @server: Mouse cursor position is determined by the server. 278# 279# @unknown: No information is available about mouse mode used by 280# the spice server. 281# 282# Note: spice/enums.h has a SpiceMouseMode already, hence the name. 283# 284# Since: 1.1 285## 286{ 'enum': 'SpiceQueryMouseMode', 287 'data': [ 'client', 'server', 'unknown' ], 288 'if': 'CONFIG_SPICE' } 289 290## 291# @SpiceInfo: 292# 293# Information about the SPICE session. 294# 295# @enabled: true if the SPICE server is enabled, false otherwise 296# 297# @migrated: true if the last guest migration completed and spice 298# migration had completed as well. false otherwise. (since 1.4) 299# 300# @host: The hostname the SPICE server is bound to. This depends on 301# the name resolution on the host and may be an IP address. 302# 303# @port: The SPICE server's port number. 304# 305# @compiled-version: SPICE server version. 306# 307# @tls-port: The SPICE server's TLS port number. 308# 309# @auth: the current authentication type used by the server 310# 311# - 'none' if no authentication is being used 312# - 'spice' uses SASL or direct TLS authentication, depending on command 313# line options 314# 315# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can 316# be determined by the client or the server, or unknown if spice 317# server doesn't provide this information. (since: 1.1) 318# 319# @channels: a list of @SpiceChannel for each active spice channel 320# 321# Since: 0.14 322## 323{ 'struct': 'SpiceInfo', 324 'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int', 325 '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str', 326 'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']}, 327 'if': 'CONFIG_SPICE' } 328 329## 330# @query-spice: 331# 332# Returns information about the current SPICE server 333# 334# Returns: @SpiceInfo 335# 336# Since: 0.14 337# 338# Example: 339# 340# -> { "execute": "query-spice" } 341# <- { "return": { 342# "enabled": true, 343# "auth": "spice", 344# "port": 5920, 345# "migrated":false, 346# "tls-port": 5921, 347# "host": "0.0.0.0", 348# "mouse-mode":"client", 349# "channels": [ 350# { 351# "port": "54924", 352# "family": "ipv4", 353# "channel-type": 1, 354# "connection-id": 1804289383, 355# "host": "127.0.0.1", 356# "channel-id": 0, 357# "tls": true 358# }, 359# { 360# "port": "36710", 361# "family": "ipv4", 362# "channel-type": 4, 363# "connection-id": 1804289383, 364# "host": "127.0.0.1", 365# "channel-id": 0, 366# "tls": false 367# }, 368# [ ... more channels follow ... ] 369# ] 370# } 371# } 372# 373## 374{ 'command': 'query-spice', 'returns': 'SpiceInfo', 375 'if': 'CONFIG_SPICE' } 376 377## 378# @SPICE_CONNECTED: 379# 380# Emitted when a SPICE client establishes a connection 381# 382# @server: server information 383# 384# @client: client information 385# 386# Since: 0.14 387# 388# Example: 389# 390# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, 391# "event": "SPICE_CONNECTED", 392# "data": { 393# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, 394# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} 395# }} 396# 397## 398{ 'event': 'SPICE_CONNECTED', 399 'data': { 'server': 'SpiceBasicInfo', 400 'client': 'SpiceBasicInfo' }, 401 'if': 'CONFIG_SPICE' } 402 403## 404# @SPICE_INITIALIZED: 405# 406# Emitted after initial handshake and authentication takes place (if any) 407# and the SPICE channel is up and running 408# 409# @server: server information 410# 411# @client: client information 412# 413# Since: 0.14 414# 415# Example: 416# 417# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, 418# "event": "SPICE_INITIALIZED", 419# "data": {"server": {"auth": "spice", "port": "5921", 420# "family": "ipv4", "host": "127.0.0.1"}, 421# "client": {"port": "49004", "family": "ipv4", "channel-type": 3, 422# "connection-id": 1804289383, "host": "127.0.0.1", 423# "channel-id": 0, "tls": true} 424# }} 425# 426## 427{ 'event': 'SPICE_INITIALIZED', 428 'data': { 'server': 'SpiceServerInfo', 429 'client': 'SpiceChannel' }, 430 'if': 'CONFIG_SPICE' } 431 432## 433# @SPICE_DISCONNECTED: 434# 435# Emitted when the SPICE connection is closed 436# 437# @server: server information 438# 439# @client: client information 440# 441# Since: 0.14 442# 443# Example: 444# 445# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, 446# "event": "SPICE_DISCONNECTED", 447# "data": { 448# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, 449# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} 450# }} 451# 452## 453{ 'event': 'SPICE_DISCONNECTED', 454 'data': { 'server': 'SpiceBasicInfo', 455 'client': 'SpiceBasicInfo' }, 456 'if': 'CONFIG_SPICE' } 457 458## 459# @SPICE_MIGRATE_COMPLETED: 460# 461# Emitted when SPICE migration has completed 462# 463# Since: 1.3 464# 465# Example: 466# 467# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, 468# "event": "SPICE_MIGRATE_COMPLETED" } 469# 470## 471{ 'event': 'SPICE_MIGRATE_COMPLETED', 472 'if': 'CONFIG_SPICE' } 473 474## 475# == VNC 476## 477 478## 479# @VncBasicInfo: 480# 481# The basic information for vnc network connection 482# 483# @host: IP address 484# 485# @service: The service name of the vnc port. This may depend on the host 486# system's service database so symbolic names should not be relied 487# on. 488# 489# @family: address family 490# 491# @websocket: true in case the socket is a websocket (since 2.3). 492# 493# Since: 2.1 494## 495{ 'struct': 'VncBasicInfo', 496 'data': { 'host': 'str', 497 'service': 'str', 498 'family': 'NetworkAddressFamily', 499 'websocket': 'bool' }, 500 'if': 'CONFIG_VNC' } 501 502## 503# @VncServerInfo: 504# 505# The network connection information for server 506# 507# @auth: authentication method used for 508# the plain (non-websocket) VNC server 509# 510# Since: 2.1 511## 512{ 'struct': 'VncServerInfo', 513 'base': 'VncBasicInfo', 514 'data': { '*auth': 'str' }, 515 'if': 'CONFIG_VNC' } 516 517## 518# @VncClientInfo: 519# 520# Information about a connected VNC client. 521# 522# @x509_dname: If x509 authentication is in use, the Distinguished 523# Name of the client. 524# 525# @sasl_username: If SASL authentication is in use, the SASL username 526# used for authentication. 527# 528# Since: 0.14 529## 530{ 'struct': 'VncClientInfo', 531 'base': 'VncBasicInfo', 532 'data': { '*x509_dname': 'str', '*sasl_username': 'str' }, 533 'if': 'CONFIG_VNC' } 534 535## 536# @VncInfo: 537# 538# Information about the VNC session. 539# 540# @enabled: true if the VNC server is enabled, false otherwise 541# 542# @host: The hostname the VNC server is bound to. This depends on 543# the name resolution on the host and may be an IP address. 544# 545# @family: - 'ipv6' if the host is listening for IPv6 connections 546# - 'ipv4' if the host is listening for IPv4 connections 547# - 'unix' if the host is listening on a unix domain socket 548# - 'unknown' otherwise 549# 550# @service: The service name of the server's port. This may depends 551# on the host system's service database so symbolic names should not 552# be relied on. 553# 554# @auth: the current authentication type used by the server 555# 556# - 'none' if no authentication is being used 557# - 'vnc' if VNC authentication is being used 558# - 'vencrypt+plain' if VEncrypt is used with plain text authentication 559# - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication 560# - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication 561# - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth 562# - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth 563# - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth 564# - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth 565# - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth 566# - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth 567# 568# @clients: a list of @VncClientInfo of all currently connected clients 569# 570# Since: 0.14 571## 572{ 'struct': 'VncInfo', 573 'data': {'enabled': 'bool', '*host': 'str', 574 '*family': 'NetworkAddressFamily', 575 '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']}, 576 'if': 'CONFIG_VNC' } 577 578## 579# @VncPrimaryAuth: 580# 581# vnc primary authentication method. 582# 583# Since: 2.3 584## 585{ 'enum': 'VncPrimaryAuth', 586 'data': [ 'none', 'vnc', 'ra2', 'ra2ne', 'tight', 'ultra', 587 'tls', 'vencrypt', 'sasl' ], 588 'if': 'CONFIG_VNC' } 589 590## 591# @VncVencryptSubAuth: 592# 593# vnc sub authentication method with vencrypt. 594# 595# Since: 2.3 596## 597{ 'enum': 'VncVencryptSubAuth', 598 'data': [ 'plain', 599 'tls-none', 'x509-none', 600 'tls-vnc', 'x509-vnc', 601 'tls-plain', 'x509-plain', 602 'tls-sasl', 'x509-sasl' ], 603 'if': 'CONFIG_VNC' } 604 605## 606# @VncServerInfo2: 607# 608# The network connection information for server 609# 610# @auth: The current authentication type used by the servers 611# 612# @vencrypt: The vencrypt sub authentication type used by the 613# servers, only specified in case auth == vencrypt. 614# 615# Since: 2.9 616## 617{ 'struct': 'VncServerInfo2', 618 'base': 'VncBasicInfo', 619 'data': { 'auth' : 'VncPrimaryAuth', 620 '*vencrypt' : 'VncVencryptSubAuth' }, 621 'if': 'CONFIG_VNC' } 622 623## 624# @VncInfo2: 625# 626# Information about a vnc server 627# 628# @id: vnc server name. 629# 630# @server: A list of @VncBasincInfo describing all listening sockets. 631# The list can be empty (in case the vnc server is disabled). 632# It also may have multiple entries: normal + websocket, 633# possibly also ipv4 + ipv6 in the future. 634# 635# @clients: A list of @VncClientInfo of all currently connected clients. 636# The list can be empty, for obvious reasons. 637# 638# @auth: The current authentication type used by the non-websockets servers 639# 640# @vencrypt: The vencrypt authentication type used by the servers, 641# only specified in case auth == vencrypt. 642# 643# @display: The display device the vnc server is linked to. 644# 645# Since: 2.3 646## 647{ 'struct': 'VncInfo2', 648 'data': { 'id' : 'str', 649 'server' : ['VncServerInfo2'], 650 'clients' : ['VncClientInfo'], 651 'auth' : 'VncPrimaryAuth', 652 '*vencrypt' : 'VncVencryptSubAuth', 653 '*display' : 'str' }, 654 'if': 'CONFIG_VNC' } 655 656## 657# @query-vnc: 658# 659# Returns information about the current VNC server 660# 661# Returns: @VncInfo 662# 663# Since: 0.14 664# 665# Example: 666# 667# -> { "execute": "query-vnc" } 668# <- { "return": { 669# "enabled":true, 670# "host":"0.0.0.0", 671# "service":"50402", 672# "auth":"vnc", 673# "family":"ipv4", 674# "clients":[ 675# { 676# "host":"127.0.0.1", 677# "service":"50401", 678# "family":"ipv4" 679# "websocket":false, 680# } 681# ] 682# } 683# } 684# 685## 686{ 'command': 'query-vnc', 'returns': 'VncInfo', 687 'if': 'CONFIG_VNC' } 688## 689# @query-vnc-servers: 690# 691# Returns a list of vnc servers. The list can be empty. 692# 693# Returns: a list of @VncInfo2 694# 695# Since: 2.3 696## 697{ 'command': 'query-vnc-servers', 'returns': ['VncInfo2'], 698 'if': 'CONFIG_VNC' } 699 700## 701# @change-vnc-password: 702# 703# Change the VNC server password. 704# 705# @password: the new password to use with VNC authentication 706# 707# Since: 1.1 708# 709# Notes: An empty password in this command will set the password to the empty 710# string. Existing clients are unaffected by executing this command. 711## 712{ 'command': 'change-vnc-password', 713 'data': { 'password': 'str' }, 714 'if': 'CONFIG_VNC' } 715 716## 717# @VNC_CONNECTED: 718# 719# Emitted when a VNC client establishes a connection 720# 721# @server: server information 722# 723# @client: client information 724# 725# Note: This event is emitted before any authentication takes place, thus 726# the authentication ID is not provided 727# 728# Since: 0.13 729# 730# Example: 731# 732# <- { "event": "VNC_CONNECTED", 733# "data": { 734# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, 735# "service": "5901", "host": "0.0.0.0" }, 736# "client": { "family": "ipv4", "service": "58425", 737# "host": "127.0.0.1", "websocket": false } }, 738# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } 739# 740## 741{ 'event': 'VNC_CONNECTED', 742 'data': { 'server': 'VncServerInfo', 743 'client': 'VncBasicInfo' }, 744 'if': 'CONFIG_VNC' } 745 746## 747# @VNC_INITIALIZED: 748# 749# Emitted after authentication takes place (if any) and the VNC session is 750# made active 751# 752# @server: server information 753# 754# @client: client information 755# 756# Since: 0.13 757# 758# Example: 759# 760# <- { "event": "VNC_INITIALIZED", 761# "data": { 762# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, 763# "service": "5901", "host": "0.0.0.0"}, 764# "client": { "family": "ipv4", "service": "46089", "websocket": false, 765# "host": "127.0.0.1", "sasl_username": "luiz" } }, 766# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } } 767# 768## 769{ 'event': 'VNC_INITIALIZED', 770 'data': { 'server': 'VncServerInfo', 771 'client': 'VncClientInfo' }, 772 'if': 'CONFIG_VNC' } 773 774## 775# @VNC_DISCONNECTED: 776# 777# Emitted when the connection is closed 778# 779# @server: server information 780# 781# @client: client information 782# 783# Since: 0.13 784# 785# Example: 786# 787# <- { "event": "VNC_DISCONNECTED", 788# "data": { 789# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, 790# "service": "5901", "host": "0.0.0.0" }, 791# "client": { "family": "ipv4", "service": "58425", "websocket": false, 792# "host": "127.0.0.1", "sasl_username": "luiz" } }, 793# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } 794# 795## 796{ 'event': 'VNC_DISCONNECTED', 797 'data': { 'server': 'VncServerInfo', 798 'client': 'VncClientInfo' }, 799 'if': 'CONFIG_VNC' } 800 801## 802# = Input 803## 804 805## 806# @MouseInfo: 807# 808# Information about a mouse device. 809# 810# @name: the name of the mouse device 811# 812# @index: the index of the mouse device 813# 814# @current: true if this device is currently receiving mouse events 815# 816# @absolute: true if this device supports absolute coordinates as input 817# 818# Since: 0.14 819## 820{ 'struct': 'MouseInfo', 821 'data': {'name': 'str', 'index': 'int', 'current': 'bool', 822 'absolute': 'bool'} } 823 824## 825# @query-mice: 826# 827# Returns information about each active mouse device 828# 829# Returns: a list of @MouseInfo for each device 830# 831# Since: 0.14 832# 833# Example: 834# 835# -> { "execute": "query-mice" } 836# <- { "return": [ 837# { 838# "name":"QEMU Microsoft Mouse", 839# "index":0, 840# "current":false, 841# "absolute":false 842# }, 843# { 844# "name":"QEMU PS/2 Mouse", 845# "index":1, 846# "current":true, 847# "absolute":true 848# } 849# ] 850# } 851# 852## 853{ 'command': 'query-mice', 'returns': ['MouseInfo'] } 854 855## 856# @QKeyCode: 857# 858# An enumeration of key name. 859# 860# This is used by the @send-key command. 861# 862# @unmapped: since 2.0 863# @pause: since 2.0 864# @ro: since 2.4 865# @kp_comma: since 2.4 866# @kp_equals: since 2.6 867# @power: since 2.6 868# @hiragana: since 2.9 869# @henkan: since 2.9 870# @yen: since 2.9 871# 872# @sleep: since 2.10 873# @wake: since 2.10 874# @audionext: since 2.10 875# @audioprev: since 2.10 876# @audiostop: since 2.10 877# @audioplay: since 2.10 878# @audiomute: since 2.10 879# @volumeup: since 2.10 880# @volumedown: since 2.10 881# @mediaselect: since 2.10 882# @mail: since 2.10 883# @calculator: since 2.10 884# @computer: since 2.10 885# @ac_home: since 2.10 886# @ac_back: since 2.10 887# @ac_forward: since 2.10 888# @ac_refresh: since 2.10 889# @ac_bookmarks: since 2.10 890# 891# @muhenkan: since 2.12 892# @katakanahiragana: since 2.12 893# 894# @lang1: since 6.1 895# @lang2: since 6.1 896# 897# 'sysrq' was mistakenly added to hack around the fact that 898# the ps2 driver was not generating correct scancodes sequences 899# when 'alt+print' was pressed. This flaw is now fixed and the 900# 'sysrq' key serves no further purpose. Any further use of 901# 'sysrq' will be transparently changed to 'print', so they 902# are effectively synonyms. 903# 904# Since: 1.3 905# 906## 907{ 'enum': 'QKeyCode', 908 'data': [ 'unmapped', 909 'shift', 'shift_r', 'alt', 'alt_r', 'ctrl', 910 'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8', 911 '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e', 912 'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right', 913 'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon', 914 'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b', 915 'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock', 916 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 917 'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply', 918 'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0', 919 'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8', 920 'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end', 921 'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again', 922 'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut', 923 'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause', 924 'ro', 'hiragana', 'henkan', 'yen', 'muhenkan', 'katakanahiragana', 925 'kp_comma', 'kp_equals', 'power', 'sleep', 'wake', 926 'audionext', 'audioprev', 'audiostop', 'audioplay', 'audiomute', 927 'volumeup', 'volumedown', 'mediaselect', 928 'mail', 'calculator', 'computer', 929 'ac_home', 'ac_back', 'ac_forward', 'ac_refresh', 'ac_bookmarks', 930 'lang1', 'lang2' ] } 931 932## 933# @KeyValueKind: 934# 935# Since: 1.3 936## 937{ 'enum': 'KeyValueKind', 938 'data': [ 'number', 'qcode' ] } 939 940## 941# @IntWrapper: 942# 943# Since: 1.3 944## 945{ 'struct': 'IntWrapper', 946 'data': { 'data': 'int' } } 947 948## 949# @QKeyCodeWrapper: 950# 951# Since: 1.3 952## 953{ 'struct': 'QKeyCodeWrapper', 954 'data': { 'data': 'QKeyCode' } } 955 956## 957# @KeyValue: 958# 959# Represents a keyboard key. 960# 961# Since: 1.3 962## 963{ 'union': 'KeyValue', 964 'base': { 'type': 'KeyValueKind' }, 965 'discriminator': 'type', 966 'data': { 967 'number': 'IntWrapper', 968 'qcode': 'QKeyCodeWrapper' } } 969 970## 971# @send-key: 972# 973# Send keys to guest. 974# 975# @keys: An array of @KeyValue elements. All @KeyValues in this array are 976# simultaneously sent to the guest. A @KeyValue.number value is sent 977# directly to the guest, while @KeyValue.qcode must be a valid 978# @QKeyCode value 979# 980# @hold-time: time to delay key up events, milliseconds. Defaults 981# to 100 982# 983# Returns: - Nothing on success 984# - If key is unknown or redundant, InvalidParameter 985# 986# Since: 1.3 987# 988# Example: 989# 990# -> { "execute": "send-key", 991# "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, 992# { "type": "qcode", "data": "alt" }, 993# { "type": "qcode", "data": "delete" } ] } } 994# <- { "return": {} } 995# 996## 997{ 'command': 'send-key', 998 'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } } 999 1000## 1001# @InputButton: 1002# 1003# Button of a pointer input device (mouse, tablet). 1004# 1005# @side: front side button of a 5-button mouse (since 2.9) 1006# 1007# @extra: rear side button of a 5-button mouse (since 2.9) 1008# 1009# Since: 2.0 1010## 1011{ 'enum' : 'InputButton', 1012 'data' : [ 'left', 'middle', 'right', 'wheel-up', 'wheel-down', 'side', 1013 'extra', 'wheel-left', 'wheel-right' ] } 1014 1015## 1016# @InputAxis: 1017# 1018# Position axis of a pointer input device (mouse, tablet). 1019# 1020# Since: 2.0 1021## 1022{ 'enum' : 'InputAxis', 1023 'data' : [ 'x', 'y' ] } 1024 1025## 1026# @InputKeyEvent: 1027# 1028# Keyboard input event. 1029# 1030# @key: Which key this event is for. 1031# @down: True for key-down and false for key-up events. 1032# 1033# Since: 2.0 1034## 1035{ 'struct' : 'InputKeyEvent', 1036 'data' : { 'key' : 'KeyValue', 1037 'down' : 'bool' } } 1038 1039## 1040# @InputBtnEvent: 1041# 1042# Pointer button input event. 1043# 1044# @button: Which button this event is for. 1045# @down: True for key-down and false for key-up events. 1046# 1047# Since: 2.0 1048## 1049{ 'struct' : 'InputBtnEvent', 1050 'data' : { 'button' : 'InputButton', 1051 'down' : 'bool' } } 1052 1053## 1054# @InputMoveEvent: 1055# 1056# Pointer motion input event. 1057# 1058# @axis: Which axis is referenced by @value. 1059# @value: Pointer position. For absolute coordinates the 1060# valid range is 0 -> 0x7ffff 1061# 1062# Since: 2.0 1063## 1064{ 'struct' : 'InputMoveEvent', 1065 'data' : { 'axis' : 'InputAxis', 1066 'value' : 'int' } } 1067 1068## 1069# @InputEventKind: 1070# 1071# Since: 2.0 1072## 1073{ 'enum': 'InputEventKind', 1074 'data': [ 'key', 'btn', 'rel', 'abs' ] } 1075 1076## 1077# @InputKeyEventWrapper: 1078# 1079# Since: 2.0 1080## 1081{ 'struct': 'InputKeyEventWrapper', 1082 'data': { 'data': 'InputKeyEvent' } } 1083 1084## 1085# @InputBtnEventWrapper: 1086# 1087# Since: 2.0 1088## 1089{ 'struct': 'InputBtnEventWrapper', 1090 'data': { 'data': 'InputBtnEvent' } } 1091 1092## 1093# @InputMoveEventWrapper: 1094# 1095# Since: 2.0 1096## 1097{ 'struct': 'InputMoveEventWrapper', 1098 'data': { 'data': 'InputMoveEvent' } } 1099 1100## 1101# @InputEvent: 1102# 1103# Input event union. 1104# 1105# @type: the input type, one of: 1106# 1107# - 'key': Input event of Keyboard 1108# - 'btn': Input event of pointer buttons 1109# - 'rel': Input event of relative pointer motion 1110# - 'abs': Input event of absolute pointer motion 1111# 1112# Since: 2.0 1113## 1114{ 'union' : 'InputEvent', 1115 'base': { 'type': 'InputEventKind' }, 1116 'discriminator': 'type', 1117 'data' : { 'key' : 'InputKeyEventWrapper', 1118 'btn' : 'InputBtnEventWrapper', 1119 'rel' : 'InputMoveEventWrapper', 1120 'abs' : 'InputMoveEventWrapper' } } 1121 1122## 1123# @input-send-event: 1124# 1125# Send input event(s) to guest. 1126# 1127# The @device and @head parameters can be used to send the input event 1128# to specific input devices in case (a) multiple input devices of the 1129# same kind are added to the virtual machine and (b) you have 1130# configured input routing (see docs/multiseat.txt) for those input 1131# devices. The parameters work exactly like the device and head 1132# properties of input devices. If @device is missing, only devices 1133# that have no input routing config are admissible. If @device is 1134# specified, both input devices with and without input routing config 1135# are admissible, but devices with input routing config take 1136# precedence. 1137# 1138# @device: display device to send event(s) to. 1139# @head: head to send event(s) to, in case the 1140# display device supports multiple scanouts. 1141# @events: List of InputEvent union. 1142# 1143# Returns: Nothing on success. 1144# 1145# Since: 2.6 1146# 1147# Note: The consoles are visible in the qom tree, under 1148# /backend/console[$index]. They have a device link and head property, 1149# so it is possible to map which console belongs to which device and 1150# display. 1151# 1152# Example: 1153# 1154# 1. Press left mouse button. 1155# 1156# -> { "execute": "input-send-event", 1157# "arguments": { "device": "video0", 1158# "events": [ { "type": "btn", 1159# "data" : { "down": true, "button": "left" } } ] } } 1160# <- { "return": {} } 1161# 1162# -> { "execute": "input-send-event", 1163# "arguments": { "device": "video0", 1164# "events": [ { "type": "btn", 1165# "data" : { "down": false, "button": "left" } } ] } } 1166# <- { "return": {} } 1167# 1168# 2. Press ctrl-alt-del. 1169# 1170# -> { "execute": "input-send-event", 1171# "arguments": { "events": [ 1172# { "type": "key", "data" : { "down": true, 1173# "key": {"type": "qcode", "data": "ctrl" } } }, 1174# { "type": "key", "data" : { "down": true, 1175# "key": {"type": "qcode", "data": "alt" } } }, 1176# { "type": "key", "data" : { "down": true, 1177# "key": {"type": "qcode", "data": "delete" } } } ] } } 1178# <- { "return": {} } 1179# 1180# 3. Move mouse pointer to absolute coordinates (20000, 400). 1181# 1182# -> { "execute": "input-send-event" , 1183# "arguments": { "events": [ 1184# { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, 1185# { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } 1186# <- { "return": {} } 1187# 1188## 1189{ 'command': 'input-send-event', 1190 'data': { '*device': 'str', 1191 '*head' : 'int', 1192 'events' : [ 'InputEvent' ] } } 1193 1194## 1195# @DisplayGTK: 1196# 1197# GTK display options. 1198# 1199# @grab-on-hover: Grab keyboard input on mouse hover. 1200# @zoom-to-fit: Zoom guest display to fit into the host window. When 1201# turned off the host window will be resized instead. 1202# In case the display device can notify the guest on 1203# window resizes (virtio-gpu) this will default to "on", 1204# assuming the guest will resize the display to match 1205# the window size then. Otherwise it defaults to "off". 1206# Since 3.1 1207# 1208# Since: 2.12 1209# 1210## 1211{ 'struct' : 'DisplayGTK', 1212 'data' : { '*grab-on-hover' : 'bool', 1213 '*zoom-to-fit' : 'bool' } } 1214 1215## 1216# @DisplayEGLHeadless: 1217# 1218# EGL headless display options. 1219# 1220# @rendernode: Which DRM render node should be used. Default is the first 1221# available node on the host. 1222# 1223# Since: 3.1 1224# 1225## 1226{ 'struct' : 'DisplayEGLHeadless', 1227 'data' : { '*rendernode' : 'str' } } 1228 1229## 1230# @DisplayDBus: 1231# 1232# DBus display options. 1233# 1234# @addr: The D-Bus bus address (default to the session bus). 1235# 1236# @rendernode: Which DRM render node should be used. Default is the first 1237# available node on the host. 1238# 1239# @p2p: Whether to use peer-to-peer connections (accepted through 1240# ``add_client``). 1241# 1242# @audiodev: Use the specified DBus audiodev to export audio. 1243# 1244# Since: 7.0 1245# 1246## 1247{ 'struct' : 'DisplayDBus', 1248 'data' : { '*rendernode' : 'str', 1249 '*addr': 'str', 1250 '*p2p': 'bool', 1251 '*audiodev': 'str' } } 1252 1253 ## 1254 # @DisplayGLMode: 1255 # 1256 # Display OpenGL mode. 1257 # 1258 # @off: Disable OpenGL (default). 1259 # @on: Use OpenGL, pick context type automatically. 1260 # Would better be named 'auto' but is called 'on' for backward 1261 # compatibility with bool type. 1262 # @core: Use OpenGL with Core (desktop) Context. 1263 # @es: Use OpenGL with ES (embedded systems) Context. 1264 # 1265 # Since: 3.0 1266 # 1267 ## 1268{ 'enum' : 'DisplayGLMode', 1269 'data' : [ 'off', 'on', 'core', 'es' ] } 1270 1271## 1272# @DisplayCurses: 1273# 1274# Curses display options. 1275# 1276# @charset: Font charset used by guest (default: CP437). 1277# 1278# Since: 4.0 1279# 1280## 1281{ 'struct' : 'DisplayCurses', 1282 'data' : { '*charset' : 'str' } } 1283 1284## 1285# @DisplayCocoa: 1286# 1287# Cocoa display options. 1288# 1289# @left-command-key: Enable/disable forwarding of left command key to 1290# guest. Allows command-tab window switching on the 1291# host without sending this key to the guest when 1292# "off". Defaults to "on" 1293# 1294# @full-grab: Capture all key presses, including system combos. This 1295# requires accessibility permissions, since it performs 1296# a global grab on key events. (default: off) 1297# See https://support.apple.com/en-in/guide/mac-help/mh32356/mac 1298# 1299# @swap-opt-cmd: Swap the Option and Command keys so that their key codes match 1300# their position on non-Mac keyboards and you can use Meta/Super 1301# and Alt where you expect them. (default: off) 1302# 1303# Since: 7.0 1304## 1305{ 'struct': 'DisplayCocoa', 1306 'data': { 1307 '*left-command-key': 'bool', 1308 '*full-grab': 'bool', 1309 '*swap-opt-cmd': 'bool' 1310 } } 1311 1312## 1313# @DisplayType: 1314# 1315# Display (user interface) type. 1316# 1317# @default: The default user interface, selecting from the first available 1318# of gtk, sdl, cocoa, and vnc. 1319# 1320# @none: No user interface or video output display. The guest will 1321# still see an emulated graphics card, but its output will not 1322# be displayed to the QEMU user. 1323# 1324# @gtk: The GTK user interface. 1325# 1326# @sdl: The SDL user interface. 1327# 1328# @egl-headless: No user interface, offload GL operations to a local 1329# DRI device. Graphical display need to be paired with 1330# VNC or Spice. (Since 3.1) 1331# 1332# @curses: Display video output via curses. For graphics device 1333# models which support a text mode, QEMU can display this 1334# output using a curses/ncurses interface. Nothing is 1335# displayed when the graphics device is in graphical mode or 1336# if the graphics device does not support a text 1337# mode. Generally only the VGA device models support text 1338# mode. 1339# 1340# @cocoa: The Cocoa user interface. 1341# 1342# @spice-app: Set up a Spice server and run the default associated 1343# application to connect to it. The server will redirect 1344# the serial console and QEMU monitors. (Since 4.0) 1345# 1346# @dbus: Start a D-Bus service for the display. (Since 7.0) 1347# 1348# Since: 2.12 1349# 1350## 1351{ 'enum' : 'DisplayType', 1352 'data' : [ 1353 { 'name': 'default' }, 1354 { 'name': 'none' }, 1355 { 'name': 'gtk', 'if': 'CONFIG_GTK' }, 1356 { 'name': 'sdl', 'if': 'CONFIG_SDL' }, 1357 { 'name': 'egl-headless', 1358 'if': { 'all': ['CONFIG_OPENGL', 'CONFIG_GBM'] } }, 1359 { 'name': 'curses', 'if': 'CONFIG_CURSES' }, 1360 { 'name': 'cocoa', 'if': 'CONFIG_COCOA' }, 1361 { 'name': 'spice-app', 'if': 'CONFIG_SPICE' }, 1362 { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' } 1363 ] 1364} 1365 1366## 1367# @DisplayOptions: 1368# 1369# Display (user interface) options. 1370# 1371# @type: Which DisplayType qemu should use. 1372# @full-screen: Start user interface in fullscreen mode (default: off). 1373# @window-close: Allow to quit qemu with window close button (default: on). 1374# @show-cursor: Force showing the mouse cursor (default: off). 1375# (since: 5.0) 1376# @gl: Enable OpenGL support (default: off). 1377# 1378# Since: 2.12 1379# 1380## 1381{ 'union' : 'DisplayOptions', 1382 'base' : { 'type' : 'DisplayType', 1383 '*full-screen' : 'bool', 1384 '*window-close' : 'bool', 1385 '*show-cursor' : 'bool', 1386 '*gl' : 'DisplayGLMode' }, 1387 'discriminator' : 'type', 1388 'data' : { 1389 'gtk': { 'type': 'DisplayGTK', 'if': 'CONFIG_GTK' }, 1390 'cocoa': { 'type': 'DisplayCocoa', 'if': 'CONFIG_COCOA' }, 1391 'curses': { 'type': 'DisplayCurses', 'if': 'CONFIG_CURSES' }, 1392 'egl-headless': { 'type': 'DisplayEGLHeadless', 1393 'if': { 'all': ['CONFIG_OPENGL', 'CONFIG_GBM'] } }, 1394 'dbus': { 'type': 'DisplayDBus', 'if': 'CONFIG_DBUS_DISPLAY' } 1395 } 1396} 1397 1398## 1399# @query-display-options: 1400# 1401# Returns information about display configuration 1402# 1403# Returns: @DisplayOptions 1404# 1405# Since: 3.1 1406# 1407## 1408{ 'command': 'query-display-options', 1409 'returns': 'DisplayOptions' } 1410 1411## 1412# @DisplayReloadType: 1413# 1414# Available DisplayReload types. 1415# 1416# @vnc: VNC display 1417# 1418# Since: 6.0 1419# 1420## 1421{ 'enum': 'DisplayReloadType', 1422 'data': ['vnc'] } 1423 1424## 1425# @DisplayReloadOptionsVNC: 1426# 1427# Specify the VNC reload options. 1428# 1429# @tls-certs: reload tls certs or not. 1430# 1431# Since: 6.0 1432# 1433## 1434{ 'struct': 'DisplayReloadOptionsVNC', 1435 'data': { '*tls-certs': 'bool' } } 1436 1437## 1438# @DisplayReloadOptions: 1439# 1440# Options of the display configuration reload. 1441# 1442# @type: Specify the display type. 1443# 1444# Since: 6.0 1445# 1446## 1447{ 'union': 'DisplayReloadOptions', 1448 'base': {'type': 'DisplayReloadType'}, 1449 'discriminator': 'type', 1450 'data': { 'vnc': 'DisplayReloadOptionsVNC' } } 1451 1452## 1453# @display-reload: 1454# 1455# Reload display configuration. 1456# 1457# Returns: Nothing on success. 1458# 1459# Since: 6.0 1460# 1461# Example: 1462# 1463# -> { "execute": "display-reload", 1464# "arguments": { "type": "vnc", "tls-certs": true } } 1465# <- { "return": {} } 1466# 1467## 1468{ 'command': 'display-reload', 1469 'data': 'DisplayReloadOptions', 1470 'boxed' : true } 1471 1472## 1473# @DisplayUpdateType: 1474# 1475# Available DisplayUpdate types. 1476# 1477# @vnc: VNC display 1478# 1479# Since: 7.1 1480# 1481## 1482{ 'enum': 'DisplayUpdateType', 1483 'data': ['vnc'] } 1484 1485## 1486# @DisplayUpdateOptionsVNC: 1487# 1488# Specify the VNC reload options. 1489# 1490# @addresses: If specified, change set of addresses 1491# to listen for connections. Addresses configured 1492# for websockets are not touched. 1493# 1494# Since: 7.1 1495# 1496## 1497{ 'struct': 'DisplayUpdateOptionsVNC', 1498 'data': { '*addresses': ['SocketAddress'] } } 1499 1500## 1501# @DisplayUpdateOptions: 1502# 1503# Options of the display configuration reload. 1504# 1505# @type: Specify the display type. 1506# 1507# Since: 7.1 1508# 1509## 1510{ 'union': 'DisplayUpdateOptions', 1511 'base': {'type': 'DisplayUpdateType'}, 1512 'discriminator': 'type', 1513 'data': { 'vnc': 'DisplayUpdateOptionsVNC' } } 1514 1515## 1516# @display-update: 1517# 1518# Update display configuration. 1519# 1520# Returns: Nothing on success. 1521# 1522# Since: 7.1 1523# 1524# Example: 1525# 1526# -> { "execute": "display-update", 1527# "arguments": { "type": "vnc", "addresses": 1528# [ { "type": "inet", "host": "0.0.0.0", 1529# "port": "5901" } ] } } 1530# <- { "return": {} } 1531# 1532## 1533{ 'command': 'display-update', 1534 'data': 'DisplayUpdateOptions', 1535 'boxed' : true } 1536