/usr/share/doc/cockpit/guide/cockpit-dbus.html is in cockpit-doc 164-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>cockpit.js: DBus Client</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Cockpit Guide">
<link rel="up" href="api-base1.html" title="API: base1">
<link rel="prev" href="api-cockpit.html" title="cockpit.js">
<link rel="next" href="cockpit-file.html" title="cockpit.js: File Access">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="api-cockpit.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="api-base1.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Cockpit Guide</th>
<td><a accesskey="n" href="cockpit-file.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="cockpit-dbus"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2>cockpit.js: DBus Client</h2>
<p>cockpit.js: DBus Client — DBus API communication</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<h2>Synopsis</h2>
<p>Cockpit allows access to DBus services via this API.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-types"></a><h2>DBus Types</h2>
<p>DBus values are represented as javascript values and objects as follows:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="code">BYTE 'y'</code></span></p></td>
<td><p>Javascript number.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">BOOLEAN 'b'</code></span></p></td>
<td><p>Javascript boolean.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">INT16 'n'</code></span></p></td>
<td><p>Javascript number.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">UINT16 'q'</code></span></p></td>
<td><p>Javascript number.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">INT32 'i'</code></span></p></td>
<td><p>Javascript number.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">UINT32 'u'</code></span></p></td>
<td><p>Javascript number.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">INT64 'x'</code></span></p></td>
<td><p>Javascript number.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">UINT64 't'</code></span></p></td>
<td><p>Javascript number.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">DOUBLE 'd'</code></span></p></td>
<td><p>Javascript number.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">STRING 's'</code></span></p></td>
<td><p>Javascript string.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">OBJECT_PATH 'o'</code></span></p></td>
<td><p>Javascript string.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">SIGNATURE 'g'</code></span></p></td>
<td><p>Javascript string.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">ARRAY of BYTE 'ay'</code></span></p></td>
<td><p>A string containing base64 encoded data.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">ARRAY of DICT_ENTRY with STRING keys 'a{s?}'</code></span></p></td>
<td><p>A javascript plain object with the keys as property names.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">ARRAY of DICT_ENTRY with other keys 'a{??}'</code></span></p></td>
<td><p>A javascript plain object each key JSON encoded into a string property
name.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">ARRAY of other</code></span></p></td>
<td><p>A javascript array.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">VARIANT</code></span></p></td>
<td><p>A javascript plain object with the <code class="code">"t"</code> property set to a DBus type string,
and the <code class="code">"v"</code> property set to a value.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">HANDLE 'h'</code></span></p></td>
<td><p>A javascript object that describes a cockpit channel which represents the
passed file descriptor. The <code class="code">payload</code> is always set to <code class="code">stream</code>.
Pass it to <a class="link" href="cockpit-channels.html#cockpit-channels-channel" title="cockpit.channel()">cockpit.channel()</a> to create
the channel and start reading or writing on it. Handles can only be
received, not sent from within cockpit.</p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsection">
<a name="cockpit-dbus-dbus"></a><h2>cockpit.dbus()</h2>
<pre class="programlisting">
client = cockpit.dbus(name, [options])
</pre>
<p>Create a DBus client for the given bus <code class="code">name</code> (eg: service name). Use the
following functions to make DBus method calls, watch for events, etc. The optional
<code class="code">options</code> argument is a javascript plain object, and may include:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="code">"bus"</code></span></p></td>
<td><p>The DBus bus to connect to. Specifying <code class="code">"session"</code> will
connect to the DBus user session bus, <code class="code">"user"</code> will connect to the
user bus (on some systems this is identical to the session bus), and <code class="code">"system"</code>
will connect to the DBus system bus. This defaults to "system" if not
present.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">"host"</code></span></p></td>
<td><p>The host to open the channel to. If an alternate user or port is
required it can be specified as <code class="code">"user@myhost:port"</code>. If no host is
specified then the correct one will be automatically selected based on the page
calling this function.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">"superuser"</code></span></p></td>
<td>
<p>Set to <code class="code">"require"</code> to talk to this service as root.
The DBus service will see the DBus method calls and accesses as coming from root,
rather than the logged in user. This is useful for talking to services that do not
correctly use <a class="ulink" href="http://www.freedesktop.org/software/polkit" target="_top">polkit</a>
to authorize administrative users. If the currently logged in user is not
permitted to become root (eg: via <code class="code">pkexec</code>) then the <code class="code">client</code> will
immediately be <a class="link" href="cockpit-dbus.html#cockpit-dbus-onclose" title="client.onclose">closed</a> with a
<code class="code">"access-denied"</code> problem code.</p>
<p>Set to <code class="code">"try"</code> to try to talk as root, but if that fails,
fall back to unprivileged.</p>
</td>
</tr>
<tr>
<td><p><span class="term"><code class="code">"track"</code></span></p></td>
<td><p>It is valid for a DBus service to exit, and be restarted in such a
way that clients continue to talk to it across the restart. Some services are not
written with this in mind. If the <code class="code">"track"</code> option is set to
<code class="code">true</code> then the channel will close when the service exits and/or disconnects
from the DBus bus.</p></td>
</tr>
</tbody>
</table></div>
<p>If the <code class="code">name</code> argument is null, and no options other than <code class="code">"bus"</code>
are specified, then a shared DBus <code class="code">client</code> is created. When using such a client
with a DBus bus, a <code class="code">"name"</code> option must be specified on various other methods
in order to specify which client to talk to.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-wait"></a><h2>client.wait()</h2>
<pre class="programlisting">
proxy = client.wait([callback])
</pre>
<p>Returns a <code class="code">promise</code> that is ready when the client is ready, or fails if the
client closes. If a <code class="code">callback</code> is specified, it is attached to the promise.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-close"></a><h2>client.close()</h2>
<pre class="programlisting">
client.close([problem])
</pre>
<p>Close the DBus client. If <code class="code">problem</code> is specified it should be a
<a class="link" href="cockpit-error.html#cockpit-problems" title="Problem Codes">problem code</a> string.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-onclose"></a><h2>client.onclose</h2>
<pre class="programlisting">
client.addEventListener("close", function(options) { ... })
</pre>
<p>An event triggered when the DBus client closes. This can happen either because
<a class="link" href="cockpit-dbus.html#cockpit-dbus-close" title="client.close()">client.close()</a> function was called,
or the DBus service went away, or some other problem or disconnection.</p>
<p>The <code class="code">options</code> will contain various close information, including a
<code class="code">"problem"</code> field which will be set if the channel was closed because
of a problem.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-onowned"></a><h2>client.onowner</h2>
<pre class="programlisting">
client.addEventListener("owner", function(event, owner) { ... })
</pre>
<p>An event triggered when the owner of the DBus name changes. The owner
value will be the id of the name owner on the bus or null if the name
is unowned. The absence of an owner should not be treated as a disconnection.
However this makes it possible to take some action based on the
actual status of the service, for example disconnecting a pending signal handler.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-options"></a><h2>client.options</h2>
<p>Set to the options used when creating the client. Will not change for the life of
the client.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-unique-name"></a><h2>client.unique_name</h2>
<p>The unique DBus name of the client. Initially null, and becomes valid once the
the client is ready.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy"></a><h2>client.proxy()</h2>
<pre class="programlisting">
proxy = client.proxy([interface, path], [options])
</pre>
<p>Create proxy javascript object for a DBus <code class="code">interface</code>. At the
specified DBus object <code class="code">path</code>. The proxy will have
properties, methods and signals from to the DBus interface, and allows for
natural interaction. If no <code class="code">interface</code> is specified then the DBus
bus name of the client is used. If no <code class="code">path</code> is specified, then
the DBus name of the client is converted to a path.</p>
<p>If creating lots of proxies for a given <code class="code">interface</code> it is more
efficient to use the
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxies" title="client.proxies()"><code class="code">client.proxies()</code></a>
function.</p>
<p>The proxy is loaded when the
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-valid" title="proxy.valid"><code class="code">proxy.valid</code></a> field is
<code class="code">true</code>, and it is set to <code class="code">false</code> if the underlying
<code class="code">interface</code> and/or <code class="code">path</code> don't or no longer exist, or
the <code class="code">client</code> has closed. You can wait for proxy to become valid
by passing a callback to its
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-wait" title="proxy.wait()"><code class="code">proxy.wait()</code></a> function.
The <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-onchanged" title="proxy.onchanged"><code class="code">proxy.onchanged</code></a>
event will also fire when the proxy becomes valid or invalid. DBus properties and
methods on the proxy are not defined until the proxy becomes valid.</p>
<pre class="programlisting">
value = proxy.Prop1
proxy.WritableProp = value
</pre>
<p>All DBus properties on the <code class="code">interface</code> that start with an upper case
letter (as is convention) will be automatically defined on this proxy, and will update
their values as the DBus property values change. In addition the
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-onchanged" title="proxy.onchanged"><code class="code">proxy.onchanged</code></a> event
will fire every time the properties change.</p>
<p>If you assign a value to a writable property on the proxy, the proxy will try to set
that property on the DBus <code class="code">interface</code> at <code class="code">path</code>. The actual proxy
property value will not update until the DBus service has notified the proxy of the
change. If setting a property fails a warning will be logged. In order to have more
reliable setting of properties, or track when they have been set, or if setting fails,
use the <a class="link" href="cockpit-dbus.html#cockpit-dbus-call" title="client.call()"><code class="code">client.call()</code></a> directly.
It should be noted that DBus service implementations may also be inconsistent in
their behavior when setting a property fails.</p>
<p>You can access the raw property data using the
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-data" title="proxy.data"><code class="code">proxy.data</code></a> field, including
data for properties that do not start with an upper case letter.</p>
<pre class="programlisting">
proxy.Method(arg1, arg2)
.done(function(retval1, retval2) {
...
})
.fail(function(ex) {
...
});
</pre>
<p>All DBus methods on the <code class="code">interface</code> that start with an upper case
letter (as is convention) will be automatically defined on this proxy. These
methods are called with arguments as normal javascript arguments. A
<a class="ulink" href="https://www.promisejs.org/" target="_top">promise</a>
that will complete successfully when the method returns, or fail if an error occurs.
The return values from the DBus method will be passed to the <code class="code">done</code> handler
function directly.</p>
<p>Methods that do not start with an upper case letter can be invoked by using
the usual <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-call" title="proxy.call()"><code class="code">proxy.call()</code></a> directly.</p>
<pre class="programlisting">
proxy.addEventListener("Signal", function(event, arg1, arg2) {
...
});
</pre>
<p>All DBus signals on the <code class="code">interface</code> that start with an upper case
letter (as is convention) will be automatically emit events on this proxy. These
events will contain the signal arguments after the standard <code class="code">event</code>
argument.</p>
<p>Signals that do not start with an upper case letter can be subscribed to by
using <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-signal" title="proxy.onsignal"><code class="code">proxy.onsignal</code></a>
directly.</p>
<p>Usually a proxy asks the <code class="code">client</code> to watch and notify it of changes
to the relevant object or path. You can pass an <code class="code">options</code> argument with
the <code class="code">watch</code> field set to <code class="code">false</code> to prevent this.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-client"></a><h2>proxy.client</h2>
<p>Set to the DBus client of the proxy. Will not change for the life of
the proxy.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-path"></a><h2>proxy.path</h2>
<p>Set to the DBus object path of the proxy. Will not change for the life of
the proxy.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-iface"></a><h2>proxy.iface</h2>
<p>Set to the DBus interface name of the proxy. Will not change for the life
of the proxy.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-valid"></a><h2>proxy.valid</h2>
<p>Set to <code class="code">true</code> when the proxy's DBus interface is present at its
DBus path, and all information for the proxy has loaded. Is set to <code class="code">false</code>
while loading, and after the proxy no longer refers a DBus interface and path.
Also set to <code class="code">false</code> if the <code class="code">client</code> closes.</p>
<p>Use the by <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-wait" title="proxy.wait()"><code class="code">proxy.wait()</code></a>
function to wait for a proxy to load. The
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-onchanged" title="proxy.onchanged"><code class="code">proxy.onchanged</code></a>
event will also be emitted when the proxy becomes valid or invalid. DBus properties and
methods on the proxy are not defined until the proxy becomes valid.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-data"></a><h2>proxy.data</h2>
<p>A plain javascript object containing all the raw property data that this
proxy has loaded. This will be updated automatically as the proxy is notified
of property changes from the DBus service. The
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy-onchanged" title="proxy.onchanged"><code class="code">proxy.onchanged</code></a>
event will be emitted when it changes.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-call"></a><h2>proxy.call()</h2>
<pre class="programlisting">
invocation = proxy.call(method, args, [options])
</pre>
<p>Make a DBus method call on this proxy.</p>
<p>For DBus methods that start with an upper case letter, is usually more convenient
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy" title="client.proxy()">to call the method directly on the proxy</a>.
However if methods that do not follow the usual DBus convention,
or specify additional options, or the caller cannot be sure that the method actually
exists, you can use this method.</p>
<p>This function also works on proxies that have are still loading and have not
become valid yet.</p>
<p>The <code class="code">method</code> should be a DBus method name, and the <code class="code">args</code>
should be an array of arguments to pass to the method. The <code class="code">options</code>
are <a class="link" href="cockpit-dbus.html#cockpit-dbus-call" title="client.call()">described elsewhere</a>.</p>
<p>The returned value is identical to the one returned from
<a class="link" href="cockpit-dbus.html#cockpit-dbus-call" title="client.call()">client.call()</a>. It is a
<a class="ulink" href="https://www.promisejs.org/" target="_top">promise</a>
that will complete successfully when the method returns, or fail if an error occurs.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-wait"></a><h2>proxy.wait()</h2>
<pre class="programlisting">
promise = proxy.wait()
proxy.wait(function() {
...
});
</pre>
<p>Wait for a proxy to finish loading. This function returns a promise. If a callback function
is passed as an argument then that function will be invoked when the proxy is ready.
If this method is called after a proxy has already loaded, then the promise will be
resolved immediately, and any callback will be invoked immediately. Use the promise or
<code class="code">proxy.valid</code> to determine whether the proxy is valid.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-onchanged"></a><h2>proxy.onchanged</h2>
<pre class="programlisting">
proxy.addEventListener("changed", function(data) {
...
});
</pre>
<p>This event is emitted when the proxy's properties change.</p>
<p>The <code class="code">data</code> has the following form, and will only include
properties that have changed:</p>
<pre class="programlisting">
{
"Prop1": "value",
"Prop2": 5
}
</pre>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxy-signal"></a><h2>proxy.onsignal</h2>
<pre class="programlisting">
proxy.addEventListener("signal", function(event, name, args) {
...
});
</pre>
<p>This event is emitted when the proxy's emits an event.</p>
<p>For most events, that have names which start with an upper case letter, you can
just <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy" title="client.proxy()">connect to that event as a signal directly</a>.
However if you wish to be notified when any signal is emitted, or for signals that do not
follow the usual DBus convention, you can connect to this event.</p>
<p>The <code class="code">name</code> is the DBus signal name, and the <code class="code">args</code> is an array
of arguments that were emitted with the signal.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxies"></a><h2>client.proxies()</h2>
<pre class="programlisting">
proxies = client.proxies([interface], [path_namespace], [options])
</pre>
<p>Create <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy" title="client.proxy()">proxy javascript objects</a> for
a DBus interfaces. The proxies will have properties, methods and signals from
the DBus <code class="code">interface</code>, and allow for natural interaction. If no
<code class="code">interface</code> is specified then the DBus bus name of the client is used.
If no <code class="code">path_namespace</code> is provided then <code class="code">"/"</code> will be used.</p>
<p>Proxies will be automatically created for instances of the
<code class="code">interface</code> available at the DBus service. The optional
<code class="code">path_namespace</code> argument can be used to restrict the proxies for
instances that have DBus paths which have the namespace path prefix.</p>
<pre class="programlisting">
proxy1 = proxies["/dbus/path1"];
proxy2 = proxies["/dbus/path2"];
for (proxy in proxies) {
...
}
</pre>
<p>The returned <code class="code">proxies</code> object will is used as a dictionary,
and will have values containing proxies for DBus interface instances, with the
keys being the DBus paths of those instances. It is possible to enumerate over
the returned <code class="code">proxies</code>.</p>
<p>Proxies will be automatically added and removed from the <code class="code">proxies</code>
object as they appear and disappear in the service. The
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxies-onadded" title="proxies.onadded"><code class="code">proxies.onadded</code></a>
and <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxies-onremoved" title="proxies.onremoved"><code class="code">proxies.onremoved</code></a>
events will be emitted. DBus services may not support notifications of paths
disappearing.</p>
<p>Use the <code class="code">proxies.wait()</code> function to be notified when the initial
set of proxies has been populated.</p>
<p>Usually a proxies ask the <code class="code">client</code> to watch and be notified of changes
to the relevant object or path. You can pass an <code class="code">options</code> argument with
the <code class="code">watch</code> field set to <code class="code">false</code> to prevent this.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxies-wait"></a><h2>proxies.wait()</h2>
<pre class="programlisting">
promise = proxies.wait()
proxies.wait(function() {
...
});
</pre>
<p>Wait for a <code class="code">proxies</code> object to populate its initial set of proxies.
This function returns a promise. If a callback function is passed as an argument then
that function will be invoked when the proxies are ready. If this method is called after
the proxies have populated, then the promise will be resolved immediately, and any callback
will be invoked immediately.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxies-client"></a><h2>proxies.client</h2>
<p>Set to the DBus client of the proxies. Will not change.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxies-iface"></a><h2>proxies.iface</h2>
<p>Set to the DBus interface name of the proxies. Will not change.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxies-path_namespace"></a><h2>proxies.path_namespace</h2>
<p>Set to the DBus path namespace used which the proxies must have as a DBus
path prefix. Will not change.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxies-onadded"></a><h2>proxies.onadded</h2>
<pre class="programlisting">
proxies.addEventListener("added", function(event, proxy) {
...
})
</pre>
<p>This event is emitted when a proxy is added to the <code class="code">proxies</code> object.
The proxy will already have loaded.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxies-onchanged"></a><h2>proxies.onchanged</h2>
<pre class="programlisting">
proxies.addEventListener("changed", function(event, proxy) {
...
})
</pre>
<p>This event is emitted when one of the proxy in the <code class="code">proxies</code> object
changes its properties.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-proxies-onremoved"></a><h2>proxies.onremoved</h2>
<pre class="programlisting">
proxies.addEventListener("removed", function(event, proxy) {
...
})
</pre>
<p>This event is emitted when a proxy is removed to the <code class="code">proxies</code> object.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-call"></a><h2>client.call()</h2>
<pre class="programlisting">
invocation = client.call(path, interface, method, args, [options])
</pre>
<p>Make a DBus method call.</p>
<p>The <code class="code">path</code> is the DBus object path to make
the call on, <code class="code">interface</code> is the DBus interface for the method and
<code class="code">method</code> is the name of the method to call. The <code class="code">args</code> is an
array of arguments to pass to the method, each of which must be appropriate for the
expected <a class="link" href="cockpit-dbus.html" title="cockpit.js: DBus Client">DBus type</a> of that argument. The
<code class="code">args</code> may be <code class="code">null</code> if no arguments are to be sent.</p>
<p>The returned value is a
<a class="ulink" href="https://www.promisejs.org/" target="_top">promise</a>
that will complete successfully when the method returns, or fail if an error occurs.</p>
<p>If <code class="code">options</code> is specified it should be a plain javascript object,
which may contain the following properties:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="code">flags</code></span></p></td>
<td><p>A string containing DBus message flags. The character <code class="code">"i"</code>
indicates to the dbus service that interactive authentication is allowed. If the
entire <code class="code">flags</code> field is missing, then <code class="code">"i"</code> is set by
default.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">type</code></span></p></td>
<td><p>A valid DBus type signature to use when calling the method. In the
absence of this, the DBus service will be introspected (and the result cached) to
ask what the method type signature is.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">timeout</code></span></p></td>
<td><p>The timeout of the call in milliseconds. The call will fail with
the <code class="code">"timeout"</code> problem code. If "timeout" is not given,
the call will never time out.</p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsection">
<a name="cockpit-dbus-done"></a><h2>invocation.done()</h2>
<pre class="programlisting">
invocation.done(function(args, options) { ... })
</pre>
<p>This is a standard
<a class="ulink" href="https://www.promisejs.org/" target="_top">promise</a>
method. It sets up a handler to be called when the DBus method call finishes
successfully.</p>
<p>The <code class="code">args</code> argument is an array of return values from the DBus method.
Each of them will be converted to an appropriate
<a class="link" href="cockpit-dbus.html" title="cockpit.js: DBus Client">javascript type</a>.</p>
<p>The <code class="code">options</code> argument may contain additional information about the
reply. If the <code class="code">type</code> option was specified when performing the method call,
then the <code class="code">options</code> in the reply here will also contain a <code class="code">type</code>
field containing the DBus type signature of the output. If the <code class="code">flags</code> option
was specified when performing the call then the <code class="code">options</code> in the reply here
will contain message flags. Possible out message flags are:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="code">></code></span></p></td>
<td><p>A big endian message.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code"><</code></span></p></td>
<td><p>A little endian message.</p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsection">
<a name="cockpit-dbus-fail"></a><h2>invocation.fail()</h2>
<pre class="programlisting">
invocation.fail(function(exception) { ... })
</pre>
<p>This is a standard
<a class="ulink" href="http://api.jquery.com/category/deferred-object/" target="_top">jQuery promise</a> method.
It sets up a handler to be called when the DBus method call fails.</p>
<p>The <code class="code">exception</code> object passed to the handler can have the
following properties:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="code">problem</code></span></p></td>
<td><p>A <a class="link" href="cockpit-error.html#cockpit-problems" title="Problem Codes">problem code</a> string when
a problem occurred starting or communicating with the DBus service. This is
<code class="code">null</code> in the cases where an actual DBus error was occurred.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">name</code></span></p></td>
<td><p>The DBus error name. This will be <code class="code">null</code> in cases where the
failure was not due to a DBus error.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">message</code></span></p></td>
<td><p>A DBus error message. This will be <code class="code">null</code> in cases where the
failure was not due to a DBus error.</p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsection">
<a name="cockpit-dbus-always"></a><h2>invocation.always()</h2>
<pre class="programlisting">
invocation.always(function() { ... })
</pre>
<p>This is a standard
<a class="ulink" href="http://api.jquery.com/category/deferred-object/" target="_top">jQuery promise</a> method.
It sets up a handler to be called when the DBus method call finishes whether successfully,
or fails.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-subscribe"></a><h2>client.subscribe()</h2>
<pre class="programlisting">
subscription = client.subscribe(match, function(path, interface, signal, args) { ... })
</pre>
<p>Subscribe to signals. The <code class="code">match</code> argument is a javascript plain object which
defines what signals to subscribe to. Each property in the <code class="code">match</code> argument restricts
signals subscribed to. If a property is not present then it is treated as a wildcard, matching
anything. If an empty object is specified as <code class="code">match</code> then all signals will be
subscribed to. The <code class="code">match</code> argument may contain the following properties:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="code">interface</code></span></p></td>
<td><p>A DBus interface to match.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">path</code></span></p></td>
<td><p>A DBus object path to match. May not be used together with the
<code class="code">path_namespace</code> property. It should be a valid DBus object path,
that is, it should have no trailing slash.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">path_namespace</code></span></p></td>
<td><p>A DBus object path prefix to match. Any paths in the hierarchy below this
top path will match. May not be used together with the <code class="code">path</code>
property.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">member</code></span></p></td>
<td><p>The DBus signal name to match.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">arg0</code></span></p></td>
<td><p>Matches the first argument of a DBus message, which must be a
string.</p></td>
</tr>
</tbody>
</table></div>
<p>The handler passed as the second argument will be invoked when the signal is received.
A <code class="code">subscription</code> is returned which can be used to remove the subscription by
calling its <code class="code">subscription.remove()</code> method.</p>
<p>It is not a problem to subscribe to the same signals more than once, with identical
or slightly different <code class="code">match</code> arguments.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-remove"></a><h2>subscription.remove()</h2>
<pre class="programlisting">
subscription.remove()
</pre>
<p>Unsubscribe from the DBus signal subscription.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-watch"></a><h2>client.watch()</h2>
<pre class="programlisting">
watch = client.watch(path)
watch = client.watch({ "path_namespace": path_namespace, "interface": interface })
</pre>
<p>Watch for property and interface changes on the given DBus object
<code class="code">path</code> DBus <code class="code">path_namespace</code>. If <code class="code">interface</code> is
specified only properties on that DBus interface will be watched.</p>
<p>The <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy" title="client.proxy()"><code class="code">client.proxy()</code></a> and
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxies" title="client.proxies()"><code class="code">client.proxies()</code></a> functions and
the objects they return are high level wrappers around <code class="code">client.watch()</code>.</p>
<p>The property and interface changes will be available in raw form on the
<a class="link" href="cockpit-dbus.html#cockpit-dbus-onnotify" title="client.onnotify"><code class="code">client.onnotify</code></a> event.</p>
<p>Property and interface changes that are caused by a method call or signal will
show up before that method call reply is received, or signal event is triggered.
It should be possible to rely on this guarantee, unless the DBus service in question
behaves incorrectly. Internally these watches work well with code that implements the
<a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager" target="_top">ObjectManager</a>
portion of the DBus specification. If no ObjectManager implementation is available, the
watch falls back to using DBus
<a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-introspectable" target="_top">Introspection</a> along with the usual
<a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties" target="_top">PropertiesChanged</a> signal. If the DBus service implements none of these, or implements them in an
inconsistent manner, then this function will provide inconsistent or unexpected
results.</p>
<p>The parameter is either a DBus <code class="code">path</code> or a plain javascript object
with zero or more of the following fields. If an empty javascript object is used as
an argument, then all paths, interfaces and properties will be watched.</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><code class="code">interface</code></span></p></td>
<td><p>Watch properties on this DBus interface.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">path</code></span></p></td>
<td><p>Watch interfaces and properties at this DBus path. May not be
used together with the <code class="code">path_namespace</code> property.</p></td>
</tr>
<tr>
<td><p><span class="term"><code class="code">path_namespace</code></span></p></td>
<td><p>Watch interfaces and properties under this DBus path. It should
be a valid DBus object path, that is, it should have no trailing slash.
If an ObjectManager implementation is available at this interface, then it
is used. May not be used together with the <code class="code">path</code> property.</p></td>
</tr>
</tbody>
</table></div>
<p>The returned value is a
<a class="ulink" href="https://www.promisejs.org/" target="_top">promise</a>
that will complete successfully when the watch has populated its initial set of properties
and interfaces, and these have been notified via
<a class="link" href="cockpit-dbus.html#cockpit-dbus-onnotify" title="client.onnotify"><code class="code">client.onnotify</code></a>.</p>
<p>A watch can be removed by calling the
<a class="link" href="cockpit-dbus.html#cockpit-dbus-watch-remove" title="watch.remove()"><code class="code">watch.remove()</code></a> method on
the returned value. If identical watches are added more than once, then they must
also be removed the same number of times before the removal takes effect.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-watch-done"></a><h2>watch.done()</h2>
<pre class="programlisting">
watch.done(function() { ... })
</pre>
<p>This is a standard
<a class="ulink" href="https://www.promisejs.org/" target="_top">promise</a>
method. It sets up a handler to be called when the watch has populated its initial
properties and interfaces.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-watch-fail"></a><h2>watch.fail()</h2>
<pre class="programlisting">
watch.fail(function() { ... })
</pre>
<p>This is a standard
<a class="ulink" href="http://api.jquery.com/category/deferred-object/" target="_top">jQuery promise</a>
method. It sets up a handler to be called if the watch fails to populate its initial
properties and interfaces. Note that a watch will only fail if the DBus client
closes or is somehow disconnected. It does not fail in the case of missing
interfaces or properties.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-watch-always"></a><h2>watch.always()</h2>
<pre class="programlisting">
watch.always(function() { ... })
</pre>
<p>This is a standard
<a class="ulink" href="http://api.jquery.com/category/deferred-object/" target="_top">jQuery promise</a>
method. It sets up a handler to be called when the watch has populated its initial
properties and interfaces or has failed to do so.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-watch-remove"></a><h2>watch.remove()</h2>
<pre class="programlisting">
watch.remove()
</pre>
<p>Remove the watch. This may not have any immediate effect if other watches are in
place. In particular, if identical watches are added more than once, then they must
also be removed the same number of times before the removal takes effect.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-onnotify"></a><h2>client.onnotify</h2>
<pre class="programlisting">
client.addEventListener("notify", function(data) { ... })
</pre>
<p>An event triggered when
<a class="link" href="cockpit-dbus.html#cockpit-dbus-watch" title="client.watch()">watched</a> properties or interfaces change.</p>
<p>The <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy" title="client.proxy()"><code class="code">client.proxy()</code></a> and
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxies" title="client.proxies()"><code class="code">client.proxies()</code></a> functions and
the objects they return are high level wrappers around the <code class="code">data</code> provided
by this event.</p>
<p>The <code class="code">data</code> has the following form:</p>
<pre class="programlisting">
{
"/path1": {
"org.Interface1": {
"Prop1": "value",
"Prop2": 5
},
"org.Interface2": null
}
}
</pre>
<p>Multiple paths may be present, each of which may have multiple interfaces, each
of which may have multiple properties. The first time a given path and interface is
emitted from this signal, it will have all its properties and interfaces. Thereafter
only changes are noted. If an interface is set to <code class="code">null</code>, then that
interface has disappeared.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-notify"></a><h2>client.notify()</h2>
<pre class="programlisting">
client.notify(data)
</pre>
<p>Emits a synthetic <a class="link" href="cockpit-dbus.html#cockpit-dbus-onnotify" title="client.onnotify"><code class="code">notify</code></a> event.
The <code class="code">data</code> argument should follow the same layout as
described for the <code class="code">notify</code> event.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-onmeta"></a><h2>client.onmeta</h2>
<pre class="programlisting">
client.onmeta = function(ev, data) { ... }
</pre>
<p>An event triggered when the meta data about
<a class="link" href="cockpit-dbus.html#cockpit-dbus-watch" title="client.watch()">watched</a> interfaces is loaded.</p>
<p>The <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy" title="client.proxy()"><code class="code">client.proxy()</code></a> and
<a class="link" href="cockpit-dbus.html#cockpit-dbus-proxies" title="client.proxies()"><code class="code">client.proxies()</code></a> functions and
the objects they return are high level wrappers around the <code class="code">data</code> provided
by this event.</p>
<p>The <code class="code">data</code> has the following form:</p>
<pre class="programlisting">
{
"org.Interface": {
"methods": {
"Method1": {
"in": [ "s", "v" ],
"out": [ "i" ]
},
"Method2": { }
},
"signals": {
"Signal": {
"in": [ "b", "s" ]
}
},
"properties": {
"Prop1": {
"flags": "rw",
"type": "s"
},
"Prop2": {
"flags": "r",
"type": "b"
}
}
}
}
</pre>
<p>Multiple interfaces may be present, each of which may have methods and properties.
This is emitted before the first <a class="link" href="cockpit-dbus.html#cockpit-dbus-proxy" title="client.proxy()"><code class="code">client.onnotify</code></a>
event for the relevant interface.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-meta"></a><h2>client.meta()</h2>
<pre class="programlisting">
client.meta(data)
</pre>
<p>Populate DBus introspection metadata about DBus interfaces. Usually this metadata
is automatically introspected from the DBus services called by the <code class="code">client</code>,
but in certain cases it is useful to populate this info from javascript code. One such
case is when exporting a DBus service from javascript.</p>
<p>The <a class="link" href="cockpit-dbus.html#cockpit-dbus-onmeta" title="client.onmeta"><code class="code">client.onmeta</code></a> event will
be emitted by this method call. It's documentation includes information about the form
of the <code class="code">data</code>.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-publish"></a><h2>client.publish()</h2>
<pre class="programlisting">
published = client.publish(path, interface, object, [options])
</pre>
<p>Publish a DBus <code class="code">interface</code> at the specified object <code class="code">path</code>.
Methods on the Javascript <code class="code">object</code> will be invoked when DBus methods on the
specified <code class="code">interface</code> are invoked by callers.</p>
<p>The meta data for the DBus interface must have been populated using the
<a class="link" href="cockpit-dbus.html#cockpit-dbus-meta" title="client.meta()"><code class="code">client.meta()</code></a> function. The
returned <code class="code">published</code> object is a promise object. It will resolve when the
DBus interface has been published on the bus. It is not an error to publish the same
interface and path repeatedly: Previously published objects at the interface and
path are replaced by those published later.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-published"></a><h2>published.remove()</h2>
<pre class="programlisting">
published.remove()
</pre>
<p>Un-publishes a DBus interface at an object path. This method can be invoked
on the <code class="code">published</code> result returned from the
<a class="link" href="cockpit-dbus.html#cockpit-dbus-publish" title="client.publish()"><code class="code">client.publish()</code></a> function.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-variant"></a><h2>cockpit.variant()</h2>
<pre class="programlisting">
variant = cockpit.variant(type, value)
</pre>
<p>A DBus variant is represented as a plain javascript object with a
<code class="code">"t"</code> property represesting the full DBus type of the variant,
and a <code class="code">"v"</code> property containing the variant value.</p>
<p>This is a helper function for creating such a variant object.</p>
</div>
<div class="refsection">
<a name="cockpit-dbus-byte-array"></a><h2>cockpit.byte_array()</h2>
<pre class="programlisting">
byte_array = cockpit.byte_array(value)
</pre>
<p>A DBus byte array is represented as base64 data encoded in a string. This
is a helper function for creating such a byte array.</p>
</div>
</div>
<div class="footer"><hr></div>
</body>
</html>
|