dbus-display1.xml (21910B)
1 <?xml version="1.0" encoding="utf-8"?> 2 <node> 3 <!-- 4 org.qemu.Display1.VM: 5 6 This interface is implemented on ``/org/qemu/Display1/VM``. 7 --> 8 <interface name="org.qemu.Display1.VM"> 9 <!-- 10 Name: 11 12 The name of the VM. 13 --> 14 <property name="Name" type="s" access="read"/> 15 16 <!-- 17 UUID: 18 19 The UUID of the VM. 20 --> 21 <property name="UUID" type="s" access="read"/> 22 23 <!-- 24 ConsoleIDs: 25 26 The list of consoles available on ``/org/qemu/Display1/Console_$id``. 27 --> 28 <property name="ConsoleIDs" type="au" access="read"/> 29 </interface> 30 31 <!-- 32 org.qemu.Display1.Console: 33 34 This interface is implemented on ``/org/qemu/Display1/Console_$id``. You 35 may discover available consoles through introspection or with the 36 :dbus:prop:`org.qemu.Display1.VM.ConsoleIDs` property. 37 38 A console is attached to a video device head. It may be "Graphic" or 39 "Text" (see :dbus:prop:`Type` and other properties). 40 41 Interactions with a console may be done with 42 :dbus:iface:`org.qemu.Display1.Keyboard` and 43 :dbus:iface:`org.qemu.Display1.Mouse` interfaces when available. 44 --> 45 <interface name="org.qemu.Display1.Console"> 46 <!-- 47 RegisterListener: 48 @listener: a Unix socket FD, for peer-to-peer D-Bus communication. 49 50 Register a console listener, which will receive display updates, until 51 it is disconnected. 52 53 Multiple listeners may be registered simultaneously. 54 55 The listener is expected to implement the 56 :dbus:iface:`org.qemu.Display1.Listener` interface. 57 --> 58 <method name="RegisterListener"> 59 <arg type="h" name="listener" direction="in"/> 60 </method> 61 62 <!-- 63 SetUIInfo: 64 @width_mm: the physical display width in millimeters. 65 @height_mm: the physical display height in millimeters. 66 @xoff: horizontal offset, in pixels. 67 @yoff: vertical offset, in pixels. 68 @width: console width, in pixels. 69 @height: console height, in pixels. 70 71 Modify the dimensions and display settings. 72 --> 73 <method name="SetUIInfo"> 74 <arg name="width_mm" type="q" direction="in"/> 75 <arg name="height_mm" type="q" direction="in"/> 76 <arg name="xoff" type="i" direction="in"/> 77 <arg name="yoff" type="i" direction="in"/> 78 <arg name="width" type="u" direction="in"/> 79 <arg name="height" type="u" direction="in"/> 80 </method> 81 82 <!-- 83 Label: 84 85 A user-friendly name for the console (for ex: "VGA"). 86 --> 87 <property name="Label" type="s" access="read"/> 88 89 <!-- 90 Head: 91 92 Graphical device head number. 93 --> 94 <property name="Head" type="u" access="read"/> 95 96 <!-- 97 Type: 98 99 Console type ("Graphic" or "Text"). 100 --> 101 <property name="Type" type="s" access="read"/> 102 103 <!-- 104 Width: 105 106 Console width, in pixels. 107 --> 108 <property name="Width" type="u" access="read"/> 109 110 <!-- 111 Height: 112 113 Console height, in pixels. 114 --> 115 <property name="Height" type="u" access="read"/> 116 117 <!-- 118 DeviceAddress: 119 120 The device address (ex: "pci/0000/02.0"). 121 --> 122 <property name="DeviceAddress" type="s" access="read"/> 123 </interface> 124 125 <!-- 126 org.qemu.Display1.Keyboard: 127 128 This interface in implemented on ``/org/qemu/Display1/Console_$id`` (see 129 :dbus:iface:`~org.qemu.Display1.Console`). 130 --> 131 <interface name="org.qemu.Display1.Keyboard"> 132 <!-- 133 Press: 134 @keycode: QEMU key number (xtkbd + special re-encoding of high bit) 135 136 Send a key press event. 137 --> 138 <method name="Press"> 139 <arg type="u" name="keycode" direction="in"/> 140 </method> 141 142 <!-- 143 Release: 144 @keycode: QEMU key number (xtkbd + special re-encoding of high bit) 145 146 Send a key release event. 147 --> 148 <method name="Release"> 149 <arg type="u" name="keycode" direction="in"/> 150 </method> 151 152 <!-- 153 Modifiers: 154 155 The active keyboard modifiers:: 156 157 Scroll = 1 << 0 158 Num = 1 << 1 159 Caps = 1 << 2 160 --> 161 <property name="Modifiers" type="u" access="read"/> 162 </interface> 163 164 <!-- 165 org.qemu.Display1.Mouse: 166 167 This interface in implemented on ``/org/qemu/Display1/Console_$id`` (see 168 :dbus:iface:`~org.qemu.Display1.Console` documentation). 169 170 .. _dbus-button-values: 171 172 **Button values**:: 173 174 Left = 0 175 Middle = 1 176 Right = 2 177 Wheel-up = 3 178 Wheel-down = 4 179 Side = 5 180 Extra = 6 181 --> 182 <interface name="org.qemu.Display1.Mouse"> 183 <!-- 184 Press: 185 @button: :ref:`button value<dbus-button-values>`. 186 187 Send a mouse button press event. 188 --> 189 <method name="Press"> 190 <arg type="u" name="button" direction="in"/> 191 </method> 192 193 <!-- 194 Release: 195 @button: :ref:`button value<dbus-button-values>`. 196 197 Send a mouse button release event. 198 --> 199 <method name="Release"> 200 <arg type="u" name="button" direction="in"/> 201 </method> 202 203 <!-- 204 SetAbsPosition: 205 @x: X position, in pixels. 206 @y: Y position, in pixels. 207 208 Set the mouse pointer position. 209 210 Returns an error if not :dbus:prop:`IsAbsolute`. 211 --> 212 <method name="SetAbsPosition"> 213 <arg type="u" name="x" direction="in"/> 214 <arg type="u" name="y" direction="in"/> 215 </method> 216 217 <!-- 218 RelMotion: 219 @dx: X-delta, in pixels. 220 @dy: Y-delta, in pixels. 221 222 Move the mouse pointer position, relative to the current position. 223 224 Returns an error if :dbus:prop:`IsAbsolute`. 225 --> 226 <method name="RelMotion"> 227 <arg type="i" name="dx" direction="in"/> 228 <arg type="i" name="dy" direction="in"/> 229 </method> 230 231 <!-- 232 IsAbsolute: 233 234 Whether the mouse is using absolute movements. 235 --> 236 <property name="IsAbsolute" type="b" access="read"/> 237 </interface> 238 239 <!-- 240 org.qemu.Display1.Listener: 241 242 This client-side interface must be available on 243 ``/org/qemu/Display1/Listener`` when registering the peer-to-peer 244 connection with :dbus:meth:`~org.qemu.Display1.Console.Register`. 245 --> 246 <interface name="org.qemu.Display1.Listener"> 247 <!-- 248 Scanout: 249 @width: display width, in pixels. 250 @height: display height, in pixels. 251 @stride: data stride, in bytes. 252 @pixman_format: image format (ex: ``PIXMAN_X8R8G8B8``). 253 @data: image data. 254 255 Resize and update the display content. 256 257 The data to transfer for the display update may be large. The preferred 258 scanout method is :dbus:meth:`ScanoutDMABUF`, used whenever possible. 259 --> 260 <method name="Scanout"> 261 <arg type="u" name="width" direction="in"/> 262 <arg type="u" name="height" direction="in"/> 263 <arg type="u" name="stride" direction="in"/> 264 <arg type="u" name="pixman_format" direction="in"/> 265 <arg type="ay" name="data" direction="in"> 266 <annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/> 267 </arg> 268 </method> 269 270 <!-- 271 Update: 272 @x: X update position, in pixels. 273 @y: Y update position, in pixels. 274 @width: update width, in pixels. 275 @height: update height, in pixels. 276 @stride: data stride, in bytes. 277 @pixman_format: image format (ex: ``PIXMAN_X8R8G8B8``). 278 @data: display image data. 279 280 Update the display content. 281 282 This method is only called after a :dbus:meth:`Scanout` call. 283 --> 284 <method name="Update"> 285 <arg type="i" name="x" direction="in"/> 286 <arg type="i" name="y" direction="in"/> 287 <arg type="i" name="width" direction="in"/> 288 <arg type="i" name="height" direction="in"/> 289 <arg type="u" name="stride" direction="in"/> 290 <arg type="u" name="pixman_format" direction="in"/> 291 <arg type="ay" name="data" direction="in"> 292 <annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/> 293 </arg> 294 </method> 295 296 <!-- 297 ScanoutDMABUF: 298 @dmabuf: the DMABUF file descriptor. 299 @width: display width, in pixels. 300 @height: display height, in pixels. 301 @stride: stride, in bytes. 302 @fourcc: DMABUF fourcc. 303 @modifier: DMABUF modifier. 304 @y0_top: whether Y position 0 is the top or not. 305 306 Resize and update the display content with a DMABUF. 307 --> 308 <method name="ScanoutDMABUF"> 309 <arg type="h" name="dmabuf" direction="in"/> 310 <arg type="u" name="width" direction="in"/> 311 <arg type="u" name="height" direction="in"/> 312 <arg type="u" name="stride" direction="in"/> 313 <arg type="u" name="fourcc" direction="in"/> 314 <!-- xywh? --> 315 <arg type="t" name="modifier" direction="in"/> 316 <arg type="b" name="y0_top" direction="in"/> 317 </method> 318 319 <!-- 320 UpdateDMABUF: 321 @x: the X update position, in pixels. 322 @y: the Y update position, in pixels. 323 @width: the update width, in pixels. 324 @height: the update height, in pixels. 325 326 Update the display content with the current DMABUF and the given region. 327 --> 328 <method name="UpdateDMABUF"> 329 <arg type="i" name="x" direction="in"/> 330 <arg type="i" name="y" direction="in"/> 331 <arg type="i" name="width" direction="in"/> 332 <arg type="i" name="height" direction="in"/> 333 </method> 334 335 <!-- 336 Disable: 337 338 Disable the display (turn it off). 339 --> 340 <method name="Disable"> 341 </method> 342 343 <!-- 344 MouseSet: 345 @x: X mouse position, in pixels. 346 @y: Y mouse position, in pixels. 347 @on: whether the mouse is visible or not. 348 349 Set the mouse position and visibility. 350 --> 351 <method name="MouseSet"> 352 <arg type="i" name="x" direction="in"/> 353 <arg type="i" name="y" direction="in"/> 354 <arg type="i" name="on" direction="in"/> 355 </method> 356 357 <!-- 358 CursorDefine: 359 @width: cursor width, in pixels. 360 @height: cursor height, in pixels. 361 @hot_x: hot-spot X position, in pixels. 362 @hot_y: hot-spot Y position, in pixels. 363 @data: the cursor data. 364 365 Set the mouse cursor shape and hot-spot. The "data" must be ARGB, 32-bit 366 per pixel. 367 --> 368 <method name="CursorDefine"> 369 <arg type="i" name="width" direction="in"/> 370 <arg type="i" name="height" direction="in"/> 371 <arg type="i" name="hot_x" direction="in"/> 372 <arg type="i" name="hot_y" direction="in"/> 373 <arg type="ay" name="data" direction="in"> 374 <annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/> 375 </arg> 376 </method> 377 </interface> 378 379 <!-- 380 org.qemu.Display1.Clipboard: 381 382 This interface must be implemented by both the client and the server on 383 ``/org/qemu/Display1/Clipboard`` to support clipboard sharing between 384 the client and the guest. 385 386 Once :dbus:meth:`Register`'ed, method calls may be sent and received in both 387 directions. Unregistered callers will get error replies. 388 389 .. _dbus-clipboard-selection: 390 391 **Selection values**:: 392 393 Clipboard = 0 394 Primary = 1 395 Secondary = 2 396 397 .. _dbus-clipboard-serial: 398 399 **Serial counter** 400 401 To solve potential clipboard races, clipboard grabs have an associated 402 serial counter. It is set to 0 on registration, and incremented by 1 for 403 each grab. The peer with the highest serial is the clipboard grab owner. 404 405 When a grab with a lower serial is received, it should be discarded. 406 407 When a grab is attempted with the same serial number as the current grab, 408 the one coming from the client should have higher priority, and the client 409 should gain clipboard grab ownership. 410 --> 411 <interface name="org.qemu.Display1.Clipboard"> 412 <!-- 413 Register: 414 415 Register a clipboard session and reinitialize the serial counter. 416 417 The client must register itself, and is granted an exclusive 418 access for handling the clipboard. 419 420 The server can reinitialize the session as well (to reset the counter). 421 --> 422 <method name="Register"/> 423 424 <!-- 425 Unregister: 426 427 Unregister the clipboard session. 428 --> 429 <method name="Unregister"/> 430 <!-- 431 Grab: 432 @selection: a :ref:`selection value<dbus-clipboard-selection>`. 433 @serial: the current grab :ref:`serial<dbus-clipboard-serial>`. 434 @mimes: the list of available content MIME types. 435 436 Grab the clipboard, claiming current clipboard content. 437 --> 438 <method name="Grab"> 439 <arg type="u" name="selection"/> 440 <arg type="u" name="serial"/> 441 <arg type="as" name="mimes"/> 442 </method> 443 444 <!-- 445 Release: 446 @selection: a :ref:`selection value<dbus-clipboard-selection>`. 447 448 Release the clipboard (does nothing if not the current owner). 449 --> 450 <method name="Release"> 451 <arg type="u" name="selection"/> 452 </method> 453 454 <!-- 455 Request: 456 @selection: a :ref:`selection value<dbus-clipboard-selection>` 457 @mimes: requested MIME types (by order of preference). 458 @reply_mime: the returned data MIME type. 459 @data: the clipboard data. 460 461 Request the clipboard content. 462 463 Return an error if the clipboard is empty, or the requested MIME types 464 are unavailable. 465 --> 466 <method name="Request"> 467 <arg type="u" name="selection"/> 468 <arg type="as" name="mimes"/> 469 <arg type="s" name="reply_mime" direction="out"/> 470 <arg type="ay" name="data" direction="out"> 471 <annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/> 472 </arg> 473 </method> 474 </interface> 475 476 <!-- 477 org.qemu.Display1.Audio: 478 479 Audio backend may be available on ``/org/qemu/Display1/Audio``. 480 --> 481 <interface name="org.qemu.Display1.Audio"> 482 <!-- 483 RegisterOutListener: 484 @listener: a Unix socket FD, for peer-to-peer D-Bus communication. 485 486 Register an audio backend playback handler. 487 488 Multiple listeners may be registered simultaneously. 489 490 The listener is expected to implement the 491 :dbus:iface:`org.qemu.Display1.AudioOutListener` interface. 492 --> 493 <method name="RegisterOutListener"> 494 <arg type="h" name="listener" direction="in"/> 495 </method> 496 497 <!-- 498 RegisterInListener: 499 @listener: a Unix socket FD, for peer-to-peer D-Bus communication. 500 501 Register an audio backend record handler. 502 503 Multiple listeners may be registered simultaneously. 504 505 The listener is expected to implement the 506 :dbus:iface:`org.qemu.Display1.AudioInListener` interface. 507 --> 508 <method name="RegisterInListener"> 509 <arg type="h" name="listener" direction="in"/> 510 </method> 511 </interface> 512 513 <!-- 514 org.qemu.Display1.AudioOutListener: 515 516 This client-side interface must be available on 517 ``/org/qemu/Display1/AudioOutListener`` when registering the peer-to-peer 518 connection with :dbus:meth:`~org.qemu.Display1.Audio.RegisterOutListener`. 519 --> 520 <interface name="org.qemu.Display1.AudioOutListener"> 521 <!-- 522 Init: 523 @id: the stream ID. 524 @bits: PCM bits per sample. 525 @is_signed: whether the PCM data is signed. 526 @is_float: PCM floating point format. 527 @freq: the PCM frequency in Hz. 528 @nchannels: the number of channels. 529 @bytes_per_frame: the bytes per frame. 530 @bytes_per_second: the bytes per second. 531 @be: whether using big-endian format. 532 533 Initializes a PCM playback stream. 534 --> 535 <method name="Init"> 536 <arg name="id" type="t" direction="in"/> 537 <arg name="bits" type="y" direction="in"/> 538 <arg name="is_signed" type="b" direction="in"/> 539 <arg name="is_float" type="b" direction="in"/> 540 <arg name="freq" type="u" direction="in"/> 541 <arg name="nchannels" type="y" direction="in"/> 542 <arg name="bytes_per_frame" type="u" direction="in"/> 543 <arg name="bytes_per_second" type="u" direction="in"/> 544 <arg name="be" type="b" direction="in"/> 545 </method> 546 547 <!-- 548 Fini: 549 @id: the stream ID. 550 551 Finish & close a playback stream. 552 --> 553 <method name="Fini"> 554 <arg name="id" type="t" direction="in"/> 555 </method> 556 557 <!-- 558 SetEnabled: 559 @id: the stream ID. 560 561 Resume or suspend the playback stream. 562 --> 563 <method name="SetEnabled"> 564 <arg name="id" type="t" direction="in"/> 565 <arg name="enabled" type="b" direction="in"/> 566 </method> 567 568 <!-- 569 SetVolume: 570 @id: the stream ID. 571 @mute: whether the stream is muted. 572 @volume: the volume per-channel. 573 574 Set the stream volume and mute state (volume without unit, 0-255). 575 --> 576 <method name="SetVolume"> 577 <arg name="id" type="t" direction="in"/> 578 <arg name="mute" type="b" direction="in"/> 579 <arg name="volume" type="ay" direction="in"> 580 <annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/> 581 </arg> 582 </method> 583 584 <!-- 585 Write: 586 @id: the stream ID. 587 @data: the PCM data. 588 589 PCM stream to play. 590 --> 591 <method name="Write"> 592 <arg name="id" type="t" direction="in"/> 593 <arg type="ay" name="data" direction="in"> 594 <annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/> 595 </arg> 596 </method> 597 </interface> 598 599 <!-- 600 org.qemu.Display1.AudioInListener: 601 602 This client-side interface must be available on 603 ``/org/qemu/Display1/AudioInListener`` when registering the peer-to-peer 604 connection with :dbus:meth:`~org.qemu.Display1.Audio.RegisterInListener`. 605 --> 606 <interface name="org.qemu.Display1.AudioInListener"> 607 <!-- 608 Init: 609 @id: the stream ID. 610 @bits: PCM bits per sample. 611 @is_signed: whether the PCM data is signed. 612 @is_float: PCM floating point format. 613 @freq: the PCM frequency in Hz. 614 @nchannels: the number of channels. 615 @bytes_per_frame: the bytes per frame. 616 @bytes_per_second: the bytes per second. 617 @be: whether using big-endian format. 618 619 Initializes a PCM record stream. 620 --> 621 <method name="Init"> 622 <arg name="id" type="t" direction="in"/> 623 <arg name="bits" type="y" direction="in"/> 624 <arg name="is_signed" type="b" direction="in"/> 625 <arg name="is_float" type="b" direction="in"/> 626 <arg name="freq" type="u" direction="in"/> 627 <arg name="nchannels" type="y" direction="in"/> 628 <arg name="bytes_per_frame" type="u" direction="in"/> 629 <arg name="bytes_per_second" type="u" direction="in"/> 630 <arg name="be" type="b" direction="in"/> 631 </method> 632 633 <!-- 634 Fini: 635 @id: the stream ID. 636 637 Finish & close a record stream. 638 --> 639 <method name="Fini"> 640 <arg name="id" type="t" direction="in"/> 641 </method> 642 643 <!-- 644 SetEnabled: 645 @id: the stream ID. 646 647 Resume or suspend the record stream. 648 --> 649 <method name="SetEnabled"> 650 <arg name="id" type="t" direction="in"/> 651 <arg name="enabled" type="b" direction="in"/> 652 </method> 653 654 <!-- 655 SetVolume: 656 @id: the stream ID. 657 @mute: whether the stream is muted. 658 @volume: the volume per-channel. 659 660 Set the stream volume and mute state (volume without unit, 0-255). 661 --> 662 <method name="SetVolume"> 663 <arg name="id" type="t" direction="in"/> 664 <arg name="mute" type="b" direction="in"/> 665 <arg name="volume" type="ay" direction="in"> 666 <annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/> 667 </arg> 668 </method> 669 670 <!-- 671 Read: 672 @id: the stream ID. 673 @size: the amount to read, in bytes. 674 @data: the recorded data (which may be less than requested). 675 676 Read "size" bytes from the record stream. 677 --> 678 <method name="Read"> 679 <arg name="id" type="t" direction="in"/> 680 <arg name="size" type="t" direction="in"/> 681 <arg type="ay" name="data" direction="out"> 682 <annotation name="org.gtk.GDBus.C.ForceGVariant" value="true"/> 683 </arg> 684 </method> 685 </interface> 686 687 <!-- 688 org.qemu.Display1.Chardev: 689 690 Character devices may be available on ``/org/qemu/Display1/Chardev_$id``. 691 692 They may be used for different kind of streams, which are identified via 693 their FQDN :dbus:prop:`Name`. 694 695 .. _dbus-chardev-fqdn: 696 697 Here are some known reserved kind names (the ``org.qemu`` prefix is 698 reserved by QEMU): 699 700 org.qemu.console.serial.0 701 A serial console stream. 702 703 org.qemu.monitor.hmp.0 704 A QEMU HMP human monitor. 705 706 org.qemu.monitor.qmp.0 707 A QEMU QMP monitor. 708 709 org.qemu.usbredir 710 A usbredir stream. 711 --> 712 <interface name="org.qemu.Display1.Chardev"> 713 <!-- 714 Register: 715 @stream: a Unix FD to redirect the stream to. 716 717 Register a file-descriptor for the stream handling. 718 719 The current handler, if any, will be replaced. 720 --> 721 <method name="Register"> 722 <arg type="h" name="stream" direction="in"/> 723 </method> 724 725 <!-- 726 SendBreak: 727 728 Send a break event to the character device. 729 --> 730 <method name="SendBreak"/> 731 732 <!-- 733 Name: 734 735 The FQDN name to identify the kind of stream. See :ref:`reserved 736 names<dbus-chardev-fqdn>`. 737 --> 738 <property name="Name" type="s" access="read"/> 739 740 <!-- 741 FEOpened: 742 743 Whether the front-end side is opened. 744 --> 745 <property name="FEOpened" type="b" access="read"/> 746 747 <!-- 748 Echo: 749 750 Whether the input should be echo'ed (for serial streams). 751 --> 752 <property name="Echo" type="b" access="read"/> 753 754 <!-- 755 Owner: 756 757 The D-Bus unique name of the registered handler. 758 --> 759 <property name="Owner" type="s" access="read"/> 760 </interface> 761 </node>