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