Tcl DBus Interface

Hex Artifact Content
Login

Artifact 3ad654f7e4bc6b0e67d7eac488e6d36d8db84329736012a62d480d9dc4e7b341:

Wiki page [Tcl DBus Interface] by schelte 2018-01-19 12:04:17.
0000: 44 20 32 30 31 38 2d 30 31 2d 31 39 54 31 32 3a  D 2018-01-19T12:
0010: 30 34 3a 31 37 2e 37 35 32 0a 4c 20 54 63 6c 5c  04:17.752.L Tcl\
0020: 73 44 42 75 73 5c 73 49 6e 74 65 72 66 61 63 65  sDBus\sInterface
0030: 0a 55 20 73 63 68 65 6c 74 65 0a 57 20 32 33 31  .U schelte.W 231
0040: 39 39 0a 3c 68 31 3e 54 63 6c 20 44 2d 42 75 73  99.<h1>Tcl D-Bus
0050: 20 49 6e 74 65 72 66 61 63 65 3c 2f 68 31 3e 0d   Interface</h1>.
0060: 0a 0d 0a 3c 70 3e 64 62 69 66 20 2d 20 41 70 70  ...<p>dbif - App
0070: 6c 69 63 61 74 69 6f 6e 20 6c 61 79 65 72 20 61  lication layer a
0080: 72 6f 75 6e 64 20 74 68 65 20 54 63 6c 20 44 2d  round the Tcl D-
0090: 42 75 73 20 6c 69 62 72 61 72 79 0d 0a 0d 0a 3c  Bus library....<
00a0: 68 72 3e 0d 0a 0d 0a 3c 68 32 3e 53 79 6e 6f 70  hr>....<h2>Synop
00b0: 73 69 73 3c 2f 68 32 3e 0d 0a 0d 0a 3c 70 3e 0d  sis</h2>....<p>.
00c0: 0a 70 61 63 6b 61 67 65 20 72 65 71 75 69 72 65  .package require
00d0: 20 3c 62 3e 54 63 6c 20 38 2e 35 3c 2f 62 3e 3c   <b>Tcl 8.5</b><
00e0: 62 72 3e 0d 0a 70 61 63 6b 61 67 65 20 72 65 71  br>..package req
00f0: 75 69 72 65 20 3c 62 3e 64 62 75 73 20 32 2e 31  uire <b>dbus 2.1
0100: 3c 2f 62 3e 3c 62 72 3e 0d 0a 70 61 63 6b 61 67  </b><br>..packag
0110: 65 20 72 65 71 75 69 72 65 20 3c 62 3e 64 62 69  e require <b>dbi
0120: 66 20 31 2e 33 3c 2f 62 3e 3c 62 72 3e 0d 0a 3c  f 1.3</b><br>..<
0130: 70 3e 0d 0a 3c 62 3e 64 62 69 66 3c 2f 62 3e 20  p>..<b>dbif</b> 
0140: 3c 62 3e 63 6f 6e 6e 65 63 74 3c 2f 62 3e 20 3f  <b>connect</b> ?
0150: 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20 3c 69 3e 62  <b>-bus</b> <i>b
0160: 75 73 74 79 70 65 3c 2f 69 3e 3f 20 3f 3c 62 3e  ustype</i>? ?<b>
0170: 2d 6e 6f 71 75 65 75 65 3c 2f 62 3e 3f 20 3f 3c  -noqueue</b>? ?<
0180: 62 3e 2d 72 65 70 6c 61 63 65 3c 2f 62 3e 3f 20  b>-replace</b>? 
0190: 3f 3c 62 3e 2d 79 69 65 6c 64 3c 2f 62 3e 3f 20  ?<b>-yield</b>? 
01a0: 3f 3c 69 3e 6e 61 6d 65 3c 2f 69 3e 20 2e 2e 2e  ?<i>name</i> ...
01b0: 3f 3c 62 72 3e 0d 0a 3c 62 3e 64 62 69 66 3c 2f  ?<br>..<b>dbif</
01c0: 62 3e 20 3c 62 3e 64 65 66 61 75 6c 74 3c 2f 62  b> <b>default</b
01d0: 3e 20 3f 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20 3c  > ?<b>-bus</b> <
01e0: 69 3e 62 75 73 74 79 70 65 3c 2f 69 3e 3f 20 3f  i>bustype</i>? ?
01f0: 3c 62 3e 2d 69 6e 74 65 72 66 61 63 65 3c 2f 62  <b>-interface</b
0200: 3e 20 3c 69 3e 69 6e 74 65 72 66 61 63 65 3c 2f  > <i>interface</
0210: 69 3e 3f 3c 62 72 3e 0d 0a 3c 62 3e 64 62 69 66  i>?<br>..<b>dbif
0220: 3c 2f 62 3e 20 3c 62 3e 64 65 6c 65 74 65 3c 2f  </b> <b>delete</
0230: 62 3e 20 3f 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20  b> ?<b>-bus</b> 
0240: 3c 69 3e 62 75 73 74 79 70 65 3c 2f 69 3e 3f 20  <i>bustype</i>? 
0250: 3f 3c 62 3e 2d 69 6e 74 65 72 66 61 63 65 3c 2f  ?<b>-interface</
0260: 62 3e 20 3c 69 3e 69 6e 74 65 72 66 61 63 65 3c  b> <i>interface<
0270: 2f 69 3e 3f 20 3f 3c 62 3e 2d 73 69 6e 67 6c 65  /i>? ?<b>-single
0280: 3c 2f 62 3e 3f 20 3c 69 3e 70 61 74 68 3c 2f 69  </b>? <i>path</i
0290: 3e 3c 62 72 3e 0d 0a 3c 62 3e 64 62 69 66 3c 2f  ><br>..<b>dbif</
02a0: 62 3e 20 3c 62 3e 65 72 72 6f 72 3c 2f 62 3e 20  b> <b>error</b> 
02b0: 3c 69 3e 6d 65 73 73 61 67 65 49 44 3c 2f 69 3e  <i>messageID</i>
02c0: 20 3c 69 3e 65 72 72 6f 72 6d 65 73 73 61 67 65   <i>errormessage
02d0: 3c 2f 69 3e 20 3f 3c 69 3e 65 72 72 6f 72 6e 61  </i> ?<i>errorna
02e0: 6d 65 3c 2f 69 3e 3f 3c 62 72 3e 0d 0a 3c 62 3e  me</i>?<br>..<b>
02f0: 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 67 65 6e 65  dbif</b> <b>gene
0300: 72 61 74 65 3c 2f 62 3e 20 3c 69 3e 73 69 67 6e  rate</b> <i>sign
0310: 61 6c 49 44 3c 2f 69 3e 20 3f 3c 69 3e 61 72 67  alID</i> ?<i>arg
0320: 3c 2f 69 3e 20 2e 2e 2e 3f 3c 62 72 3e 0d 0a 3c  </i> ...?<br>..<
0330: 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 67 65  b>dbif</b> <b>ge
0340: 74 3c 2f 62 3e 20 3c 69 3e 6d 65 73 73 61 67 65  t</b> <i>message
0350: 49 44 3c 2f 69 3e 20 3c 69 3e 6e 61 6d 65 3c 2f  ID</i> <i>name</
0360: 69 3e 3c 62 72 3e 0d 0a 3c 62 3e 64 62 69 66 3c  i><br>..<b>dbif<
0370: 2f 62 3e 20 3c 62 3e 6c 69 73 74 65 6e 3c 2f 62  /b> <b>listen</b
0380: 3e 20 3f 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20 3c  > ?<b>-bus</b> <
0390: 69 3e 62 75 73 74 79 70 65 3c 2f 69 3e 3f 20 3f  i>bustype</i>? ?
03a0: 3c 62 3e 2d 69 6e 74 65 72 66 61 63 65 3c 2f 62  <b>-interface</b
03b0: 3e 20 3c 69 3e 69 6e 74 65 72 66 61 63 65 3c 2f  > <i>interface</
03c0: 69 3e 3f 20 3c 69 3e 70 61 74 68 3c 2f 69 3e 20  i>? <i>path</i> 
03d0: 3c 69 3e 6e 61 6d 65 3c 2f 69 3e 20 3f 3c 69 3e  <i>name</i> ?<i>
03e0: 61 72 67 6c 69 73 74 3c 2f 69 3e 3f 20 3f 3c 69  arglist</i>? ?<i
03f0: 3e 69 6e 74 65 72 70 3c 2f 69 3e 3f 20 3c 69 3e  >interp</i>? <i>
0400: 62 6f 64 79 3c 2f 69 3e 3c 62 72 3e 0d 0a 3c 62  body</i><br>..<b
0410: 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 6d 65 74  >dbif</b> <b>met
0420: 68 6f 64 3c 2f 62 3e 20 3f 3c 62 3e 2d 61 74 74  hod</b> ?<b>-att
0430: 72 69 62 75 74 65 73 3c 2f 62 3e 20 3c 69 3e 61  ributes</b> <i>a
0440: 74 74 72 69 62 75 74 65 73 3c 2f 69 3e 3f 20 3f  ttributes</i>? ?
0450: 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20 3c 69 3e 62  <b>-bus</b> <i>b
0460: 75 73 74 79 70 65 3c 2f 69 3e 3f 20 3f 3c 62 3e  ustype</i>? ?<b>
0470: 2d 69 6e 74 65 72 66 61 63 65 3c 2f 62 3e 20 3c  -interface</b> <
0480: 69 3e 69 6e 74 65 72 66 61 63 65 3c 2f 69 3e 3f  i>interface</i>?
0490: 20 3c 69 3e 70 61 74 68 3c 2f 69 3e 20 3c 69 3e   <i>path</i> <i>
04a0: 6e 61 6d 65 3c 2f 69 3e 20 3f 3c 69 3e 69 6e 70  name</i> ?<i>inp
04b0: 75 74 61 72 67 73 3c 2f 69 3e 20 3f 3c 69 3e 6f  utargs</i> ?<i>o
04c0: 75 74 70 75 74 61 72 67 73 3c 2f 69 3e 3f 3f 20  utputargs</i>?? 
04d0: 3f 3c 69 3e 69 6e 74 65 72 70 3c 2f 69 3e 3f 20  ?<i>interp</i>? 
04e0: 3c 69 3e 62 6f 64 79 3c 2f 69 3e 3c 62 72 3e 0d  <i>body</i><br>.
04f0: 0a 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e  .<b>dbif</b> <b>
0500: 70 61 76 65 3c 2f 62 3e 20 3f 3c 62 3e 2d 62 75  pave</b> ?<b>-bu
0510: 73 3c 2f 62 3e 20 3c 69 3e 62 75 73 74 79 70 65  s</b> <i>bustype
0520: 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d 69 6e 74 65 72  </i>? ?<b>-inter
0530: 66 61 63 65 3c 2f 62 3e 20 3c 69 3e 69 6e 74 65  face</b> <i>inte
0540: 72 66 61 63 65 3c 2f 69 3e 3f 20 3c 69 3e 70 61  rface</i>? <i>pa
0550: 74 68 3c 2f 69 3e 3c 62 72 3e 0d 0a 3c 62 3e 64  th</i><br>..<b>d
0560: 62 69 66 3c 2f 62 3e 20 3c 62 3e 70 72 6f 70 65  bif</b> <b>prope
0570: 72 74 79 3c 2f 62 3e 20 3f 3c 62 3e 2d 61 63 63  rty</b> ?<b>-acc
0580: 65 73 73 3c 2f 62 3e 20 3c 69 3e 6d 6f 64 65 3c  ess</b> <i>mode<
0590: 2f 69 3e 3f 20 3f 3c 62 3e 2d 61 74 74 72 69 62  /i>? ?<b>-attrib
05a0: 75 74 65 73 3c 2f 62 3e 20 3c 69 3e 61 74 74 72  utes</b> <i>attr
05b0: 69 62 75 74 65 73 3c 2f 69 3e 3f 20 3f 3c 62 3e  ibutes</i>? ?<b>
05c0: 2d 62 75 73 3c 2f 62 3e 20 3c 69 3e 62 75 73 74  -bus</b> <i>bust
05d0: 79 70 65 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d 69 6e  ype</i>? ?<b>-in
05e0: 74 65 72 66 61 63 65 3c 2f 62 3e 20 3c 69 3e 69  terface</b> <i>i
05f0: 6e 74 65 72 66 61 63 65 3c 2f 69 3e 3f 20 3c 69  nterface</i>? <i
0600: 3e 70 61 74 68 3c 2f 69 3e 20 3c 69 3e 6e 61 6d  >path</i> <i>nam
0610: 65 3c 2f 69 3e 3f 3a 3c 69 3e 73 69 67 6e 61 74  e</i>?:<i>signat
0620: 75 72 65 3c 2f 69 3e 3f 20 3c 69 3e 76 61 72 69  ure</i>? <i>vari
0630: 61 62 6c 65 3c 2f 69 3e 20 3f 3f 3c 69 3e 69 6e  able</i> ??<i>in
0640: 74 65 72 70 3c 2f 69 3e 3f 20 3c 69 3e 62 6f 64  terp</i>? <i>bod
0650: 79 3c 2f 69 3e 3f 3c 62 72 3e 0d 0a 3c 62 3e 64  y</i>?<br>..<b>d
0660: 62 69 66 3c 2f 62 3e 20 3c 62 3e 72 65 74 75 72  bif</b> <b>retur
0670: 6e 3c 2f 62 3e 20 3c 69 3e 6d 65 73 73 61 67 65  n</b> <i>message
0680: 49 44 3c 2f 69 3e 20 3c 69 3e 72 65 74 75 72 6e  ID</i> <i>return
0690: 76 61 6c 75 65 3c 2f 69 3e 3c 62 72 3e 0d 0a 3c  value</i><br>..<
06a0: 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 73 69  b>dbif</b> <b>si
06b0: 67 6e 61 6c 3c 2f 62 3e 20 3f 3c 62 3e 2d 61 74  gnal</b> ?<b>-at
06c0: 74 72 69 62 75 74 65 73 3c 2f 62 3e 20 3c 69 3e  tributes</b> <i>
06d0: 61 74 74 72 69 62 75 74 65 73 3c 2f 69 3e 3f 20  attributes</i>? 
06e0: 3f 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20 3c 69 3e  ?<b>-bus</b> <i>
06f0: 62 75 73 74 79 70 65 3c 2f 69 3e 3f 20 3f 3c 62  bustype</i>? ?<b
0700: 3e 2d 69 64 3c 2f 62 3e 20 3c 69 3e 73 69 67 6e  >-id</b> <i>sign
0710: 61 6c 49 44 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d 69  alID</i>? ?<b>-i
0720: 6e 74 65 72 66 61 63 65 3c 2f 62 3e 20 3c 69 3e  nterface</b> <i>
0730: 69 6e 74 65 72 66 61 63 65 3c 2f 69 3e 3f 20 3c  interface</i>? <
0740: 69 3e 70 61 74 68 3c 2f 69 3e 20 3c 69 3e 6e 61  i>path</i> <i>na
0750: 6d 65 3c 2f 69 3e 20 3f 3c 69 3e 61 72 67 6c 69  me</i> ?<i>argli
0760: 73 74 3c 2f 69 3e 20 3f 3f 3c 69 3e 69 6e 74 65  st</i> ??<i>inte
0770: 72 70 3c 2f 69 3e 3f 20 3c 69 3e 61 72 67 73 3c  rp</i>? <i>args<
0780: 2f 69 3e 20 3c 69 3e 62 6f 64 79 3c 2f 69 3e 3f  /i> <i>body</i>?
0790: 3f 3c 62 72 3e 0d 0a 0d 0a 3c 68 72 3e 0d 0a 0d  ?<br>....<hr>...
07a0: 0a 3c 68 32 3e 44 65 73 63 72 69 70 74 69 6f 6e  .<h2>Description
07b0: 3c 2f 68 32 3e 0d 0a 0d 0a 54 68 65 20 3c 62 3e  </h2>....The <b>
07c0: 64 62 69 66 3c 2f 62 3e 20 70 61 63 6b 61 67 65  dbif</b> package
07d0: 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 67 68   provides a high
07e0: 65 72 20 6c 65 76 65 6c 20 77 72 61 70 70 65 72  er level wrapper
07f0: 20 61 72 6f 75 6e 64 0d 0a 74 68 65 20 6c 6f 77   around..the low
0800: 2d 6c 65 76 65 6c 20 44 2d 42 75 73 20 63 6f 6d  -level D-Bus com
0810: 6d 61 6e 64 73 20 70 72 6f 76 69 64 65 64 20 62  mands provided b
0820: 79 20 74 68 65 20 64 62 75 73 20 70 61 63 6b 61  y the dbus packa
0830: 67 65 2e 20 54 68 65 20 70 61 63 6b 61 67 65 20  ge. The package 
0840: 61 6c 73 6f 0d 0a 70 72 6f 76 69 64 65 73 20 61  also..provides a
0850: 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
0860: 20 6f 66 20 61 20 6e 75 6d 62 65 72 20 6f 66 20   of a number of 
0870: 73 74 61 6e 64 61 72 64 20 44 2d 42 75 73 20 69  standard D-Bus i
0880: 6e 74 65 72 66 61 63 65 73 2e 0d 0a 53 65 65 20  nterfaces...See 
0890: 3c 62 3e 53 54 41 4e 44 41 52 44 20 49 4e 54 45  <b>STANDARD INTE
08a0: 52 46 41 43 45 53 3c 2f 62 3e 20 66 6f 72 20 6d  RFACES</b> for m
08b0: 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  ore information.
08c0: 0d 0a 0d 0a 3c 70 3e 0d 0a 0d 0a 41 63 63 65 73  ....<p>....Acces
08d0: 73 20 74 6f 20 61 6c 6c 20 66 75 6e 63 74 69 6f  s to all functio
08e0: 6e 73 20 6f 66 20 74 68 65 20 3c 62 3e 64 62 69  ns of the <b>dbi
08f0: 66 3c 2f 62 3e 20 70 61 63 6b 61 67 65 20 66 72  f</b> package fr
0900: 6f 6d 20 77 69 74 68 69 6e 0d 0a 61 20 54 63 6c  om within..a Tcl
0910: 20 70 72 6f 67 72 61 6d 20 69 73 20 64 6f 6e 65   program is done
0920: 20 75 73 69 6e 67 20 74 68 65 20 3c 62 3e 64 62   using the <b>db
0930: 69 66 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64 2e 20  if</b> command. 
0940: 54 68 65 20 63 6f 6d 6d 61 6e 64 0d 0a 73 75 70  The command..sup
0950: 70 6f 72 74 73 20 73 65 76 65 72 61 6c 20 73 75  ports several su
0960: 62 63 6f 6d 6d 61 6e 64 73 20 74 68 61 74 20 64  bcommands that d
0970: 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 61 63  etermine what ac
0980: 74 69 6f 6e 20 69 73 20 63 61 72 72 69 65 64 20  tion is carried 
0990: 6f 75 74 2e 0d 0a 3c 64 6c 3e 0d 0a 3c 64 74 3e  out...<dl>..<dt>
09a0: 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 63  <b>dbif</b> <b>c
09b0: 6f 6e 6e 65 63 74 3c 2f 62 3e 20 3f 3c 62 3e 2d  onnect</b> ?<b>-
09c0: 62 75 73 3c 2f 62 3e 20 3c 69 3e 62 75 73 74 79  bus</b> <i>busty
09d0: 70 65 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d 6e 6f 71  pe</i>? ?<b>-noq
09e0: 75 65 75 65 3c 2f 62 3e 3f 20 3f 3c 62 3e 2d 72  ueue</b>? ?<b>-r
09f0: 65 70 6c 61 63 65 3c 2f 62 3e 3f 20 3f 3c 62 3e  eplace</b>? ?<b>
0a00: 2d 79 69 65 6c 64 3c 2f 62 3e 3f 20 3f 3c 69 3e  -yield</b>? ?<i>
0a10: 6e 61 6d 65 3c 2f 69 3e 20 2e 2e 2e 3f 0d 0a 3c  name</i> ...?..<
0a20: 64 64 3e 43 6f 6e 6e 65 63 74 20 74 6f 20 61 20  dd>Connect to a 
0a30: 6d 65 73 73 61 67 65 20 62 75 73 20 61 6e 64 20  message bus and 
0a40: 6f 70 74 69 6f 6e 61 6c 6c 79 20 72 65 71 75 65  optionally reque
0a50: 73 74 20 74 68 65 20 44 2d 42 75 73 20 73 65 72  st the D-Bus ser
0a60: 76 65 72 20 74 6f 20 61 73 73 69 67 6e 0d 0a 6f  ver to assign..o
0a70: 6e 65 20 6f 72 20 6d 6f 72 65 20 6e 61 6d 65 73  ne or more names
0a80: 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
0a90: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0d 0a 0d 0a  application.....
0aa0: 3c 70 3e 0d 0a 0d 0a 54 68 65 20 3c 62 3e 2d 79  <p>....The <b>-y
0ab0: 69 65 6c 64 3c 2f 62 3e 20 6f 70 74 69 6f 6e 20  ield</b> option 
0ac0: 73 70 65 63 69 66 69 65 73 20 74 68 61 74 20 74  specifies that t
0ad0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
0ae0: 69 6c 6c 20 72 65 6c 65 61 73 65 20 74 68 65 0d  ill release the.
0af0: 0a 72 65 71 75 65 73 74 65 64 20 6e 61 6d 65 20  .requested name 
0b00: 77 68 65 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  when some other 
0b10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 72 65 71 75  application requ
0b20: 65 73 74 73 20 74 68 65 20 73 61 6d 65 20 6e 61  ests the same na
0b30: 6d 65 20 61 6e 64 20 68 61 73 0d 0a 69 6e 64 69  me and has..indi
0b40: 63 61 74 65 64 20 74 68 61 74 20 69 74 20 77 61  cated that it wa
0b50: 6e 74 73 20 74 6f 20 74 61 6b 65 20 6f 76 65 72  nts to take over
0b60: 20 6f 77 6e 65 72 73 68 69 70 20 6f 66 20 74 68   ownership of th
0b70: 65 20 6e 61 6d 65 2e 20 54 68 65 20 61 70 70 6c  e name. The appl
0b80: 69 63 61 74 69 6f 6e 0d 0a 77 69 6c 6c 20 62 65  ication..will be
0b90: 20 69 6e 66 6f 72 6d 65 64 20 62 79 20 61 20 3c   informed by a <
0ba0: 65 6d 3e 4e 61 6d 65 4c 6f 73 74 3c 2f 65 6d 3e  em>NameLost</em>
0bb0: 20 73 69 67 6e 61 6c 20 77 68 65 6e 20 69 74 20   signal when it 
0bc0: 6c 6f 73 65 73 20 6f 77 6e 65 72 73 68 69 70 20  loses ownership 
0bd0: 6f 66 20 74 68 65 0d 0a 6e 61 6d 65 2e 0d 0a 0d  of the..name....
0be0: 0a 3c 70 3e 0d 0a 0d 0a 54 68 65 20 3c 62 3e 2d  .<p>....The <b>-
0bf0: 72 65 70 6c 61 63 65 3c 2f 62 3e 20 6f 70 74 69  replace</b> opti
0c00: 6f 6e 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  on indicates tha
0c10: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
0c20: 6e 20 77 61 6e 74 73 20 74 6f 20 74 61 6b 65 0d  n wants to take.
0c30: 0a 6f 76 65 72 20 74 68 65 20 6f 77 6e 65 72 73  .over the owners
0c40: 68 69 70 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  hip of the name 
0c50: 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
0c60: 74 69 6f 6e 20 74 68 61 74 20 69 73 20 63 75 72  tion that is cur
0c70: 72 65 6e 74 6c 79 20 74 68 65 0d 0a 70 72 69 6d  rently the..prim
0c80: 61 72 79 20 6f 77 6e 65 72 2c 20 69 66 20 61 6e  ary owner, if an
0c90: 79 2e 20 54 68 69 73 20 72 65 71 75 65 73 74 20  y. This request 
0ca0: 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 68 6f 6e  will only be hon
0cb0: 6f 75 72 65 64 20 69 66 20 74 68 65 20 63 75 72  oured if the cur
0cc0: 72 65 6e 74 0d 0a 6f 77 6e 65 72 20 68 61 73 20  rent..owner has 
0cd0: 69 6e 64 69 63 61 74 65 64 20 74 68 61 74 20 69  indicated that i
0ce0: 74 20 77 69 6c 6c 20 72 65 6c 65 61 73 65 20 74  t will release t
0cf0: 68 65 20 6e 61 6d 65 20 6f 6e 20 72 65 71 75 65  he name on reque
0d00: 73 74 2e 20 53 65 65 20 61 6c 73 6f 20 74 68 65  st. See also the
0d10: 0d 0a 3c 62 3e 2d 79 69 65 6c 64 3c 2f 62 3e 20  ..<b>-yield</b> 
0d20: 6f 70 74 69 6f 6e 2e 0d 0a 0d 0a 3c 70 3e 0d 0a  option.....<p>..
0d30: 0d 0a 49 66 20 74 68 65 20 72 65 71 75 65 73 74  ..If the request
0d40: 65 64 20 6e 61 6d 65 20 69 73 20 63 75 72 72 65  ed name is curre
0d50: 6e 74 6c 79 20 69 6e 20 75 73 65 20 61 6e 64 20  ntly in use and 
0d60: 74 68 65 20 2d 72 65 70 6c 61 63 65 20 6f 70 74  the -replace opt
0d70: 69 6f 6e 20 68 61 73 20 6e 6f 74 0d 0a 62 65 65  ion has not..bee
0d80: 6e 20 73 70 65 63 69 66 69 65 64 2c 20 6f 72 20  n specified, or 
0d90: 74 68 65 20 3c 62 3e 2d 72 65 70 6c 61 63 65 3c  the <b>-replace<
0da0: 2f 62 3e 20 6f 70 74 69 6f 6e 20 77 61 73 20 73  /b> option was s
0db0: 70 65 63 69 66 69 65 64 20 62 75 74 20 74 68 65  pecified but the
0dc0: 0d 0a 63 75 72 72 65 6e 74 20 6f 77 6e 65 72 20  ..current owner 
0dd0: 69 73 20 75 6e 77 69 6c 6c 69 6e 67 20 74 6f 20  is unwilling to 
0de0: 67 69 76 65 20 75 70 20 69 74 73 20 6f 77 6e 65  give up its owne
0df0: 72 73 68 69 70 2c 20 74 68 65 20 6e 61 6d 65 20  rship, the name 
0e00: 72 65 71 75 65 73 74 20 77 69 6c 6c 0d 0a 6e 6f  request will..no
0e10: 72 6d 61 6c 6c 79 20 62 65 20 71 75 65 75 65 64  rmally be queued
0e20: 2e 20 54 68 65 6e 20 77 68 65 6e 20 74 68 65 20  . Then when the 
0e30: 6e 61 6d 65 20 69 73 20 72 65 6c 65 61 73 65 64  name is released
0e40: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
0e50: 6f 77 6e 65 72 20 69 74 0d 0a 69 73 20 61 73 73  owner it..is ass
0e60: 69 67 6e 65 64 20 74 6f 20 74 68 65 20 6e 65 78  igned to the nex
0e70: 74 20 72 65 71 75 65 73 74 65 72 20 69 6e 20 74  t requester in t
0e80: 68 65 20 71 75 65 75 65 20 61 6e 64 20 61 20 73  he queue and a s
0e90: 69 67 6e 61 6c 20 69 73 20 73 65 6e 74 20 74 6f  ignal is sent to
0ea0: 0d 0a 69 6e 66 6f 72 6d 20 74 68 61 74 20 72 65  ..inform that re
0eb0: 71 75 65 73 74 65 72 20 74 68 61 74 20 69 74 20  quester that it 
0ec0: 69 73 20 6e 6f 77 20 74 68 65 20 70 72 69 6d 61  is now the prima
0ed0: 72 79 20 6f 77 6e 65 72 20 6f 66 20 74 68 65 20  ry owner of the 
0ee0: 6e 61 6d 65 2e 20 54 68 65 0d 0a 3c 62 3e 2d 6e  name. The..<b>-n
0ef0: 6f 71 75 65 75 65 3c 2f 62 3e 20 6f 70 74 69 6f  oqueue</b> optio
0f00: 6e 20 6d 61 79 20 62 65 20 73 70 65 63 69 66 69  n may be specifi
0f10: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
0f20: 68 61 74 20 74 68 65 20 6e 61 6d 65 20 72 65 71  hat the name req
0f30: 75 65 73 74 0d 0a 73 68 6f 75 6c 64 20 6e 6f 74  uest..should not
0f40: 20 62 65 20 71 75 65 75 65 64 2e 0d 0a 0d 0a 3c   be queued.....<
0f50: 70 3e 0d 0a 0d 0a 54 68 65 20 63 6f 6d 6d 61 6e  p>....The comman
0f60: 64 20 72 65 74 75 72 6e 73 20 61 20 6c 69 73 74  d returns a list
0f70: 20 6f 66 20 6e 61 6d 65 73 20 74 68 61 74 20 68   of names that h
0f80: 61 76 65 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ave successfully
0f90: 20 62 65 65 6e 20 61 63 71 75 69 72 65 64 2e 0d   been acquired..
0fa0: 0a 49 66 20 74 68 65 20 64 62 75 73 20 63 6f 6e  .If the dbus con
0fb0: 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 69  nection handle i
0fc0: 73 20 6e 65 65 64 65 64 2c 20 69 74 20 63 61 6e  s needed, it can
0fd0: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   be obtained fro
0fe0: 6d 20 74 68 65 20 2d 62 75 73 0d 0a 72 65 74 75  m the -bus..retu
0ff0: 72 6e 20 6f 70 74 69 6f 6e 2e 0d 0a 0d 0a 3c 70  rn option.....<p
1000: 3e 0d 0a 0d 0a 54 68 65 20 66 6f 6c 6c 6f 77 69  >....The followi
1010: 6e 67 20 63 6f 64 65 20 63 61 6e 20 62 65 20 75  ng code can be u
1020: 73 65 64 20 74 6f 20 61 6c 6c 6f 77 20 61 20 6e  sed to allow a n
1030: 65 77 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ew instance of a
1040: 20 70 72 6f 67 72 61 6d 20 74 6f 20 0d 0a 72 65   program to ..re
1050: 70 6c 61 63 65 20 74 68 65 20 63 75 72 72 65 6e  place the curren
1060: 74 20 6f 6e 65 2e 20 54 68 69 73 20 63 61 6e 20  t one. This can 
1070: 62 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  be useful during
1080: 20 70 72 6f 67 72 61 6d 20 64 65 76 65 6c 6f 70   program develop
1090: 6d 65 6e 74 3a 0d 0a 0d 0a 3c 76 65 72 62 61 74  ment:....<verbat
10a0: 69 6d 3e 0d 0a 64 62 69 66 20 63 6f 6e 6e 65 63  im>..dbif connec
10b0: 74 20 2d 79 69 65 6c 64 20 2d 72 65 70 6c 61 63  t -yield -replac
10c0: 65 20 24 64 62 75 73 6e 61 6d 65 0d 0a 64 62 69  e $dbusname..dbi
10d0: 66 20 6c 69 73 74 65 6e 20 2d 69 6e 74 65 72 66  f listen -interf
10e0: 61 63 65 20 5b 64 62 75 73 20 69 6e 66 6f 20 73  ace [dbus info s
10f0: 65 72 76 69 63 65 5d 20 5c 0d 0a 20 20 5b 64 62  ervice] \..  [db
1100: 75 73 20 69 6e 66 6f 20 70 61 74 68 5d 20 4e 61  us info path] Na
1110: 6d 65 4c 6f 73 74 20 6e 61 6d 65 20 7b 69 66 20  meLost name {if 
1120: 7b 24 6e 61 6d 65 20 65 71 20 24 3a 3a 64 62 75  {$name eq $::dbu
1130: 73 6e 61 6d 65 7d 20 65 78 69 74 7d 0d 0a 3c 2f  sname} exit}..</
1140: 76 65 72 62 61 74 69 6d 3e 0d 0a 3c 64 74 3e 3c  verbatim>..<dt><
1150: 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 64 65  b>dbif</b> <b>de
1160: 66 61 75 6c 74 3c 2f 62 3e 20 3f 3c 62 3e 2d 62  fault</b> ?<b>-b
1170: 75 73 3c 2f 62 3e 20 3c 69 3e 62 75 73 74 79 70  us</b> <i>bustyp
1180: 65 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d 69 6e 74 65  e</i>? ?<b>-inte
1190: 72 66 61 63 65 3c 2f 62 3e 20 3c 69 3e 69 6e 74  rface</b> <i>int
11a0: 65 72 66 61 63 65 3c 2f 69 3e 3f 0d 0a 3c 64 64  erface</i>?..<dd
11b0: 3e 47 65 6e 65 72 61 6c 6c 79 20 61 6e 20 61 70  >Generally an ap
11c0: 70 6c 69 63 61 74 69 6f 6e 20 77 69 6c 6c 20 70  plication will p
11d0: 65 72 66 6f 72 6d 20 73 65 76 65 72 61 6c 20 3c  erform several <
11e0: 62 3e 64 62 69 66 3c 2f 62 3e 20 63 6f 6d 6d 61  b>dbif</b> comma
11f0: 6e 64 73 0d 0a 72 65 6c 61 74 65 64 20 74 6f 20  nds..related to 
1200: 74 68 65 20 73 61 6d 65 20 6d 65 73 73 61 67 65  the same message
1210: 20 62 75 73 20 61 6e 64 20 69 6e 74 65 72 66 61   bus and interfa
1220: 63 65 2e 20 54 6f 20 61 76 6f 69 64 20 68 61 76  ce. To avoid hav
1230: 69 6e 67 20 74 6f 20 70 61 73 73 20 74 68 65 0d  ing to pass the.
1240: 0a 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72  .same values for
1250: 20 74 68 65 20 3c 62 3e 2d 62 75 73 3c 2f 62 3e   the <b>-bus</b>
1260: 20 61 6e 64 20 3c 62 3e 2d 69 6e 74 65 72 66 61   and <b>-interfa
1270: 63 65 3c 2f 62 3e 20 6f 70 74 69 6f 6e 73 20 77  ce</b> options w
1280: 69 74 68 20 61 6c 6c 0d 0a 74 68 6f 73 65 20 63  ith all..those c
1290: 6f 6d 6d 61 6e 64 73 2c 20 74 68 65 69 72 20 64  ommands, their d
12a0: 65 66 61 75 6c 74 73 20 63 61 6e 20 62 65 20 73  efaults can be s
12b0: 65 74 75 70 20 77 69 74 68 20 74 68 65 20 3c 62  etup with the <b
12c0: 3e 64 62 69 66 3c 2f 62 3e 0d 0a 3c 62 3e 64 65  >dbif</b>..<b>de
12d0: 66 61 75 6c 74 3c 2f 62 3e 20 73 75 62 63 6f 6d  fault</b> subcom
12e0: 6d 61 6e 64 2e 0d 0a 0d 0a 3c 70 3e 0d 0a 0d 0a  mand.....<p>....
12f0: 41 6e 20 69 6e 74 65 72 66 61 63 65 20 6e 61 6d  An interface nam
1300: 65 20 6d 75 73 74 20 63 6f 6e 73 69 73 74 20 6f  e must consist o
1310: 66 20 61 74 20 6c 65 61 73 74 20 74 77 6f 20 65  f at least two e
1320: 6c 65 6d 65 6e 74 73 20 73 65 70 61 72 61 74 65  lements separate
1330: 64 20 62 79 0d 0a 61 20 70 65 72 69 6f 64 20 28  d by..a period (
1340: 27 2e 27 29 20 63 68 61 72 61 63 74 65 72 2e 20  '.') character. 
1350: 45 61 63 68 20 65 6c 65 6d 65 6e 74 20 6d 61 79  Each element may
1360: 20 6f 6e 6c 79 20 63 6f 6e 74 61 69 6e 20 74 68   only contain th
1370: 65 20 63 68 61 72 61 63 74 65 72 73 0d 0a 26 71  e characters..&q
1380: 75 6f 74 3b 26 23 39 31 3b 41 2d 5a 26 23 39 33  uot;&#91;A-Z&#93
1390: 3b 26 23 39 31 3b 61 2d 7a 26 23 39 33 3b 26 23  ;&#91;a-z&#93;&#
13a0: 39 31 3b 30 2d 39 26 23 39 33 3b 5f 26 71 75 6f  91;0-9&#93;_&quo
13b0: 74 3b 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  t; and must not 
13c0: 62 65 67 69 6e 20 77 69 74 68 20 61 20 64 69 67  begin with a dig
13d0: 69 74 2e 0d 0a 0d 0a 3c 70 3e 0d 0a 0d 0a 54 68  it.....<p>....Th
13e0: 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20  e initial value 
13f0: 66 6f 72 20 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20  for <b>-bus</b> 
1400: 69 73 20 73 65 73 73 69 6f 6e 2e 20 54 68 65 20  is session. The 
1410: 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 66 6f  initial value fo
1420: 72 0d 0a 3c 62 3e 2d 69 6e 74 65 72 66 61 63 65  r..<b>-interface
1430: 3c 2f 62 3e 20 69 73 20 74 61 6b 65 6e 20 66 72  </b> is taken fr
1440: 6f 6d 20 74 68 65 20 66 69 72 73 74 20 6e 61 6d  om the first nam
1450: 65 20 72 65 71 75 65 73 74 65 64 20 66 6f 72 20  e requested for 
1460: 74 68 65 0d 0a 61 70 70 6c 69 63 61 74 69 6f 6e  the..application
1470: 20 69 6e 20 61 20 3c 62 3e 64 62 69 66 3c 2f 62   in a <b>dbif</b
1480: 3e 20 3c 62 3e 63 6f 6e 6e 65 63 74 3c 2f 62 3e  > <b>connect</b>
1490: 20 63 6f 6d 6d 61 6e 64 2e 20 49 66 20 6e 6f 0d   command. If no.
14a0: 0a 6e 61 6d 65 20 77 61 73 20 65 76 65 72 20 72  .name was ever r
14b0: 65 71 75 65 73 74 65 64 20 77 69 74 68 20 74 68  equested with th
14c0: 65 20 63 6f 6e 6e 65 63 74 20 73 75 62 63 6f 6d  e connect subcom
14d0: 6d 61 6e 64 2c 20 69 74 20 64 65 66 61 75 6c 74  mand, it default
14e0: 73 20 74 6f 0d 0a 26 71 75 6f 74 3b 63 6f 6d 2e  s to..&quot;com.
14f0: 74 63 6c 63 6f 64 65 2e 64 65 66 61 75 6c 74 26  tclcode.default&
1500: 71 75 6f 74 3b 2e 0d 0a 3c 64 74 3e 3c 62 3e 64  quot;...<dt><b>d
1510: 62 69 66 3c 2f 62 3e 20 3c 62 3e 64 65 6c 65 74  bif</b> <b>delet
1520: 65 3c 2f 62 3e 20 3f 3c 62 3e 2d 62 75 73 3c 2f  e</b> ?<b>-bus</
1530: 62 3e 20 3c 69 3e 62 75 73 74 79 70 65 3c 2f 69  b> <i>bustype</i
1540: 3e 3f 20 3f 3c 62 3e 2d 69 6e 74 65 72 66 61 63  >? ?<b>-interfac
1550: 65 3c 2f 62 3e 20 3c 69 3e 69 6e 74 65 72 66 61  e</b> <i>interfa
1560: 63 65 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d 73 69 6e  ce</i>? ?<b>-sin
1570: 67 6c 65 3c 2f 62 3e 3f 20 3c 69 3e 70 61 74 68  gle</b>? <i>path
1580: 3c 2f 69 3e 0d 0a 3c 64 64 3e 57 68 69 6c 65 20  </i>..<dd>While 
1590: 74 68 65 72 65 20 63 75 72 72 65 6e 74 6c 79 20  there currently 
15a0: 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 72 65 6d  is no way to rem
15b0: 6f 76 65 20 69 6e 64 69 76 69 64 75 61 6c 20 73  ove individual s
15c0: 69 67 6e 61 6c 73 2c 20 6d 65 74 68 6f 64 73 2c  ignals, methods,
15d0: 20 6f 72 0d 0a 70 72 6f 70 65 72 74 69 65 73 20   or..properties 
15e0: 66 72 6f 6d 20 74 68 65 20 70 75 62 6c 69 73 68  from the publish
15f0: 65 64 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  ed interface, th
1600: 69 73 20 73 75 62 63 6f 6d 6d 61 6e 64 20 61 6c  is subcommand al
1610: 6c 6f 77 73 20 74 68 65 20 72 65 6d 6f 76 61 6c  lows the removal
1620: 0d 0a 6f 66 20 61 20 63 6f 6d 70 6c 65 74 65 20  ..of a complete 
1630: 6e 6f 64 65 2e 20 55 6e 6c 65 73 73 20 74 68 65  node. Unless the
1640: 20 3c 62 3e 2d 73 69 6e 67 6c 65 3c 2f 62 3e 20   <b>-single</b> 
1650: 6f 70 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66  option is specif
1660: 69 65 64 2c 20 74 68 65 0d 0a 63 6f 6d 6d 61 6e  ied, the..comman
1670: 64 20 77 69 6c 6c 20 61 6c 73 6f 20 72 65 63 75  d will also recu
1680: 72 73 69 76 65 6c 79 20 64 65 6c 65 74 65 20 6e  rsively delete n
1690: 6f 64 65 73 20 6f 6e 20 61 6c 6c 20 75 6e 64 65  odes on all unde
16a0: 72 6c 79 69 6e 67 20 6f 62 6a 65 63 74 20 70 61  rlying object pa
16b0: 74 68 73 2e 0d 0a 3c 64 74 3e 3c 62 3e 64 62 69  ths...<dt><b>dbi
16c0: 66 3c 2f 62 3e 20 3c 62 3e 65 72 72 6f 72 3c 2f  f</b> <b>error</
16d0: 62 3e 20 3c 69 3e 6d 65 73 73 61 67 65 49 44 3c  b> <i>messageID<
16e0: 2f 69 3e 20 3c 69 3e 65 72 72 6f 72 6d 65 73 73  /i> <i>errormess
16f0: 61 67 65 3c 2f 69 3e 20 3f 3c 69 3e 65 72 72 6f  age</i> ?<i>erro
1700: 72 6e 61 6d 65 3c 2f 69 3e 3f 0d 0a 3c 64 64 3e  rname</i>?..<dd>
1710: 53 65 6e 64 20 61 20 44 2d 42 75 73 20 65 72 72  Send a D-Bus err
1720: 6f 72 20 6d 65 73 73 61 67 65 20 69 6e 20 72 65  or message in re
1730: 73 70 6f 6e 73 65 20 74 6f 20 61 20 44 2d 42 75  sponse to a D-Bu
1740: 73 20 6d 65 74 68 6f 64 20 63 61 6c 6c 2e 20 49  s method call. I
1750: 66 20 74 68 65 0d 0a 3c 69 3e 65 72 72 6f 72 6e  f the..<i>errorn
1760: 61 6d 65 3c 2f 69 3e 20 61 72 67 75 6d 65 6e 74  ame</i> argument
1770: 20 69 73 20 6e 6f 74 20 73 70 65 63 69 66 69 65   is not specifie
1780: 64 2c 20 69 74 20 64 65 66 61 75 6c 74 73 20 74  d, it defaults t
1790: 6f 0d 0a 26 71 75 6f 74 3b 6f 72 67 2e 66 72 65  o..&quot;org.fre
17a0: 65 64 65 73 6b 74 6f 70 2e 44 42 75 73 2e 45 72  edesktop.DBus.Er
17b0: 72 6f 72 2e 46 61 69 6c 65 64 26 71 75 6f 74 3b  ror.Failed&quot;
17c0: 2e 0d 0a 3c 64 74 3e 3c 62 3e 64 62 69 66 3c 2f  ...<dt><b>dbif</
17d0: 62 3e 20 3c 62 3e 67 65 6e 65 72 61 74 65 3c 2f  b> <b>generate</
17e0: 62 3e 20 3c 69 3e 73 69 67 6e 61 6c 49 44 3c 2f  b> <i>signalID</
17f0: 69 3e 20 3f 3c 69 3e 61 72 67 3c 2f 69 3e 20 2e  i> ?<i>arg</i> .
1800: 2e 2e 3f 0d 0a 3c 64 64 3e 47 65 6e 65 72 61 74  ..?..<dd>Generat
1810: 65 20 61 20 73 69 67 6e 61 6c 20 61 73 20 64 65  e a signal as de
1820: 66 69 6e 65 64 20 62 79 20 61 20 70 72 65 76 69  fined by a previ
1830: 6f 75 73 20 3c 62 3e 64 62 69 66 3c 2f 62 3e 20  ous <b>dbif</b> 
1840: 0d 0a 3c 62 3e 73 69 67 6e 61 6c 3c 2f 62 3e 20  ..<b>signal</b> 
1850: 63 6f 6d 6d 61 6e 64 2e 20 49 66 20 61 20 62 6f  command. If a bo
1860: 64 79 20 77 61 73 20 73 70 65 63 69 66 69 65 64  dy was specified
1870: 20 77 69 74 68 20 74 68 65 20 73 69 67 6e 61 6c   with the signal
1880: 20 64 65 66 69 6e 69 74 69 6f 6e 2c 0d 0a 74 68   definition,..th
1890: 65 20 70 72 6f 76 69 64 65 64 20 61 72 67 75 6d  e provided argum
18a0: 65 6e 74 73 20 6d 75 73 74 20 6d 61 74 63 68 20  ents must match 
18b0: 74 68 65 20 61 72 67 73 20 64 65 66 69 6e 69 74  the args definit
18c0: 69 6f 6e 20 66 6f 72 20 74 68 65 20 62 6f 64 79  ion for the body
18d0: 2e 20 4f 74 68 65 72 77 69 73 65 0d 0a 74 68 65  . Otherwise..the
18e0: 79 20 6d 75 73 74 20 6d 61 74 63 68 20 74 68 65  y must match the
18f0: 20 61 72 67 6c 69 73 74 20 73 70 65 63 69 66 69   arglist specifi
1900: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 64 65  ed during the de
1910: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 74 68 65 20  finition of the 
1920: 73 69 67 6e 61 6c 2e 0d 0a 3c 64 74 3e 3c 62 3e  signal...<dt><b>
1930: 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 67 65 74 3c  dbif</b> <b>get<
1940: 2f 62 3e 20 3c 69 3e 6d 65 73 73 61 67 65 49 44  /b> <i>messageID
1950: 3c 2f 69 3e 20 3c 69 3e 6e 61 6d 65 3c 2f 69 3e  </i> <i>name</i>
1960: 0d 0a 3c 64 64 3e 41 63 63 65 73 73 20 61 64 64  ..<dd>Access add
1970: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
1980: 69 6f 6e 20 61 62 6f 75 74 20 61 20 44 2d 42 75  ion about a D-Bu
1990: 73 20 6d 65 73 73 61 67 65 2e 20 52 65 63 6f 67  s message. Recog
19a0: 6e 69 7a 65 64 20 6e 61 6d 65 73 20 61 72 65 0d  nized names are.
19b0: 0a 3c 69 3e 62 75 73 3c 2f 69 3e 2c 20 3c 69 3e  .<i>bus</i>, <i>
19c0: 6d 65 6d 62 65 72 3c 2f 69 3e 2c 20 3c 69 3e 69  member</i>, <i>i
19d0: 6e 74 65 72 66 61 63 65 3c 2f 69 3e 2c 20 3c 69  nterface</i>, <i
19e0: 3e 70 61 74 68 3c 2f 69 3e 2c 20 3c 69 3e 73 65  >path</i>, <i>se
19f0: 6e 64 65 72 3c 2f 69 3e 2c 0d 0a 3c 69 3e 64 65  nder</i>,..<i>de
1a00: 73 74 69 6e 61 74 69 6f 6e 3c 2f 69 3e 2c 20 3c  stination</i>, <
1a10: 69 3e 6d 65 73 73 61 67 65 74 79 70 65 3c 2f 69  i>messagetype</i
1a20: 3e 2c 20 3c 69 3e 73 69 67 6e 61 74 75 72 65 3c  >, <i>signature<
1a30: 2f 69 3e 2c 20 3c 69 3e 73 65 72 69 61 6c 3c 2f  /i>, <i>serial</
1a40: 69 3e 2c 0d 0a 3c 69 3e 72 65 70 6c 79 73 65 72  i>,..<i>replyser
1a50: 69 61 6c 3c 2f 69 3e 2c 20 3c 69 3e 6e 6f 72 65  ial</i>, <i>nore
1a60: 70 6c 79 3c 2f 69 3e 2c 20 3c 69 3e 61 75 74 6f  ply</i>, <i>auto
1a70: 73 74 61 72 74 3c 2f 69 3e 2c 20 61 6e 64 20 3c  start</i>, and <
1a80: 69 3e 65 72 72 6f 72 6e 61 6d 65 3c 2f 69 3e 2e  i>errorname</i>.
1a90: 0d 0a 3c 64 74 3e 3c 62 3e 64 62 69 66 3c 2f 62  ..<dt><b>dbif</b
1aa0: 3e 20 3c 62 3e 6c 69 73 74 65 6e 3c 2f 62 3e 20  > <b>listen</b> 
1ab0: 3f 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20 3c 69 3e  ?<b>-bus</b> <i>
1ac0: 62 75 73 74 79 70 65 3c 2f 69 3e 3f 20 3f 3c 62  bustype</i>? ?<b
1ad0: 3e 2d 69 6e 74 65 72 66 61 63 65 3c 2f 62 3e 20  >-interface</b> 
1ae0: 3c 69 3e 69 6e 74 65 72 66 61 63 65 3c 2f 69 3e  <i>interface</i>
1af0: 3f 20 3c 69 3e 70 61 74 68 3c 2f 69 3e 20 3c 69  ? <i>path</i> <i
1b00: 3e 6e 61 6d 65 3c 2f 69 3e 20 3f 3c 69 3e 61 72  >name</i> ?<i>ar
1b10: 67 6c 69 73 74 3c 2f 69 3e 3f 20 3f 3c 69 3e 69  glist</i>? ?<i>i
1b20: 6e 74 65 72 70 3c 2f 69 3e 3f 20 3c 69 3e 62 6f  nterp</i>? <i>bo
1b30: 64 79 3c 2f 69 3e 0d 0a 3c 64 64 3e 53 74 61 72  dy</i>..<dd>Star
1b40: 74 20 6c 69 73 74 65 6e 69 6e 67 20 66 6f 72 20  t listening for 
1b50: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 73 69  the specified si
1b60: 67 6e 61 6c 20 61 6e 64 20 65 78 65 63 75 74 65  gnal and execute
1b70: 20 3c 69 3e 62 6f 64 79 3c 2f 69 3e 20 77 68 65   <i>body</i> whe
1b80: 6e 20 73 75 63 68 20 61 0d 0a 73 69 67 6e 61 6c  n such a..signal
1b90: 20 61 70 70 65 61 72 73 20 6f 6e 20 74 68 65 20   appears on the 
1ba0: 44 2d 42 75 73 2e 0d 0a 0d 0a 3c 70 3e 0d 0a 0d  D-Bus.....<p>...
1bb0: 0a 54 68 65 20 63 6f 64 65 20 69 6e 20 3c 69 3e  .The code in <i>
1bc0: 62 6f 64 79 3c 2f 69 3e 20 77 69 6c 6c 20 62 65  body</i> will be
1bd0: 20 65 78 65 63 75 74 65 64 20 69 6e 20 74 68 65   executed in the
1be0: 20 6e 61 6d 65 73 70 61 63 65 20 74 68 65 0d 0a   namespace the..
1bf0: 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 6c  <b>dbif</b> <b>l
1c00: 69 73 74 65 6e 3c 2f 62 3e 20 63 6f 6d 6d 61 6e  isten</b> comman
1c10: 64 20 77 61 73 20 69 73 73 75 65 64 20 66 72 6f  d was issued fro
1c20: 6d 2e 0d 0a 0d 0a 54 68 65 20 3c 69 3e 61 72 67  m.....The <i>arg
1c30: 6c 69 73 74 3c 2f 69 3e 20 61 72 67 75 6d 65 6e  list</i> argumen
1c40: 74 20 66 6f 6c 6c 6f 77 73 20 74 68 65 20 73 70  t follows the sp
1c50: 65 63 69 61 6c 20 72 75 6c 65 73 20 66 6f 72 20  ecial rules for 
1c60: 64 62 69 66 0d 0a 61 72 67 75 6d 65 6e 74 20 6c  dbif..argument l
1c70: 69 73 74 73 2e 20 53 65 65 20 3c 62 3e 41 52 47  ists. See <b>ARG
1c80: 55 4d 45 4e 54 20 4c 49 53 54 53 3c 2f 62 3e 20  UMENT LISTS</b> 
1c90: 62 65 6c 6f 77 20 66 6f 72 20 6d 6f 72 65 20 69  below for more i
1ca0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0d 0a 3c 64 74  nformation...<dt
1cb0: 3e 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e  ><b>dbif</b> <b>
1cc0: 6d 65 74 68 6f 64 3c 2f 62 3e 20 3f 3c 62 3e 2d  method</b> ?<b>-
1cd0: 61 74 74 72 69 62 75 74 65 73 3c 2f 62 3e 20 3c  attributes</b> <
1ce0: 69 3e 61 74 74 72 69 62 75 74 65 73 3c 2f 69 3e  i>attributes</i>
1cf0: 3f 20 3f 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20 3c  ? ?<b>-bus</b> <
1d00: 69 3e 62 75 73 74 79 70 65 3c 2f 69 3e 3f 20 3f  i>bustype</i>? ?
1d10: 3c 62 3e 2d 69 6e 74 65 72 66 61 63 65 3c 2f 62  <b>-interface</b
1d20: 3e 20 3c 69 3e 69 6e 74 65 72 66 61 63 65 3c 2f  > <i>interface</
1d30: 69 3e 3f 20 3c 69 3e 70 61 74 68 3c 2f 69 3e 20  i>? <i>path</i> 
1d40: 3c 69 3e 6e 61 6d 65 3c 2f 69 3e 20 3f 3c 69 3e  <i>name</i> ?<i>
1d50: 69 6e 70 75 74 61 72 67 73 3c 2f 69 3e 20 3f 3c  inputargs</i> ?<
1d60: 69 3e 6f 75 74 70 75 74 61 72 67 73 3c 2f 69 3e  i>outputargs</i>
1d70: 3f 3f 20 3f 3c 69 3e 69 6e 74 65 72 70 3c 2f 69  ?? ?<i>interp</i
1d80: 3e 3f 20 3c 69 3e 62 6f 64 79 3c 2f 69 3e 0d 0a  >? <i>body</i>..
1d90: 3c 64 64 3e 44 65 66 69 6e 65 20 61 20 6d 65 74  <dd>Define a met
1da0: 68 6f 64 20 74 68 61 74 20 6d 61 79 20 62 65 20  hod that may be 
1db0: 61 63 63 65 73 73 65 64 20 74 68 72 6f 75 67 68  accessed through
1dc0: 20 74 68 65 20 44 2d 42 75 73 20 61 6e 64 20 65   the D-Bus and e
1dd0: 78 65 63 75 74 65 20 3c 69 3e 62 6f 64 79 3c 2f  xecute <i>body</
1de0: 69 3e 0d 0a 77 68 65 6e 20 74 68 65 20 6d 65 74  i>..when the met
1df0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  hod is invoked. 
1e00: 0d 0a 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  ..In addition to
1e10: 20 76 61 6c 69 64 20 64 62 75 73 20 70 61 74 68   valid dbus path
1e20: 73 2c 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  s, an empty stri
1e30: 6e 67 20 6d 61 79 20 62 65 20 73 70 65 63 69 66  ng may be specif
1e40: 69 65 64 20 66 6f 72 20 74 68 65 0d 0a 3c 69 3e  ied for the..<i>
1e50: 70 61 74 68 3c 2f 69 3e 20 61 72 67 75 6d 65 6e  path</i> argumen
1e60: 74 2e 20 54 68 69 73 20 6d 61 6b 65 73 20 74 68  t. This makes th
1e70: 65 20 6d 65 74 68 6f 64 20 61 76 61 69 6c 61 62  e method availab
1e80: 6c 65 20 6f 6e 20 61 6c 6c 20 70 61 74 68 73 2e  le on all paths.
1e90: 0d 0a 54 68 65 20 3c 69 3e 69 6e 70 75 74 61 72  ..The <i>inputar
1ea0: 67 73 3c 2f 69 3e 20 61 72 67 75 6d 65 6e 74 20  gs</i> argument 
1eb0: 73 70 65 63 69 66 69 65 73 20 77 68 69 63 68 20  specifies which 
1ec0: 61 72 67 75 6d 65 6e 74 73 20 6d 75 73 74 20 62  arguments must b
1ed0: 65 20 70 72 6f 76 69 64 65 64 20 62 79 0d 0a 74  e provided by..t
1ee0: 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 3c  he caller. The <
1ef0: 69 3e 6f 75 74 70 75 74 61 72 67 73 3c 2f 69 3e  i>outputargs</i>
1f00: 20 61 72 67 75 6d 65 6e 74 20 69 6e 64 69 63 61   argument indica
1f10: 74 65 73 20 74 68 65 20 74 79 70 65 20 6f 66 20  tes the type of 
1f20: 72 65 73 75 6c 74 20 74 68 65 0d 0a 6d 65 74 68  result the..meth
1f30: 6f 64 20 72 65 74 75 72 6e 73 2e 0d 0a 0d 0a 3c  od returns.....<
1f40: 70 3e 0d 0a 0d 0a 41 74 74 72 69 62 75 74 65 73  p>....Attributes
1f50: 20 6d 61 79 20 62 65 20 73 70 65 63 69 66 69 65   may be specifie
1f60: 64 20 76 69 61 20 74 68 65 20 3c 62 3e 2d 61 74  d via the <b>-at
1f70: 74 72 69 62 75 74 65 73 3c 2f 62 3e 20 6f 70 74  tributes</b> opt
1f80: 69 6f 6e 20 74 6f 20 70 72 6f 76 69 64 65 0d 0a  ion to provide..
1f90: 68 69 6e 74 73 20 74 6f 20 75 73 65 72 73 20 6f  hints to users o
1fa0: 66 20 79 6f 75 72 20 41 50 49 2e 0d 0a 53 65 65  f your API...See
1fb0: 20 3c 62 3e 41 54 54 52 49 42 55 54 45 53 3c 2f   <b>ATTRIBUTES</
1fc0: 62 3e 20 62 65 6c 6f 77 20 66 6f 72 20 6d 6f 72  b> below for mor
1fd0: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0d 0a  e information...
1fe0: 0d 0a 3c 70 3e 0d 0a 0d 0a 54 68 65 20 72 65 74  ..<p>....The ret
1ff0: 75 72 6e 20 76 61 6c 75 65 20 72 65 73 75 6c 74  urn value result
2000: 69 6e 67 20 66 72 6f 6d 20 65 78 65 63 75 74 69  ing from executi
2010: 6e 67 20 74 68 65 20 62 6f 64 79 20 77 69 6c 6c  ng the body will
2020: 20 6e 6f 72 6d 61 6c 6c 79 20 62 65 20 72 65 74   normally be ret
2030: 75 72 6e 65 64 0d 0a 74 6f 20 74 68 65 20 63 61  urned..to the ca
2040: 6c 6c 65 72 20 69 6e 20 61 20 44 2d 42 75 73 20  ller in a D-Bus 
2050: 72 65 74 75 72 6e 20 6d 65 73 73 61 67 65 2e 20  return message. 
2060: 49 66 20 61 6e 20 75 6e 63 61 75 67 68 74 20 65  If an uncaught e
2070: 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 72 20 74  rror occurs or t
2080: 68 65 0d 0a 72 65 73 75 6c 74 20 6f 66 20 62 6f  he..result of bo
2090: 64 79 20 64 6f 65 73 6e 27 74 20 6d 61 74 63 68  dy doesn't match
20a0: 20 3c 69 3e 6f 75 74 70 75 74 61 72 67 73 3c 2f   <i>outputargs</
20b0: 69 3e 2c 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  i>, an error mes
20c0: 73 61 67 65 20 77 69 6c 6c 20 62 65 0d 0a 72 65  sage will be..re
20d0: 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
20e0: 6c 6c 65 72 20 69 6e 73 74 65 61 64 2e 0d 0a 0d  ller instead....
20f0: 0a 3c 70 3e 0d 0a 0d 0a 54 68 65 20 62 6f 64 79  .<p>....The body
2100: 20 63 6f 64 65 20 72 65 63 6f 67 6e 69 7a 65 73   code recognizes
2110: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 3c   an additional <
2120: 62 3e 2d 61 73 79 6e 63 3c 2f 62 3e 20 6f 70 74  b>-async</b> opt
2130: 69 6f 6e 20 66 6f 72 20 74 68 65 20 54 63 6c 0d  ion for the Tcl.
2140: 0a 3c 62 3e 72 65 74 75 72 6e 3c 2f 62 3e 20 63  .<b>return</b> c
2150: 6f 6d 6d 61 6e 64 2e 20 57 68 65 6e 20 74 68 61  ommand. When tha
2160: 74 20 6f 70 74 69 6f 6e 20 69 73 20 73 70 65 63  t option is spec
2170: 69 66 69 65 64 20 77 69 74 68 20 61 20 74 72 75  ified with a tru
2180: 65 20 62 6f 6f 6c 65 61 6e 0d 0a 76 61 6c 75 65  e boolean..value
2190: 20 28 3c 62 20 63 6c 61 73 73 3d 22 63 6f 6e 73   (<b class="cons
21a0: 74 22 3e 74 72 75 65 3c 2f 62 3e 2c 20 3c 62 20  t">true</b>, <b 
21b0: 63 6c 61 73 73 3d 22 63 6f 6e 73 74 22 3e 79 65  class="const">ye
21c0: 73 3c 2f 62 3e 2c 20 3c 62 20 63 6c 61 73 73 3d  s</b>, <b class=
21d0: 22 63 6f 6e 73 74 22 3e 31 3c 2f 62 3e 29 2c 20  "const">1</b>), 
21e0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
21f0: 20 66 72 6f 6d 20 74 68 65 20 62 6f 64 79 0d 0a   from the body..
2200: 77 69 6c 6c 20 6e 6f 74 20 61 75 74 6f 6d 61 74  will not automat
2210: 69 63 61 6c 6c 79 20 62 65 20 72 65 74 75 72 6e  ically be return
2220: 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
2230: 2e 20 41 20 72 65 73 70 6f 6e 73 65 20 6d 65 73  . A response mes
2240: 73 61 67 65 20 73 68 6f 75 6c 64 0d 0a 74 68 65  sage should..the
2250: 6e 20 62 65 20 67 65 6e 65 72 61 74 65 64 20 75  n be generated u
2260: 73 69 6e 67 20 74 68 65 20 3c 62 3e 64 62 69 66  sing the <b>dbif
2270: 3c 2f 62 3e 20 3c 62 3e 72 65 74 75 72 6e 3c 2f  </b> <b>return</
2280: 62 3e 20 6f 72 0d 0a 3c 62 3e 64 62 69 66 3c 2f  b> or..<b>dbif</
2290: 62 3e 20 3c 62 3e 65 72 72 6f 72 3c 2f 62 3e 20  b> <b>error</b> 
22a0: 73 75 62 63 6f 6d 6d 61 6e 64 73 2e 0d 0a 0d 0a  subcommands.....
22b0: 3c 70 3e 0d 0a 0d 0a 41 6e 20 61 64 64 69 74 69  <p>....An additi
22c0: 6f 6e 61 6c 20 76 61 72 69 61 62 6c 65 20 3c 62  onal variable <b
22d0: 3e 6d 73 67 69 64 3c 2f 62 3e 20 77 69 6c 6c 20  >msgid</b> will 
22e0: 62 65 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  be passed to the
22f0: 20 6d 65 74 68 6f 64 20 62 6f 64 79 2e 20 54 68   method body. Th
2300: 69 73 0d 0a 76 61 72 69 61 62 6c 65 20 63 6f 6e  is..variable con
2310: 74 61 69 6e 73 20 61 20 6d 65 73 73 61 67 65 49  tains a messageI
2320: 44 20 74 68 61 74 20 6d 61 79 20 62 65 20 75 73  D that may be us
2330: 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2340: 6e 20 77 69 74 68 20 74 68 65 0d 0a 3c 62 3e 67  n with the..<b>g
2350: 65 74 3c 2f 62 3e 2c 20 3c 62 3e 72 65 74 75 72  et</b>, <b>retur
2360: 6e 3c 2f 62 3e 2c 20 6f 72 20 3c 62 3e 65 72 72  n</b>, or <b>err
2370: 6f 72 3c 2f 62 3e 20 73 75 62 63 6f 6d 6d 61 6e  or</b> subcomman
2380: 64 73 2e 20 54 68 65 20 6d 65 73 73 61 67 65 49  ds. The messageI
2390: 44 0d 0a 72 65 6d 61 69 6e 73 20 76 61 6c 69 64  D..remains valid
23a0: 20 66 6f 72 20 61 20 70 65 72 69 6f 64 20 6f 66   for a period of
23b0: 20 74 69 6d 65 20 28 64 65 66 61 75 6c 74 20 32   time (default 2
23c0: 35 20 73 65 63 6f 6e 64 73 29 2c 20 6f 72 20 75  5 seconds), or u
23d0: 6e 74 69 6c 20 61 20 72 65 73 70 6f 6e 73 65 0d  ntil a response.
23e0: 0a 68 61 73 20 62 65 65 6e 20 72 65 74 75 72 6e  .has been return
23f0: 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
2400: 2c 20 77 68 69 63 68 65 76 65 72 20 68 61 70 70  , whichever happ
2410: 65 6e 73 20 66 69 72 73 74 2e 0d 0a 0d 0a 3c 70  ens first.....<p
2420: 3e 0d 0a 0d 0a 54 68 65 20 63 6f 64 65 20 69 6e  >....The code in
2430: 20 3c 69 3e 62 6f 64 79 3c 2f 69 3e 20 77 69 6c   <i>body</i> wil
2440: 6c 20 62 65 20 65 78 65 63 75 74 65 64 20 69 6e  l be executed in
2450: 20 74 68 65 20 6e 61 6d 65 73 70 61 63 65 20 74   the namespace t
2460: 68 65 0d 0a 3c 62 3e 64 62 69 66 3c 2f 62 3e 20  he..<b>dbif</b> 
2470: 3c 62 3e 6d 65 74 68 6f 64 3c 2f 62 3e 20 63 6f  <b>method</b> co
2480: 6d 6d 61 6e 64 20 77 61 73 20 69 73 73 75 65 64  mmand was issued
2490: 20 66 72 6f 6d 2e 0d 0a 0d 0a 54 68 65 20 3c 69   from.....The <i
24a0: 3e 69 6e 70 75 74 61 72 67 73 3c 2f 69 3e 20 61  >inputargs</i> a
24b0: 6e 64 20 3c 69 3e 6f 75 74 70 75 74 61 72 67 73  nd <i>outputargs
24c0: 3c 2f 69 3e 20 61 72 67 75 6d 65 6e 74 73 20 66  </i> arguments f
24d0: 6f 6c 6c 6f 77 20 74 68 65 20 73 70 65 63 69 61  ollow the specia
24e0: 6c 20 72 75 6c 65 73 0d 0a 66 6f 72 20 64 62 69  l rules..for dbi
24f0: 66 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 73  f argument lists
2500: 2e 0d 0a 53 65 65 20 3c 62 3e 41 52 47 55 4d 45  ...See <b>ARGUME
2510: 4e 54 20 4c 49 53 54 53 3c 2f 62 3e 20 62 65 6c  NT LISTS</b> bel
2520: 6f 77 20 66 6f 72 20 6d 6f 72 65 20 69 6e 66 6f  ow for more info
2530: 72 6d 61 74 69 6f 6e 2e 0d 0a 3c 64 74 3e 3c 62  rmation...<dt><b
2540: 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 70 61 76  >dbif</b> <b>pav
2550: 65 3c 2f 62 3e 20 3f 3c 62 3e 2d 62 75 73 3c 2f  e</b> ?<b>-bus</
2560: 62 3e 20 3c 69 3e 62 75 73 74 79 70 65 3c 2f 69  b> <i>bustype</i
2570: 3e 3f 20 3f 3c 62 3e 2d 69 6e 74 65 72 66 61 63  >? ?<b>-interfac
2580: 65 3c 2f 62 3e 20 3c 69 3e 69 6e 74 65 72 66 61  e</b> <i>interfa
2590: 63 65 3c 2f 69 3e 3f 20 3c 69 3e 70 61 74 68 3c  ce</i>? <i>path<
25a0: 2f 69 3e 0d 0a 3c 64 64 3e 43 72 65 61 74 65 20  /i>..<dd>Create 
25b0: 61 20 70 61 74 68 2e 20 4e 6f 72 6d 61 6c 6c 79  a path. Normally
25c0: 20 61 20 70 61 74 68 20 69 73 20 61 75 74 6f 6d   a path is autom
25d0: 61 74 69 63 61 6c 6c 79 20 63 72 65 61 74 65 64  atically created
25e0: 20 77 68 65 6e 20 61 20 70 72 6f 70 65 72 74 79   when a property
25f0: 2c 0d 0a 6d 65 74 68 6f 64 2c 20 6f 72 20 73 69  ,..method, or si
2600: 67 6e 61 6c 20 69 73 20 64 65 66 69 6e 65 64 20  gnal is defined 
2610: 6f 6e 20 74 68 61 74 20 70 61 74 68 2e 20 54 68  on that path. Th
2620: 69 73 20 63 6f 6d 6d 61 6e 64 20 69 73 20 69 6e  is command is in
2630: 74 65 6e 64 65 64 20 66 6f 72 20 70 61 74 68 73  tended for paths
2640: 0d 0a 74 68 61 74 20 6f 6e 6c 79 20 68 61 76 65  ..that only have
2650: 20 75 6e 69 76 65 72 73 61 6c 20 6d 65 74 68 6f   universal metho
2660: 64 73 20 61 6e 64 2f 6f 72 20 73 69 67 6e 61 6c  ds and/or signal
2670: 73 20 28 69 2e 65 2e 20 6d 65 74 68 6f 64 73 20  s (i.e. methods 
2680: 61 6e 64 2f 6f 72 20 73 69 67 6e 61 6c 73 0d 0a  and/or signals..
2690: 74 68 61 74 20 61 72 65 20 64 65 66 69 6e 65 64  that are defined
26a0: 20 77 69 74 68 20 61 6e 20 65 6d 70 74 79 20 73   with an empty s
26b0: 74 72 69 6e 67 20 61 73 20 74 68 65 69 72 20 70  tring as their p
26c0: 61 74 68 29 2e 0d 0a 3c 64 74 3e 3c 62 3e 64 62  ath)...<dt><b>db
26d0: 69 66 3c 2f 62 3e 20 3c 62 3e 70 72 6f 70 65 72  if</b> <b>proper
26e0: 74 79 3c 2f 62 3e 20 3f 3c 62 3e 2d 61 63 63 65  ty</b> ?<b>-acce
26f0: 73 73 3c 2f 62 3e 20 3c 69 3e 6d 6f 64 65 3c 2f  ss</b> <i>mode</
2700: 69 3e 3f 20 3f 3c 62 3e 2d 61 74 74 72 69 62 75  i>? ?<b>-attribu
2710: 74 65 73 3c 2f 62 3e 20 3c 69 3e 61 74 74 72 69  tes</b> <i>attri
2720: 62 75 74 65 73 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d  butes</i>? ?<b>-
2730: 62 75 73 3c 2f 62 3e 20 3c 69 3e 62 75 73 74 79  bus</b> <i>busty
2740: 70 65 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d 69 6e 74  pe</i>? ?<b>-int
2750: 65 72 66 61 63 65 3c 2f 62 3e 20 3c 69 3e 69 6e  erface</b> <i>in
2760: 74 65 72 66 61 63 65 3c 2f 69 3e 3f 20 3c 69 3e  terface</i>? <i>
2770: 70 61 74 68 3c 2f 69 3e 20 3c 69 3e 6e 61 6d 65  path</i> <i>name
2780: 3c 2f 69 3e 3f 3a 3c 69 3e 73 69 67 6e 61 74 75  </i>?:<i>signatu
2790: 72 65 3c 2f 69 3e 3f 20 3c 69 3e 76 61 72 69 61  re</i>? <i>varia
27a0: 62 6c 65 3c 2f 69 3e 20 3f 3f 3c 69 3e 69 6e 74  ble</i> ??<i>int
27b0: 65 72 70 3c 2f 69 3e 3f 20 3c 69 3e 62 6f 64 79  erp</i>? <i>body
27c0: 3c 2f 69 3e 3f 0d 0a 3c 64 64 3e 44 65 66 69 6e  </i>?..<dd>Defin
27d0: 65 20 61 20 70 72 6f 70 65 72 74 79 20 74 68 61  e a property tha
27e0: 74 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  t may be accesse
27f0: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 44 2d  d through the D-
2800: 42 75 73 20 75 73 69 6e 67 20 6d 65 74 68 6f 64  Bus using method
2810: 73 20 64 65 66 69 6e 65 64 20 0d 0a 62 79 20 74  s defined ..by t
2820: 68 65 20 6f 72 67 2e 66 72 65 65 64 65 73 6b 74  he org.freedeskt
2830: 6f 70 2e 44 42 75 73 2e 50 72 6f 70 65 72 74 69  op.DBus.Properti
2840: 65 73 20 73 74 61 6e 64 61 72 64 20 69 6e 74 65  es standard inte
2850: 72 66 61 63 65 2e 20 54 68 65 20 3c 69 3e 76 61  rface. The <i>va
2860: 72 69 61 62 6c 65 3c 2f 69 3e 0d 0a 61 72 67 75  riable</i>..argu
2870: 6d 65 6e 74 20 64 65 66 69 6e 65 73 20 74 68 65  ment defines the
2880: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
2890: 20 68 6f 6c 64 69 6e 67 20 74 68 65 20 76 61 6c   holding the val
28a0: 75 65 20 6f 66 20 74 68 65 20 70 72 6f 70 65 72  ue of the proper
28b0: 74 79 2e 0d 0a 0d 0a 54 68 65 20 3c 69 3e 73 69  ty.....The <i>si
28c0: 67 6e 61 74 75 72 65 3c 2f 69 3e 20 6f 66 20 61  gnature</i> of a
28d0: 20 70 72 6f 70 65 72 74 79 20 6d 75 73 74 20 62   property must b
28e0: 65 20 61 20 73 69 6e 67 6c 65 20 63 6f 6d 70 6c  e a single compl
28f0: 65 74 65 20 74 79 70 65 2e 0d 0a 3c 70 3e 0d 0a  ete type...<p>..
2900: 0d 0a 54 68 65 20 3c 62 3e 2d 61 63 63 65 73 73  ..The <b>-access
2910: 3c 2f 62 3e 20 6f 70 74 69 6f 6e 20 73 70 65 63  </b> option spec
2920: 69 66 69 65 73 20 77 68 65 74 68 65 72 20 74 68  ifies whether th
2930: 65 20 70 72 6f 70 65 72 74 79 20 63 61 6e 20 62  e property can b
2940: 65 20 76 69 65 77 65 64 0d 0a 61 6e 64 2f 6f 72  e viewed..and/or
2950: 20 6d 6f 64 69 66 69 65 64 20 74 68 72 6f 75 67   modified throug
2960: 68 20 74 68 65 20 44 2d 42 75 73 2e 20 56 61 6c  h the D-Bus. Val
2970: 69 64 20 61 63 63 65 73 73 20 6d 6f 64 65 73 20  id access modes 
2980: 61 72 65 20 3c 62 20 63 6c 61 73 73 3d 22 63 6f  are <b class="co
2990: 6e 73 74 22 3e 72 65 61 64 3c 2f 62 3e 2c 0d 0a  nst">read</b>,..
29a0: 3c 62 20 63 6c 61 73 73 3d 22 63 6f 6e 73 74 22  <b class="const"
29b0: 3e 77 72 69 74 65 3c 2f 62 3e 2c 20 61 6e 64 20  >write</b>, and 
29c0: 3c 62 20 63 6c 61 73 73 3d 22 63 6f 6e 73 74 22  <b class="const"
29d0: 3e 72 65 61 64 77 72 69 74 65 3c 2f 62 3e 2e 20  >readwrite</b>. 
29e0: 49 66 20 6e 6f 20 61 63 63 65 73 73 20 6d 6f 64  If no access mod
29f0: 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  e is specified, 
2a00: 69 74 0d 0a 64 65 66 61 75 6c 74 73 20 74 6f 20  it..defaults to 
2a10: 72 65 61 64 77 72 69 74 65 2e 0d 0a 0d 0a 3c 70  readwrite.....<p
2a20: 3e 0d 0a 0d 0a 41 74 74 72 69 62 75 74 65 73 20  >....Attributes 
2a30: 6d 61 79 20 62 65 20 73 70 65 63 69 66 69 65 64  may be specified
2a40: 20 76 69 61 20 74 68 65 20 3c 62 3e 2d 61 74 74   via the <b>-att
2a50: 72 69 62 75 74 65 73 3c 2f 62 3e 20 6f 70 74 69  ributes</b> opti
2a60: 6f 6e 20 74 6f 20 70 72 6f 76 69 64 65 0d 0a 68  on to provide..h
2a70: 69 6e 74 73 20 74 6f 20 75 73 65 72 73 20 6f 66  ints to users of
2a80: 20 79 6f 75 72 20 41 50 49 2e 0d 0a 53 65 65 20   your API...See 
2a90: 3c 62 3e 41 54 54 52 49 42 55 54 45 53 3c 2f 62  <b>ATTRIBUTES</b
2aa0: 3e 20 62 65 6c 6f 77 20 66 6f 72 20 6d 6f 72 65  > below for more
2ab0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0d 0a 0d   information....
2ac0: 0a 3c 70 3e 0d 0a 0d 0a 54 68 65 20 63 6f 64 65  .<p>....The code
2ad0: 20 69 6e 20 74 68 65 20 6f 70 74 69 6f 6e 61 6c   in the optional
2ae0: 20 3c 69 3e 62 6f 64 79 3c 2f 69 3e 20 61 72 67   <i>body</i> arg
2af0: 75 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 65 78  ument will be ex
2b00: 65 63 75 74 65 64 20 77 68 65 6e 20 74 68 65 0d  ecuted when the.
2b10: 0a 70 72 6f 70 65 72 74 79 20 69 73 20 6d 6f 64  .property is mod
2b20: 69 66 69 65 64 20 74 68 72 6f 75 67 68 20 74 68  ified through th
2b30: 65 20 44 2d 42 75 73 2e 20 44 75 72 69 6e 67 20  e D-Bus. During 
2b40: 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
2b50: 20 3c 69 3e 62 6f 64 79 3c 2f 69 3e 0d 0a 74 68   <i>body</i>..th
2b60: 65 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  e global variabl
2b70: 65 20 77 69 6c 6c 20 73 74 69 6c 6c 20 68 61 76  e will still hav
2b80: 65 20 69 74 73 20 6f 72 69 67 69 6e 61 6c 20 76  e its original v
2b90: 61 6c 75 65 2c 20 69 66 20 61 6e 79 2e 20 54 68  alue, if any. Th
2ba0: 65 20 6e 65 77 0d 0a 76 61 6c 75 65 20 66 6f 72  e new..value for
2bb0: 20 74 68 65 20 70 72 6f 70 65 72 74 79 20 69 73   the property is
2bc0: 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 73   passed to the s
2bd0: 63 72 69 70 74 20 61 73 20 61 6e 20 61 72 67 75  cript as an argu
2be0: 6d 65 6e 74 20 77 69 74 68 20 74 68 65 20 73 61  ment with the sa
2bf0: 6d 65 0d 0a 6e 61 6d 65 20 61 73 20 74 68 65 20  me..name as the 
2c00: 70 72 6f 70 65 72 74 79 2e 20 49 66 20 65 78 65  property. If exe
2c10: 63 75 74 69 6f 6e 20 6f 66 20 3c 69 3e 62 6f 64  cution of <i>bod
2c20: 79 3c 2f 69 3e 20 72 65 73 75 6c 74 73 20 69 6e  y</i> results in
2c30: 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 0d 0a   an error, the..
2c40: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
2c50: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 6d 6f 64 69  will not be modi
2c60: 66 69 65 64 2e 20 54 68 69 73 20 61 6c 6c 6f 77  fied. This allow
2c70: 73 20 72 65 73 74 72 69 63 74 69 6f 6e 73 20 74  s restrictions t
2c80: 6f 20 62 65 20 69 6d 70 6f 73 65 64 0d 0a 6f 6e  o be imposed..on
2c90: 20 74 68 65 20 76 61 6c 75 65 20 66 6f 72 20 74   the value for t
2ca0: 68 65 20 70 72 6f 70 65 72 74 79 2e 0d 0a 0d 0a  he property.....
2cb0: 3c 70 3e 0d 0a 0d 0a 54 68 65 20 63 6f 64 65 20  <p>....The code 
2cc0: 69 6e 20 3c 69 3e 62 6f 64 79 3c 2f 69 3e 20 77  in <i>body</i> w
2cd0: 69 6c 6c 20 62 65 20 65 78 65 63 75 74 65 64 20  ill be executed 
2ce0: 69 6e 20 74 68 65 20 6e 61 6d 65 73 70 61 63 65  in the namespace
2cf0: 20 74 68 65 0d 0a 3c 62 3e 64 62 69 66 3c 2f 62   the..<b>dbif</b
2d00: 3e 20 3c 62 3e 70 72 6f 70 65 72 74 79 3c 2f 62  > <b>property</b
2d10: 3e 20 63 6f 6d 6d 61 6e 64 20 77 61 73 20 69 73  > command was is
2d20: 73 75 65 64 20 66 72 6f 6d 20 6f 72 2c 20 69 66  sued from or, if
2d30: 20 61 20 73 6c 61 76 65 0d 0a 69 6e 74 65 72 70   a slave..interp
2d40: 72 65 74 65 72 20 77 61 73 20 73 70 65 63 69 66  reter was specif
2d50: 69 65 64 2c 20 69 6e 20 74 68 65 20 63 75 72 72  ied, in the curr
2d60: 65 6e 74 20 6e 61 6d 65 73 70 61 63 65 20 6f 66  ent namespace of
2d70: 20 74 68 61 74 20 73 6c 61 76 65 20 69 6e 74 65   that slave inte
2d80: 72 70 72 65 74 65 72 0d 0a 61 74 20 64 65 66 69  rpreter..at defi
2d90: 6e 69 74 69 6f 6e 20 74 69 6d 65 2e 0d 0a 0d 0a  nition time.....
2da0: 3c 70 3e 0d 0a 0d 0a 47 65 6e 65 72 61 74 69 6e  <p>....Generatin
2db0: 67 20 74 68 65 20 70 72 6f 70 65 72 74 79 20 76  g the property v
2dc0: 61 6c 75 65 20 6f 6e 6c 79 20 77 68 65 6e 20 6e  alue only when n
2dd0: 65 65 64 65 64 20 63 61 6e 20 62 65 20 69 6d 70  eeded can be imp
2de0: 6c 65 6d 65 6e 74 65 64 20 62 79 20 70 75 74 74  lemented by putt
2df0: 69 6e 67 0d 0a 61 20 72 65 61 64 20 74 72 61 63  ing..a read trac
2e00: 65 20 6f 6e 20 74 68 65 20 67 6c 6f 62 61 6c 20  e on the global 
2e10: 76 61 72 69 61 62 6c 65 2e 20 45 78 61 6d 70 6c  variable. Exampl
2e20: 65 3a 0d 0a 0d 0a 3c 76 65 72 62 61 74 69 6d 3e  e:....<verbatim>
2e30: 0d 0a 64 62 69 66 20 70 72 6f 70 65 72 74 79 20  ..dbif property 
2e40: 2d 61 74 74 72 69 62 75 74 65 73 20 7b 50 72 6f  -attributes {Pro
2e50: 70 65 72 74 79 2e 45 6d 69 74 73 43 68 61 6e 67  perty.EmitsChang
2e60: 65 64 53 69 67 6e 61 6c 20 66 61 6c 73 65 7d 20  edSignal false} 
2e70: 2f 20 63 6c 6f 63 6b 20 73 65 63 0d 0a 74 72 61  / clock sec..tra
2e80: 63 65 20 61 64 64 20 76 61 72 69 61 62 6c 65 20  ce add variable 
2e90: 73 65 63 20 72 65 61 64 20 7b 61 70 70 6c 79 20  sec read {apply 
2ea0: 7b 61 72 67 73 20 7b 73 65 74 20 3a 3a 73 65 63  {args {set ::sec
2eb0: 20 5b 63 6c 6f 63 6b 20 73 65 63 6f 6e 64 73 5d   [clock seconds]
2ec0: 7d 7d 7d 0d 0a 3c 2f 76 65 72 62 61 74 69 6d 3e  }}}..</verbatim>
2ed0: 0d 0a 0d 0a 49 6e 20 74 68 69 73 20 65 78 61 6d  ....In this exam
2ee0: 70 6c 65 20 74 68 65 20 50 72 6f 70 65 72 74 79  ple the Property
2ef0: 2e 45 6d 69 74 73 43 68 61 6e 67 65 64 53 69 67  .EmitsChangedSig
2f00: 6e 61 6c 20 61 74 74 72 69 62 75 74 65 20 69 73  nal attribute is
2f10: 20 75 73 65 64 20 74 6f 0d 0a 70 72 65 76 65 6e   used to..preven
2f20: 74 20 74 68 65 20 3c 65 6d 3e 50 72 6f 70 65 72  t the <em>Proper
2f30: 74 69 65 73 43 68 61 6e 67 65 64 3c 2f 65 6d 3e  tiesChanged</em>
2f40: 20 73 69 67 6e 61 6c 20 62 65 69 6e 67 20 67 65   signal being ge
2f50: 6e 65 72 61 74 65 64 2c 20 77 68 69 63 68 20 77  nerated, which w
2f60: 6f 75 6c 64 0d 0a 69 6e 76 6f 6c 76 65 20 61 20  ould..involve a 
2f70: 73 65 63 6f 6e 64 20 72 65 61 64 20 6f 66 20 74  second read of t
2f80: 68 65 20 76 61 72 69 61 62 6c 65 2e 0d 0a 3c 64  he variable...<d
2f90: 74 3e 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62  t><b>dbif</b> <b
2fa0: 3e 72 65 74 75 72 6e 3c 2f 62 3e 20 3c 69 3e 6d  >return</b> <i>m
2fb0: 65 73 73 61 67 65 49 44 3c 2f 69 3e 20 3c 69 3e  essageID</i> <i>
2fc0: 72 65 74 75 72 6e 76 61 6c 75 65 3c 2f 69 3e 0d  returnvalue</i>.
2fd0: 0a 3c 64 64 3e 53 65 6e 64 20 61 20 44 2d 42 75  .<dd>Send a D-Bu
2fe0: 73 20 72 65 74 75 72 6e 20 6d 65 73 73 61 67 65  s return message
2ff0: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
3000: 61 20 44 2d 42 75 73 20 6d 65 74 68 6f 64 20 63  a D-Bus method c
3010: 61 6c 6c 2e 20 54 68 65 20 70 72 6f 76 69 64 65  all. The provide
3020: 64 0d 0a 3c 69 3e 72 65 74 75 72 6e 76 61 6c 75  d..<i>returnvalu
3030: 65 3c 2f 69 3e 20 6d 75 73 74 20 6d 61 74 63 68  e</i> must match
3040: 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 73   the signature s
3050: 70 65 63 69 66 69 65 64 20 65 61 72 6c 69 65 72  pecified earlier
3060: 20 69 6e 20 74 68 65 0d 0a 3c 62 3e 64 62 69 66   in the..<b>dbif
3070: 3c 2f 62 3e 20 3c 62 3e 6d 65 74 68 6f 64 3c 2f  </b> <b>method</
3080: 62 3e 20 63 6f 6d 6d 61 6e 64 20 66 6f 72 20 74  b> command for t
3090: 68 65 20 6d 65 74 68 6f 64 2e 0d 0a 3c 64 74 3e  he method...<dt>
30a0: 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 73  <b>dbif</b> <b>s
30b0: 69 67 6e 61 6c 3c 2f 62 3e 20 3f 3c 62 3e 2d 61  ignal</b> ?<b>-a
30c0: 74 74 72 69 62 75 74 65 73 3c 2f 62 3e 20 3c 69  ttributes</b> <i
30d0: 3e 61 74 74 72 69 62 75 74 65 73 3c 2f 69 3e 3f  >attributes</i>?
30e0: 20 3f 3c 62 3e 2d 62 75 73 3c 2f 62 3e 20 3c 69   ?<b>-bus</b> <i
30f0: 3e 62 75 73 74 79 70 65 3c 2f 69 3e 3f 20 3f 3c  >bustype</i>? ?<
3100: 62 3e 2d 69 64 3c 2f 62 3e 20 3c 69 3e 73 69 67  b>-id</b> <i>sig
3110: 6e 61 6c 49 44 3c 2f 69 3e 3f 20 3f 3c 62 3e 2d  nalID</i>? ?<b>-
3120: 69 6e 74 65 72 66 61 63 65 3c 2f 62 3e 20 3c 69  interface</b> <i
3130: 3e 69 6e 74 65 72 66 61 63 65 3c 2f 69 3e 3f 20  >interface</i>? 
3140: 3c 69 3e 70 61 74 68 3c 2f 69 3e 20 3c 69 3e 6e  <i>path</i> <i>n
3150: 61 6d 65 3c 2f 69 3e 20 3f 3c 69 3e 61 72 67 6c  ame</i> ?<i>argl
3160: 69 73 74 3c 2f 69 3e 20 3f 3f 3c 69 3e 69 6e 74  ist</i> ??<i>int
3170: 65 72 70 3c 2f 69 3e 3f 20 3c 69 3e 61 72 67 73  erp</i>? <i>args
3180: 3c 2f 69 3e 20 3c 69 3e 62 6f 64 79 3c 2f 69 3e  </i> <i>body</i>
3190: 3f 3f 0d 0a 3c 64 64 3e 44 65 66 69 6e 65 20 61  ??..<dd>Define a
31a0: 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
31b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
31c0: 20 65 6d 69 74 20 75 73 69 6e 67 20 74 68 65 20   emit using the 
31d0: 3c 62 3e 64 62 69 66 3c 2f 62 3e 0d 0a 3c 62 3e  <b>dbif</b>..<b>
31e0: 67 65 6e 65 72 61 74 65 3c 2f 62 3e 20 73 75 62  generate</b> sub
31f0: 63 6f 6d 6d 61 6e 64 2e 20 53 69 67 6e 61 6c 73  command. Signals
3200: 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
3210: 20 62 79 20 74 68 65 69 72 20 53 69 67 6e 61 6c   by their Signal
3220: 49 44 2e 0d 0a 49 66 20 3c 62 3e 2d 69 64 3c 2f  ID...If <b>-id</
3230: 62 3e 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  b> is specified,
3240: 20 69 74 20 69 73 20 75 73 65 64 20 61 73 20 74   it is used as t
3250: 68 65 20 53 69 67 6e 61 6c 49 44 2e 20 4f 74 68  he SignalID. Oth
3260: 65 72 77 69 73 65 20 61 20 6e 65 77 0d 0a 75 6e  erwise a new..un
3270: 69 71 75 65 20 69 64 65 6e 74 69 66 69 65 72 20  ique identifier 
3280: 69 73 20 67 65 6e 65 72 61 74 65 64 2e 20 53 70  is generated. Sp
3290: 65 63 69 66 79 69 6e 67 20 61 6e 20 65 78 69 73  ecifying an exis
32a0: 74 69 6e 67 20 53 69 67 6e 61 6c 49 44 20 72 65  ting SignalID re
32b0: 70 6c 61 63 65 73 0d 0a 74 68 65 20 70 72 65 76  places..the prev
32c0: 69 6f 75 73 6c 79 20 64 65 66 69 6e 65 64 20 73  iously defined s
32d0: 69 67 6e 61 6c 2e 0d 0a 0d 0a 3c 70 3e 0d 0a 0d  ignal.....<p>...
32e0: 0a 41 74 74 72 69 62 75 74 65 73 20 6d 61 79 20  .Attributes may 
32f0: 62 65 20 73 70 65 63 69 66 69 65 64 20 76 69 61  be specified via
3300: 20 74 68 65 20 3c 62 3e 2d 61 74 74 72 69 62 75   the <b>-attribu
3310: 74 65 73 3c 2f 62 3e 20 6f 70 74 69 6f 6e 20 74  tes</b> option t
3320: 6f 20 70 72 6f 76 69 64 65 0d 0a 68 69 6e 74 73  o provide..hints
3330: 20 74 6f 20 75 73 65 72 73 20 6f 66 20 79 6f 75   to users of you
3340: 72 20 41 50 49 2e 0d 0a 53 65 65 20 3c 62 3e 41  r API...See <b>A
3350: 54 54 52 49 42 55 54 45 53 3c 2f 62 3e 20 62 65  TTRIBUTES</b> be
3360: 6c 6f 77 20 66 6f 72 20 6d 6f 72 65 20 69 6e 66  low for more inf
3370: 6f 72 6d 61 74 69 6f 6e 2e 0d 0a 0d 0a 3c 70 3e  ormation.....<p>
3380: 0d 0a 0d 0a 54 68 65 20 63 6f 6d 6d 61 6e 64 20  ....The command 
3390: 72 65 74 75 72 6e 73 20 74 68 65 20 53 69 67 6e  returns the Sign
33a0: 61 6c 49 44 20 6f 66 20 74 68 65 20 6e 65 77 6c  alID of the newl
33b0: 79 20 63 72 65 61 74 65 64 20 73 69 67 6e 61 6c  y created signal
33c0: 2e 0d 0a 0d 0a 3c 70 3e 0d 0a 0d 0a 49 66 20 74  .....<p>....If t
33d0: 68 65 20 6f 70 74 69 6f 6e 61 6c 20 3c 69 3e 61  he optional <i>a
33e0: 72 67 73 3c 2f 69 3e 20 61 6e 64 20 3c 69 3e 62  rgs</i> and <i>b
33f0: 6f 64 79 3c 2f 69 3e 20 61 72 67 75 6d 65 6e 74  ody</i> argument
3400: 73 20 61 72 65 20 73 70 65 63 69 66 69 65 64 2c  s are specified,
3410: 20 62 6f 64 79 0d 0a 77 69 6c 6c 20 62 65 20 65   body..will be e
3420: 78 65 63 75 74 65 64 20 77 68 65 6e 20 74 68 65  xecuted when the
3430: 20 73 69 67 6e 61 6c 20 69 73 20 74 72 61 6e 73   signal is trans
3440: 6d 69 74 74 65 64 20 6f 6e 20 74 68 65 20 44 2d  mitted on the D-
3450: 42 75 73 20 61 73 20 61 20 72 65 73 75 6c 74 0d  Bus as a result.
3460: 0a 6f 66 20 74 68 65 20 3c 62 3e 64 62 69 66 3c  .of the <b>dbif<
3470: 2f 62 3e 20 3c 62 3e 67 65 6e 65 72 61 74 65 3c  /b> <b>generate<
3480: 2f 62 3e 20 73 75 62 63 6f 6d 6d 61 6e 64 2e 20  /b> subcommand. 
3490: 49 74 20 69 73 20 74 68 65 0d 0a 72 65 73 70 6f  It is the..respo
34a0: 6e 73 69 62 69 6c 69 74 79 20 6f 66 20 74 68 65  nsibility of the
34b0: 20 62 6f 64 79 20 63 6f 64 65 20 74 6f 20 70 72   body code to pr
34c0: 6f 64 75 63 65 20 61 20 72 65 74 75 72 6e 20 76  oduce a return v
34d0: 61 6c 75 65 20 74 68 61 74 20 6d 61 74 63 68 65  alue that matche
34e0: 73 0d 0a 74 68 65 20 73 70 65 63 69 66 69 65 64  s..the specified
34f0: 20 61 72 67 6c 69 73 74 2e 0d 0a 0d 0a 3c 70 3e   arglist.....<p>
3500: 0d 0a 0d 0a 54 68 65 20 63 6f 64 65 20 69 6e 20  ....The code in 
3510: 3c 69 3e 62 6f 64 79 3c 2f 69 3e 20 77 69 6c 6c  <i>body</i> will
3520: 20 62 65 20 65 78 65 63 75 74 65 64 20 69 6e 20   be executed in 
3530: 74 68 65 20 6e 61 6d 65 73 70 61 63 65 20 74 68  the namespace th
3540: 65 0d 0a 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 3c  e..<b>dbif</b> <
3550: 62 3e 73 69 67 6e 61 6c 3c 2f 62 3e 20 63 6f 6d  b>signal</b> com
3560: 6d 61 6e 64 20 77 61 73 20 69 73 73 75 65 64 20  mand was issued 
3570: 66 72 6f 6d 2e 0d 0a 0d 0a 49 66 20 61 6e 79 20  from.....If any 
3580: 75 6e 63 61 75 67 68 74 20 65 72 72 6f 72 20 68  uncaught error h
3590: 61 70 70 65 6e 73 20 64 75 72 69 6e 67 20 74 68  appens during th
35a0: 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
35b0: 68 65 20 62 6f 64 79 20 63 6f 64 65 2c 20 74 68  he body code, th
35c0: 65 0d 0a 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 3c  e..<b>dbif</b> <
35d0: 62 3e 67 65 6e 65 72 61 74 65 3c 2f 62 3e 20 63  b>generate</b> c
35e0: 6f 6d 6d 61 6e 64 20 77 69 6c 6c 20 61 6c 73 6f  ommand will also
35f0: 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 20   throw an error 
3600: 77 69 74 68 0d 0a 74 68 65 20 73 61 6d 65 20 65  with..the same e
3610: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 0d 0a  rror message. ..
3620: 0d 0a 57 68 65 6e 20 74 68 65 20 62 6f 64 79 20  ..When the body 
3630: 63 6f 64 65 20 63 6f 6d 65 73 20 74 6f 20 74 68  code comes to th
3640: 65 20 63 6f 6e 63 6c 75 73 69 6f 6e 20 74 68 61  e conclusion tha
3650: 74 20 74 68 65 20 73 69 67 6e 61 6c 20 64 6f 65  t the signal doe
3660: 73 6e 27 74 20 6e 65 65 64 20 74 6f 0d 0a 62 65  sn't need to..be
3670: 20 73 65 6e 74 20 61 66 74 65 72 20 61 6c 6c 2c   sent after all,
3680: 20 69 74 20 6d 61 79 20 61 62 6f 72 74 20 74 68   it may abort th
3690: 65 20 6f 70 65 72 61 74 69 6f 6e 20 62 79 20 72  e operation by r
36a0: 65 74 75 72 6e 69 6e 67 20 75 73 69 6e 67 0d 0a  eturning using..
36b0: 26 23 39 31 3b 72 65 74 75 72 6e 20 2d 63 6f 64  &#91;return -cod
36c0: 65 20 72 65 74 75 72 6e 26 23 39 33 3b 2e 0d 0a  e return&#93;...
36d0: 0d 0a 54 68 65 20 3c 69 3e 61 72 67 6c 69 73 74  ..The <i>arglist
36e0: 3c 2f 69 3e 20 61 72 67 75 6d 65 6e 74 20 66 6f  </i> argument fo
36f0: 6c 6c 6f 77 73 20 74 68 65 20 73 70 65 63 69 61  llows the specia
3700: 6c 20 72 75 6c 65 73 20 66 6f 72 20 64 62 69 66  l rules for dbif
3710: 0d 0a 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 73  ..argument lists
3720: 2e 20 53 65 65 20 3c 62 3e 41 52 47 55 4d 45 4e  . See <b>ARGUMEN
3730: 54 20 4c 49 53 54 53 3c 2f 62 3e 20 62 65 6c 6f  T LISTS</b> belo
3740: 77 20 66 6f 72 20 6d 6f 72 65 20 69 6e 66 6f 72  w for more infor
3750: 6d 61 74 69 6f 6e 2e 0d 0a 0d 0a 3c 70 3e 0d 0a  mation.....<p>..
3760: 0d 0a 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  ..In addition to
3770: 20 76 61 6c 69 64 20 64 62 75 73 20 70 61 74 68   valid dbus path
3780: 73 2c 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  s, an empty stri
3790: 6e 67 20 6d 61 79 20 62 65 20 73 70 65 63 69 66  ng may be specif
37a0: 69 65 64 20 66 6f 72 20 74 68 65 0d 0a 3c 69 3e  ied for the..<i>
37b0: 70 61 74 68 3c 2f 69 3e 20 61 72 67 75 6d 65 6e  path</i> argumen
37c0: 74 2e 20 54 68 69 73 20 6d 61 6b 65 73 20 74 68  t. This makes th
37d0: 65 20 73 69 67 6e 61 6c 20 61 76 61 69 6c 61 62  e signal availab
37e0: 6c 65 20 6f 6e 20 61 6c 6c 20 70 61 74 68 73 2e  le on all paths.
37f0: 20 49 6e 20 74 68 69 73 0d 0a 63 61 73 65 20 61   In this..case a
3800: 20 62 6f 64 79 20 6d 75 73 74 20 62 65 20 70 72   body must be pr
3810: 6f 76 69 64 65 64 20 61 6e 64 20 74 68 65 20 62  ovided and the b
3820: 6f 64 79 20 63 6f 64 65 20 6d 75 73 74 20 70 72  ody code must pr
3830: 6f 76 69 64 65 20 61 20 70 61 74 68 20 69 6e 20  ovide a path in 
3840: 74 68 65 0d 0a 3c 62 3e 2d 70 61 74 68 3c 2f 62  the..<b>-path</b
3850: 3e 20 6f 70 74 69 6f 6e 20 74 6f 20 74 68 65 20  > option to the 
3860: 3c 62 3e 72 65 74 75 72 6e 3c 2f 62 3e 20 63 6f  <b>return</b> co
3870: 6d 6d 61 6e 64 2e 0d 0a 46 6f 72 20 65 78 61 6d  mmand...For exam
3880: 70 6c 65 3a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  ple: The followi
3890: 6e 67 20 68 65 6c 70 65 72 20 70 72 6f 63 20 63  ng helper proc c
38a0: 6f 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20  ould be used to 
38b0: 61 6c 6c 6f 77 20 70 72 6f 76 69 64 69 6e 67 20  allow providing 
38c0: 61 0d 0a 70 61 74 68 20 74 6f 20 74 68 65 20 3c  a..path to the <
38d0: 62 3e 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 67 65  b>dbif</b> <b>ge
38e0: 6e 65 72 61 74 65 3c 2f 62 3e 20 63 6f 6d 6d 61  nerate</b> comma
38f0: 6e 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 74  nd in front of t
3900: 68 65 0d 0a 73 69 67 6e 61 6c 20 61 72 67 75 6d  he..signal argum
3910: 65 6e 74 73 3a 0d 0a 0d 0a 3c 76 65 72 62 61 74  ents:....<verbat
3920: 69 6d 3e 0d 0a 70 72 6f 63 20 73 74 64 73 69 67  im>..proc stdsig
3930: 6e 61 6c 20 7b 70 61 74 68 20 61 72 67 73 7d 20  nal {path args} 
3940: 7b 0d 0a 20 20 20 20 23 20 53 69 6e 67 6c 65 20  {..    # Single 
3950: 61 72 67 75 6d 65 6e 74 20 73 69 67 6e 61 6c 20  argument signal 
3960: 62 6f 64 69 65 73 20 61 72 65 20 6e 6f 74 20 65  bodies are not e
3970: 78 70 65 63 74 65 64 20 74 6f 20 70 72 6f 64 75  xpected to produ
3980: 63 65 20 61 20 6c 69 73 74 0d 0a 20 20 20 20 69  ce a list..    i
3990: 66 20 7b 5b 6c 6c 65 6e 67 74 68 20 24 61 72 67  f {[llength $arg
39a0: 73 5d 20 3d 3d 20 31 7d 20 7b 73 65 74 20 61 72  s] == 1} {set ar
39b0: 67 73 20 5b 6c 69 6e 64 65 78 20 24 61 72 67 73  gs [lindex $args
39c0: 20 30 5d 7d 0d 0a 20 20 20 20 72 65 74 75 72 6e   0]}..    return
39d0: 20 2d 70 61 74 68 20 24 70 61 74 68 20 24 61 72   -path $path $ar
39e0: 67 73 0d 0a 7d 0d 0a 3c 2f 76 65 72 62 61 74 69  gs..}..</verbati
39f0: 6d 3e 0d 0a 3c 2f 64 6c 3e 0d 0a 0d 0a 3c 68 32  m>..</dl>....<h2
3a00: 3e 42 55 53 20 54 59 50 45 53 3c 2f 68 32 3e 0d  >BUS TYPES</h2>.
3a10: 0a 0d 0a 54 68 65 20 3c 62 3e 2d 62 75 73 3c 2f  ...The <b>-bus</
3a20: 62 3e 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65  b> option of the
3a30: 20 76 61 72 69 6f 75 73 20 73 75 62 63 6f 6d 6d   various subcomm
3a40: 61 6e 64 73 20 74 61 6b 65 73 20 61 20 3c 69 3e  ands takes a <i>
3a50: 62 75 73 74 79 70 65 3c 2f 69 3e 0d 0a 76 61 6c  bustype</i>..val
3a60: 75 65 20 74 68 61 74 20 63 61 6e 20 74 61 6b 65  ue that can take
3a70: 20 73 65 76 65 72 61 6c 20 66 6f 72 6d 73 3a 0d   several forms:.
3a80: 0a 3c 75 6c 3e 0d 0a 0d 0a 3c 6c 69 3e 4f 6e 65  .<ul>....<li>One
3a90: 20 6f 66 20 74 68 65 20 77 65 6c 6c 2d 6b 6e 6f   of the well-kno
3aa0: 77 6e 20 62 75 73 20 6e 61 6d 65 73 3a 20 27 73  wn bus names: 's
3ab0: 65 73 73 69 6f 6e 27 2c 20 27 73 79 73 74 65 6d  ession', 'system
3ac0: 27 2c 20 6f 72 20 27 73 74 61 72 74 75 70 27 2e  ', or 'startup'.
3ad0: 0d 0a 3c 2f 6c 69 3e 0d 0a 3c 6c 69 3e 41 20 62  ..</li>..<li>A b
3ae0: 75 73 20 61 64 64 72 65 73 73 2c 20 63 6f 6e 73  us address, cons
3af0: 69 73 74 69 6e 67 20 6f 66 20 61 20 74 72 61 6e  isting of a tran
3b00: 73 70 6f 72 74 20 6e 61 6d 65 20 66 6f 6c 6c 6f  sport name follo
3b10: 77 65 64 20 62 79 20 61 20 63 6f 6c 6f 6e 2c 0d  wed by a colon,.
3b20: 0a 61 6e 64 20 74 68 65 6e 20 61 6e 20 6f 70 74  .and then an opt
3b30: 69 6f 6e 61 6c 2c 20 63 6f 6d 6d 61 2d 73 65 70  ional, comma-sep
3b40: 61 72 61 74 65 64 20 6c 69 73 74 20 6f 66 20 6b  arated list of k
3b50: 65 79 73 20 61 6e 64 20 76 61 6c 75 65 73 20 69  eys and values i
3b60: 6e 20 74 68 65 20 66 6f 72 6d 0d 0a 6b 65 79 3d  n the form..key=
3b70: 76 61 6c 75 65 2e 0d 0a 3c 2f 6c 69 3e 0d 0a 3c  value...</li>..<
3b80: 6c 69 3e 41 20 68 61 6e 64 6c 65 20 61 73 20 72  li>A handle as r
3b90: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 3c  eturned by the <
3ba0: 62 3e 64 62 75 73 3c 2f 62 3e 20 3c 62 3e 63 6f  b>dbus</b> <b>co
3bb0: 6e 6e 65 63 74 3c 2f 62 3e 20 73 75 62 63 6f 6d  nnect</b> subcom
3bc0: 6d 61 6e 64 2e 0d 0a 3c 2f 6c 69 3e 0d 0a 3c 2f  mand...</li>..</
3bd0: 75 6c 3e 0d 0a 0d 0a 3c 68 32 3e 56 41 4c 49 44  ul>....<h2>VALID
3be0: 20 4e 41 4d 45 53 3c 2f 68 32 3e 0d 0a 0d 0a 54   NAMES</h2>....T
3bf0: 68 65 20 64 62 69 66 20 70 61 63 6b 61 67 65 20  he dbif package 
3c00: 65 6e 66 6f 72 63 65 73 20 73 6f 6d 65 20 6c 69  enforces some li
3c10: 6d 69 74 61 74 69 6f 6e 73 20 6f 6e 20 6e 61 6d  mitations on nam
3c20: 65 73 20 75 73 65 64 20 77 69 74 68 20 74 68 65  es used with the
3c30: 0d 0a 3c 62 3e 64 62 69 66 3c 2f 62 3e 20 73 75  ..<b>dbif</b> su
3c40: 62 63 6f 6d 6d 61 6e 64 73 2e 20 41 6c 6c 20 6e  bcommands. All n
3c50: 61 6d 65 73 20 6d 75 73 74 20 6f 6e 6c 79 20 75  ames must only u
3c60: 73 65 20 74 68 65 20 63 68 61 72 61 63 74 65 72  se the character
3c70: 73 0d 0a 26 71 75 6f 74 3b 26 23 39 31 3b 41 2d  s..&quot;&#91;A-
3c80: 5a 26 23 39 33 3b 26 23 39 31 3b 61 2d 7a 26 23  Z&#93;&#91;a-z&#
3c90: 39 33 3b 26 23 39 31 3b 30 2d 39 26 23 39 33 3b  93;&#91;0-9&#93;
3ca0: 5f 26 71 75 6f 74 3b 2e 20 54 68 69 73 20 6c 69  _&quot;. This li
3cb0: 6d 69 74 61 74 69 6f 6e 20 61 70 70 6c 69 65 73  mitation applies
3cc0: 20 74 6f 20 6d 65 74 68 6f 64 0d 0a 6e 61 6d 65   to method..name
3cd0: 73 2c 20 70 72 6f 70 65 72 74 79 20 6e 61 6d 65  s, property name
3ce0: 73 2c 20 73 69 67 6e 61 6c 20 6e 61 6d 65 73 2c  s, signal names,
3cf0: 20 61 6e 64 20 61 72 67 75 6d 65 6e 74 20 6e 61   and argument na
3d00: 6d 65 73 2e 20 4f 75 74 20 6f 66 20 74 68 69 73  mes. Out of this
3d10: 20 67 72 6f 75 70 2c 0d 0a 6f 6e 6c 79 20 61 72   group,..only ar
3d20: 67 75 6d 65 6e 74 20 6e 61 6d 65 73 20 6d 61 79  gument names may
3d30: 20 62 65 67 69 6e 20 77 69 74 68 20 61 20 64 69   begin with a di
3d40: 67 69 74 2e 0d 0a 0d 0a 3c 70 3e 0d 0a 0d 0a 49  git.....<p>....I
3d50: 6e 74 65 72 66 61 63 65 20 6e 61 6d 65 73 20 61  nterface names a
3d60: 6e 64 20 65 72 72 6f 72 20 6e 61 6d 65 73 20 6d  nd error names m
3d70: 75 73 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  ust consist of a
3d80: 74 20 6c 65 61 73 74 20 74 77 6f 20 65 6c 65 6d  t least two elem
3d90: 65 6e 74 73 0d 0a 73 65 70 61 72 61 74 65 64 20  ents..separated 
3da0: 62 79 20 61 20 70 65 72 69 6f 64 20 28 27 2e 27  by a period ('.'
3db0: 29 20 63 68 61 72 61 63 74 65 72 2e 20 45 61 63  ) character. Eac
3dc0: 68 20 65 6c 65 6d 65 6e 74 20 6d 75 73 74 20 6f  h element must o
3dd0: 6e 6c 79 20 63 6f 6e 74 61 69 6e 20 74 68 65 0d  nly contain the.
3de0: 0a 63 68 61 72 61 63 74 65 72 73 20 26 71 75 6f  .characters &quo
3df0: 74 3b 26 23 39 31 3b 41 2d 5a 26 23 39 33 3b 26  t;&#91;A-Z&#93;&
3e00: 23 39 31 3b 61 2d 7a 26 23 39 33 3b 26 23 39 31  #91;a-z&#93;&#91
3e10: 3b 30 2d 39 26 23 39 33 3b 5f 26 71 75 6f 74 3b  ;0-9&#93;_&quot;
3e20: 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
3e30: 67 69 6e 20 77 69 74 68 20 61 0d 0a 64 69 67 69  gin with a..digi
3e40: 74 2e 0d 0a 0d 0a 3c 70 3e 0d 0a 0d 0a 44 2d 42  t.....<p>....D-B
3e50: 75 73 20 6e 61 6d 65 73 20 66 6f 72 20 61 70 70  us names for app
3e60: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 66  lications must f
3e70: 6f 6c 6c 6f 77 20 74 68 65 20 73 61 6d 65 20 72  ollow the same r
3e80: 75 6c 65 73 20 61 73 20 69 6e 74 65 72 66 61 63  ules as interfac
3e90: 65 20 6e 61 6d 65 73 2c 0d 0a 65 78 63 65 70 74  e names,..except
3ea0: 20 74 68 61 74 20 61 6c 73 6f 20 64 61 73 68 20   that also dash 
3eb0: 28 27 2d 27 29 20 63 68 61 72 61 63 74 65 72 73  ('-') characters
3ec0: 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 55 6e   are allowed. Un
3ed0: 69 71 75 65 20 44 2d 42 75 73 20 6e 61 6d 65 73  ique D-Bus names
3ee0: 20 62 65 67 69 6e 0d 0a 77 69 74 68 20 61 20 63   begin..with a c
3ef0: 6f 6c 6f 6e 20 28 27 3a 27 29 2e 20 54 68 65 20  olon (':'). The 
3f00: 65 6c 65 6d 65 6e 74 73 20 6f 66 20 75 6e 69 71  elements of uniq
3f10: 75 65 20 44 2d 42 75 73 20 6e 61 6d 65 73 20 61  ue D-Bus names a
3f20: 72 65 20 61 6c 6c 6f 77 65 64 20 74 6f 20 62 65  re allowed to be
3f30: 67 69 6e 0d 0a 77 69 74 68 20 61 20 64 69 67 69  gin..with a digi
3f40: 74 2e 0d 0a 0d 0a 3c 70 3e 0d 0a 0d 0a 50 61 74  t.....<p>....Pat
3f50: 68 73 20 6d 75 73 74 20 73 74 61 72 74 20 77 69  hs must start wi
3f60: 74 68 20 61 20 73 6c 61 73 68 20 28 27 2f 27 29  th a slash ('/')
3f70: 20 61 6e 64 20 6d 75 73 74 20 63 6f 6e 73 69 73   and must consis
3f80: 74 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 73 65  t of elements se
3f90: 70 61 72 61 74 65 64 0d 0a 62 79 20 73 6c 61 73  parated..by slas
3fa0: 68 20 63 68 61 72 61 63 74 65 72 73 2e 20 45 61  h characters. Ea
3fb0: 63 68 20 65 6c 65 6d 65 6e 74 20 6d 75 73 74 20  ch element must 
3fc0: 6f 6e 6c 79 20 63 6f 6e 74 61 69 6e 20 74 68 65  only contain the
3fd0: 20 63 68 61 72 61 63 74 65 72 73 0d 0a 26 71 75   characters..&qu
3fe0: 6f 74 3b 26 23 39 31 3b 41 2d 5a 26 23 39 33 3b  ot;&#91;A-Z&#93;
3ff0: 26 23 39 31 3b 61 2d 7a 26 23 39 33 3b 26 23 39  &#91;a-z&#93;&#9
4000: 31 3b 30 2d 39 26 23 39 33 3b 5f 26 71 75 6f 74  1;0-9&#93;_&quot
4010: 3b 2e 20 45 6d 70 74 79 20 65 6c 65 6d 65 6e 74  ;. Empty element
4020: 73 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  s are not allowe
4030: 64 2e 0d 0a 0d 0a 3c 68 32 3e 41 52 47 55 4d 45  d.....<h2>ARGUME
4040: 4e 54 20 4c 49 53 54 53 3c 2f 68 32 3e 0d 0a 0d  NT LISTS</h2>...
4050: 0a 44 75 65 20 74 6f 20 74 68 65 20 66 61 63 74  .Due to the fact
4060: 20 74 68 61 74 20 74 68 65 20 44 2d 42 75 73 20   that the D-Bus 
4070: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 77 6f  specification wo
4080: 72 6b 73 20 77 69 74 68 20 74 79 70 65 64 20 61  rks with typed a
4090: 72 67 75 6d 65 6e 74 73 2c 20 61 0d 0a 73 6c 69  rguments, a..sli
40a0: 67 68 74 6c 79 20 6d 6f 64 69 66 69 65 64 20 6d  ghtly modified m
40b0: 65 74 68 6f 64 20 66 6f 72 20 73 70 65 63 69 66  ethod for specif
40c0: 79 69 6e 67 20 61 72 67 75 6d 65 6e 74 20 6c 69  ying argument li
40d0: 73 74 73 20 68 61 73 20 62 65 65 6e 20 61 64 6f  sts has been ado
40e0: 70 74 65 64 20 66 6f 72 0d 0a 74 68 65 20 64 62  pted for..the db
40f0: 69 66 20 70 61 63 6b 61 67 65 2e 20 54 68 65 20  if package. The 
4100: 6e 6f 72 6d 61 6c 20 54 63 6c 20 61 72 67 75 6d  normal Tcl argum
4110: 65 6e 74 20 6c 69 73 74 20 61 73 20 75 73 65 64  ent list as used
4120: 20 77 69 74 68 20 74 68 65 0d 0a 3c 62 3e 70 72   with the..<b>pr
4130: 6f 63 3c 2f 62 3e 20 61 6e 64 20 3c 62 3e 61 70  oc</b> and <b>ap
4140: 70 6c 79 3c 2f 62 3e 20 63 6f 6d 6d 61 6e 64 73  ply</b> commands
4150: 20 6d 61 79 20 73 74 69 6c 6c 20 62 65 20 75 73   may still be us
4160: 65 64 2e 20 49 6e 20 74 68 61 74 20 63 61 73 65  ed. In that case
4170: 20 61 6c 6c 0d 0a 61 72 67 75 6d 65 6e 74 73 20   all..arguments 
4180: 77 69 6c 6c 20 62 65 20 6f 66 20 74 68 65 20 73  will be of the s
4190: 74 72 69 6e 67 20 74 79 70 65 2e 20 54 6f 20 73  tring type. To s
41a0: 70 65 63 69 66 79 20 61 20 64 69 66 66 65 72 65  pecify a differe
41b0: 6e 74 20 74 79 70 65 2c 20 74 68 65 0d 0a 76 61  nt type, the..va
41c0: 72 69 61 62 6c 65 20 6e 61 6d 65 20 6d 75 73 74  riable name must
41d0: 20 62 65 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20   be followed by 
41e0: 61 20 63 6f 6c 6f 6e 20 61 6e 64 20 74 68 65 20  a colon and the 
41f0: 44 2d 42 75 73 20 73 69 67 6e 61 74 75 72 65 0d  D-Bus signature.
4200: 0a 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 66  .specification f
4210: 6f 72 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  or that argument
4220: 2e 20 45 78 61 6d 70 6c 65 3a 20 74 6f 20 64 65  . Example: to de
4230: 66 69 6e 65 20 74 68 65 20 63 6f 75 6e 74 20 61  fine the count a
4240: 72 67 75 6d 65 6e 74 20 61 73 0d 0a 61 20 33 32  rgument as..a 32
4250: 2d 62 69 74 20 69 6e 74 65 67 65 72 2c 20 69 74  -bit integer, it
4260: 20 73 68 6f 75 6c 64 20 62 65 20 73 70 65 63 69   should be speci
4270: 66 69 65 64 20 61 73 20 63 6f 75 6e 74 3a 69 2e  fied as count:i.
4280: 0d 0a 0d 0a 3c 70 3e 0d 0a 0d 0a 54 68 65 20 66  ....<p>....The f
4290: 6f 6c 6c 6f 77 69 6e 67 20 61 72 67 75 6d 65 6e  ollowing argumen
42a0: 74 20 74 79 70 65 73 20 61 72 65 20 61 76 61 69  t types are avai
42b0: 6c 61 62 6c 65 3a 0d 0a 3c 64 6c 3e 0d 0a 3c 64  lable:..<dl>..<d
42c0: 74 3e 73 0d 0a 3c 64 64 3e 41 20 55 54 46 2d 38  t>s..<dd>A UTF-8
42d0: 20 65 6e 63 6f 64 65 64 2c 20 6e 75 6c 2d 74 65   encoded, nul-te
42e0: 72 6d 69 6e 61 74 65 64 20 55 6e 69 63 6f 64 65  rminated Unicode
42f0: 20 73 74 72 69 6e 67 2e 0d 0a 3c 64 74 3e 62 0d   string...<dt>b.
4300: 0a 3c 64 64 3e 41 20 62 6f 6f 6c 65 61 6e 2c 20  .<dd>A boolean, 
4310: 46 41 4c 53 45 20 28 30 29 2c 20 6f 72 20 54 52  FALSE (0), or TR
4320: 55 45 20 28 31 29 2e 0d 0a 3c 64 74 3e 79 0d 0a  UE (1)...<dt>y..
4330: 3c 64 64 3e 41 20 62 79 74 65 20 28 38 2d 62 69  <dd>A byte (8-bi
4340: 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
4350: 65 72 29 2e 0d 0a 3c 64 74 3e 6e 0d 0a 3c 64 64  er)...<dt>n..<dd
4360: 3e 41 20 31 36 2d 62 69 74 20 73 69 67 6e 65 64  >A 16-bit signed
4370: 20 69 6e 74 65 67 65 72 2e 0d 0a 3c 64 74 3e 71   integer...<dt>q
4380: 0d 0a 3c 64 64 3e 41 20 31 36 2d 62 69 74 20 75  ..<dd>A 16-bit u
4390: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e  nsigned integer.
43a0: 0d 0a 3c 64 74 3e 69 0d 0a 3c 64 64 3e 41 20 33  ..<dt>i..<dd>A 3
43b0: 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
43c0: 65 67 65 72 2e 0d 0a 3c 64 74 3e 75 0d 0a 3c 64  eger...<dt>u..<d
43d0: 64 3e 41 20 33 32 2d 62 69 74 20 75 6e 73 69 67  d>A 32-bit unsig
43e0: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0d 0a 3c 64  ned integer...<d
43f0: 74 3e 78 0d 0a 3c 64 64 3e 41 20 36 34 2d 62 69  t>x..<dd>A 64-bi
4400: 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
4410: 2e 0d 0a 3c 64 74 3e 74 0d 0a 3c 64 64 3e 41 20  ...<dt>t..<dd>A 
4420: 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
4430: 69 6e 74 65 67 65 72 2e 0d 0a 3c 64 74 3e 64 0d  integer...<dt>d.
4440: 0a 3c 64 64 3e 41 6e 20 38 2d 62 79 74 65 20 64  .<dd>An 8-byte d
4450: 6f 75 62 6c 65 20 69 6e 20 49 45 45 45 20 37 35  ouble in IEEE 75
4460: 34 20 66 6f 72 6d 61 74 2e 0d 0a 3c 64 74 3e 67  4 format...<dt>g
4470: 0d 0a 3c 64 64 3e 41 20 74 79 70 65 20 73 69 67  ..<dd>A type sig
4480: 6e 61 74 75 72 65 2e 0d 0a 3c 64 74 3e 6f 0d 0a  nature...<dt>o..
4490: 3c 64 64 3e 41 6e 20 6f 62 6a 65 63 74 20 70 61  <dd>An object pa
44a0: 74 68 2e 0d 0a 3c 64 74 3e 61 23 0d 0a 3c 64 64  th...<dt>a#..<dd
44b0: 3e 41 20 44 2d 42 75 73 20 61 72 72 61 79 20 74  >A D-Bus array t
44c0: 79 70 65 2c 20 77 68 69 63 68 20 69 73 20 73 69  ype, which is si
44d0: 6d 69 6c 61 72 20 74 6f 20 61 20 54 63 6c 20 6c  milar to a Tcl l
44e0: 69 73 74 2e 20 54 68 65 20 23 20 73 70 65 63 69  ist. The # speci
44f0: 66 69 65 73 0d 0a 74 68 65 20 74 79 70 65 20 6f  fies..the type o
4500: 66 20 74 68 65 20 61 72 72 61 79 20 65 6c 65 6d  f the array elem
4510: 65 6e 74 73 2e 20 54 68 69 73 20 63 61 6e 20 62  ents. This can b
4520: 65 20 61 6e 79 20 74 79 70 65 2c 20 69 6e 63 6c  e any type, incl
4530: 75 64 69 6e 67 20 61 6e 6f 74 68 65 72 0d 0a 61  uding another..a
4540: 72 72 61 79 2c 20 61 20 73 74 72 75 63 74 20 6f  rray, a struct o
4550: 72 20 61 20 64 69 63 74 20 65 6e 74 72 79 2e 0d  r a dict entry..
4560: 0a 3c 64 74 3e 76 0d 0a 3c 64 64 3e 41 20 44 2d  .<dt>v..<dd>A D-
4570: 42 75 73 20 76 61 72 69 61 6e 74 20 74 79 70 65  Bus variant type
4580: 2e 20 53 70 65 63 69 66 79 69 6e 67 20 74 68 69  . Specifying thi
4590: 73 20 74 79 70 65 20 77 69 6c 6c 20 63 61 75 73  s type will caus
45a0: 65 20 74 68 65 20 63 6f 64 65 20 74 6f 0d 0a 61  e the code to..a
45b0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 74  utomatically det
45c0: 65 72 6d 69 6e 65 20 74 68 65 20 74 79 70 65 20  ermine the type 
45d0: 6f 66 20 74 68 65 20 70 72 6f 76 69 64 65 64 20  of the provided 
45e0: 76 61 6c 75 65 20 28 62 79 20 6c 6f 6f 6b 69 6e  value (by lookin
45f0: 67 20 61 74 20 74 68 65 0d 0a 69 6e 74 65 72 6e  g at the..intern
4600: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
4610: 6e 29 2e 0d 0a 3c 64 74 3e 28 2e 2e 2e 29 0d 0a  n)...<dt>(...)..
4620: 3c 64 64 3e 41 20 73 74 72 75 63 74 2e 20 54 68  <dd>A struct. Th
4630: 65 20 73 74 72 69 6e 67 20 69 6e 73 69 64 65 20  e string inside 
4640: 74 68 65 20 70 61 72 65 6e 74 68 65 73 65 73 20  the parentheses 
4650: 64 65 66 69 6e 65 73 20 74 68 65 20 74 79 70 65  defines the type
4660: 73 20 6f 66 0d 0a 74 68 65 20 61 72 67 75 6d 65  s of..the argume
4670: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  nts within the s
4680: 74 72 75 63 74 2c 20 77 68 69 63 68 20 6d 61 79  truct, which may
4690: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 63 6f   consist of a co
46a0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 61 6e 79  mbination of any
46b0: 0d 0a 6f 66 20 74 68 65 20 65 78 69 73 74 69 6e  ..of the existin
46c0: 67 20 74 79 70 65 73 2e 0d 0a 3c 64 74 3e 7b 23  g types...<dt>{#
46d0: 23 7d 0d 0a 3c 64 64 3e 41 20 64 69 63 74 20 65  #}..<dd>A dict e
46e0: 6e 74 72 79 2e 20 44 69 63 74 20 65 6e 74 72 69  ntry. Dict entri
46f0: 65 73 20 6d 61 79 20 6f 6e 6c 79 20 6f 63 63 75  es may only occu
4700: 72 20 61 73 20 61 72 72 61 79 20 65 6c 65 6d 65  r as array eleme
4710: 6e 74 73 2e 20 54 68 65 0d 0a 66 69 72 73 74 20  nts. The..first 
4720: 23 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  # specifies the 
4730: 74 79 70 65 20 6f 66 20 74 68 65 20 64 69 63 74  type of the dict
4740: 20 6b 65 79 2e 20 54 68 69 73 20 6d 75 73 74 20   key. This must 
4750: 62 65 20 61 20 62 61 73 69 63 20 74 79 70 65 0d  be a basic type.
4760: 0a 28 6f 6e 65 20 6f 66 20 27 73 62 79 6e 71 69  .(one of 'sbynqi
4770: 75 78 74 64 67 6f 27 29 2e 20 54 68 65 20 73 65  uxtdgo'). The se
4780: 63 6f 6e 64 20 23 20 73 70 65 63 69 66 69 65 73  cond # specifies
4790: 20 74 68 65 20 74 79 70 65 20 6f 66 20 74 68 65   the type of the
47a0: 20 64 69 63 74 20 76 61 6c 75 65 2e 0d 0a 54 68   dict value...Th
47b0: 69 73 20 63 61 6e 20 61 67 61 69 6e 20 62 65 20  is can again be 
47c0: 61 6e 79 20 65 78 69 73 74 69 6e 67 20 74 79 70  any existing typ
47d0: 65 2e 0d 0a 3c 2f 64 6c 3e 0d 0a 0d 0a 3c 70 3e  e...</dl>....<p>
47e0: 0d 0a 0d 0a 41 72 67 75 6d 65 6e 74 20 6c 69 73  ....Argument lis
47f0: 74 73 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 6f  ts may contain o
4800: 70 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  ptional argument
4810: 73 2e 20 54 68 65 20 75 73 65 20 6f 66 20 6f 70  s. The use of op
4820: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
4830: 0d 0a 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  ..will result in
4840: 20 6d 75 6c 74 69 70 6c 65 20 70 72 6f 74 6f 74   multiple protot
4850: 79 70 65 73 20 62 65 69 6e 67 20 72 65 70 6f 72  ypes being repor
4860: 74 65 64 20 66 6f 72 20 74 68 65 20 6f 62 6a 65  ted for the obje
4870: 63 74 20 77 68 65 6e 0d 0a 69 6e 74 72 6f 73 70  ct when..introsp
4880: 65 63 74 65 64 2e 20 54 68 65 20 73 70 65 63 69  ected. The speci
4890: 61 6c 20 6d 65 61 6e 69 6e 67 20 6f 66 20 74 68  al meaning of th
48a0: 65 20 3c 62 20 63 6c 61 73 73 3d 22 63 6f 6e 73  e <b class="cons
48b0: 74 22 3e 61 72 67 73 3c 2f 62 3e 20 61 72 67 75  t">args</b> argu
48c0: 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 0d 0a 74  ment does not..t
48d0: 72 61 6e 73 6c 61 74 65 20 77 65 6c 6c 20 69 6e  ranslate well in
48e0: 20 74 68 65 20 44 2d 42 75 73 20 63 6f 6e 63 65   the D-Bus conce
48f0: 70 74 2e 20 46 6f 72 20 74 68 61 74 20 72 65 61  pt. For that rea
4900: 73 6f 6e 20 75 73 69 6e 67 20 3c 69 3e 61 72 67  son using <i>arg
4910: 73 3c 2f 69 3e 20 61 73 20 74 68 65 0d 0a 6c 61  s</i> as the..la
4920: 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 61  st argument of a
4930: 6e 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  n argument list 
4940: 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
4950: 64 2e 0d 0a 0d 0a 3c 68 32 3e 53 54 41 4e 44 41  d.....<h2>STANDA
4960: 52 44 20 49 4e 54 45 52 46 41 43 45 53 3c 2f 68  RD INTERFACES</h
4970: 32 3e 0d 0a 0d 0a 41 20 6e 75 6d 62 65 72 20 6f  2>....A number o
4980: 66 20 73 74 61 6e 64 61 72 64 20 69 6e 74 65 72  f standard inter
4990: 66 61 63 65 73 20 68 61 76 65 20 62 65 65 6e 20  faces have been 
49a0: 64 65 66 69 6e 65 64 20 69 6e 20 74 68 65 20 44  defined in the D
49b0: 2d 42 75 73 20 73 70 65 63 69 66 69 63 61 74 69  -Bus specificati
49c0: 6f 6e 0d 0a 74 68 61 74 20 6d 61 79 20 62 65 20  on..that may be 
49d0: 75 73 65 66 75 6c 20 61 63 72 6f 73 73 20 76 61  useful across va
49e0: 72 69 6f 75 73 20 44 2d 42 75 73 20 61 70 70 6c  rious D-Bus appl
49f0: 69 63 61 74 69 6f 6e 73 2e 0d 0a 0d 0a 3c 64 69  ications.....<di
4a00: 76 20 69 64 3d 22 73 75 62 73 65 63 74 69 6f 6e  v id="subsection
4a10: 31 22 20 63 6c 61 73 73 3d 22 73 75 62 73 65 63  1" class="subsec
4a20: 74 69 6f 6e 22 3e 3c 68 33 3e 6f 72 67 2e 66 72  tion"><h3>org.fr
4a30: 65 65 64 65 73 6b 74 6f 70 2e 44 42 75 73 2e 50  eedesktop.DBus.P
4a40: 65 65 72 3c 2f 68 33 3e 0d 0a 3c 64 6c 3e 0d 0a  eer</h3>..<dl>..
4a50: 3c 64 74 3e 3c 65 6d 3e 6f 72 67 2e 66 72 65 65  <dt><em>org.free
4a60: 64 65 73 6b 74 6f 70 2e 44 42 75 73 2e 50 65 65  desktop.DBus.Pee
4a70: 72 2e 50 69 6e 67 3c 2f 65 6d 3e 0d 0a 3c 64 64  r.Ping</em>..<dd
4a80: 3e 52 65 74 75 72 6e 73 20 61 6e 20 65 6d 70 74  >Returns an empt
4a90: 79 20 72 65 73 70 6f 6e 73 65 2e 0d 0a 3c 64 74  y response...<dt
4aa0: 3e 3c 65 6d 3e 6f 72 67 2e 66 72 65 65 64 65 73  ><em>org.freedes
4ab0: 6b 74 6f 70 2e 44 42 75 73 2e 50 65 65 72 2e 47  ktop.DBus.Peer.G
4ac0: 65 74 4d 61 63 68 69 6e 65 49 64 3c 2f 65 6d 3e  etMachineId</em>
4ad0: 0d 0a 3c 64 64 3e 52 65 74 75 72 6e 73 20 61 20  ..<dd>Returns a 
4ae0: 68 65 78 2d 65 6e 63 6f 64 65 64 20 55 55 49 44  hex-encoded UUID
4af0: 20 72 65 70 72 65 73 65 6e 74 69 6e 67 20 74 68   representing th
4b00: 65 20 69 64 65 6e 74 69 74 79 20 6f 66 20 74 68  e identity of th
4b10: 65 20 6d 61 63 68 69 6e 65 20 74 68 65 0d 0a 61  e machine the..a
4b20: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 75  pplication is ru
4b30: 6e 6e 69 6e 67 20 6f 6e 2e 0d 0a 3c 2f 64 6c 3e  nning on...</dl>
4b40: 0d 0a 0d 0a 3c 2f 64 69 76 3e 0d 0a 3c 64 69 76  ....</div>..<div
4b50: 20 69 64 3d 22 73 75 62 73 65 63 74 69 6f 6e 32   id="subsection2
4b60: 22 20 63 6c 61 73 73 3d 22 73 75 62 73 65 63 74  " class="subsect
4b70: 69 6f 6e 22 3e 3c 68 33 3e 6f 72 67 2e 66 72 65  ion"><h3>org.fre
4b80: 65 64 65 73 6b 74 6f 70 2e 44 42 75 73 2e 49 6e  edesktop.DBus.In
4b90: 74 72 6f 73 70 65 63 74 61 62 6c 65 3c 2f 68 33  trospectable</h3
4ba0: 3e 0d 0a 3c 64 6c 3e 0d 0a 3c 64 74 3e 3c 65 6d  >..<dl>..<dt><em
4bb0: 3e 6f 72 67 2e 66 72 65 65 64 65 73 6b 74 6f 70  >org.freedesktop
4bc0: 2e 44 42 75 73 2e 49 6e 74 72 6f 73 70 65 63 74  .DBus.Introspect
4bd0: 61 62 6c 65 2e 49 6e 74 72 6f 73 70 65 63 74 3c  able.Introspect<
4be0: 2f 65 6d 3e 0d 0a 3c 64 64 3e 52 65 74 75 72 6e  /em>..<dd>Return
4bf0: 73 20 61 6e 20 58 4d 4c 20 64 65 73 63 72 69 70  s an XML descrip
4c00: 74 69 6f 6e 20 6f 66 20 74 68 65 20 44 2d 42 75  tion of the D-Bu
4c10: 73 20 73 74 72 75 63 74 75 72 65 2c 20 69 6e 63  s structure, inc
4c20: 6c 75 64 69 6e 67 20 69 74 73 20 69 6e 74 65 72  luding its inter
4c30: 66 61 63 65 73 0d 0a 28 77 69 74 68 20 73 69 67  faces..(with sig
4c40: 6e 61 6c 73 20 61 6e 64 20 6d 65 74 68 6f 64 73  nals and methods
4c50: 29 2c 20 6f 62 6a 65 63 74 73 20 62 65 6c 6f 77  ), objects below
4c60: 20 69 74 20 69 6e 20 74 68 65 20 6f 62 6a 65 63   it in the objec
4c70: 74 20 70 61 74 68 20 74 72 65 65 2c 20 61 6e 64  t path tree, and
4c80: 0d 0a 69 74 73 20 70 72 6f 70 65 72 74 69 65 73  ..its properties
4c90: 2e 0d 0a 3c 2f 64 6c 3e 0d 0a 0d 0a 3c 2f 64 69  ...</dl>....</di
4ca0: 76 3e 0d 0a 3c 64 69 76 20 69 64 3d 22 73 75 62  v>..<div id="sub
4cb0: 73 65 63 74 69 6f 6e 33 22 20 63 6c 61 73 73 3d  section3" class=
4cc0: 22 73 75 62 73 65 63 74 69 6f 6e 22 3e 3c 68 33  "subsection"><h3
4cd0: 3e 6f 72 67 2e 66 72 65 65 64 65 73 6b 74 6f 70  >org.freedesktop
4ce0: 2e 44 42 75 73 2e 50 72 6f 70 65 72 74 69 65 73  .DBus.Properties
4cf0: 3c 2f 68 33 3e 0d 0a 3c 64 6c 3e 0d 0a 3c 64 74  </h3>..<dl>..<dt
4d00: 3e 3c 65 6d 3e 6f 72 67 2e 66 72 65 65 64 65 73  ><em>org.freedes
4d10: 6b 74 6f 70 2e 44 42 75 73 2e 50 72 6f 70 65 72  ktop.DBus.Proper
4d20: 74 69 65 73 2e 47 65 74 3c 2f 65 6d 3e 0d 0a 3c  ties.Get</em>..<
4d30: 64 64 3e 52 65 74 75 72 6e 73 20 74 68 65 20 76  dd>Returns the v
4d40: 61 6c 75 65 20 6f 66 20 74 68 65 20 73 70 65 63  alue of the spec
4d50: 69 66 69 65 64 20 70 72 6f 70 65 72 74 79 2e 20  ified property. 
4d60: 4f 6e 6c 79 20 76 61 6c 69 64 20 66 6f 72 20 70  Only valid for p
4d70: 72 6f 70 65 72 74 69 65 73 20 77 69 74 68 0d 0a  roperties with..
4d80: 72 65 61 64 20 6f 72 20 72 65 61 64 77 72 69 74  read or readwrit
4d90: 65 20 61 63 63 65 73 73 2e 0d 0a 3c 64 74 3e 3c  e access...<dt><
4da0: 65 6d 3e 6f 72 67 2e 66 72 65 65 64 65 73 6b 74  em>org.freedeskt
4db0: 6f 70 2e 44 42 75 73 2e 50 72 6f 70 65 72 74 69  op.DBus.Properti
4dc0: 65 73 2e 53 65 74 3c 2f 65 6d 3e 0d 0a 3c 64 64  es.Set</em>..<dd
4dd0: 3e 43 68 61 6e 67 65 73 20 74 68 65 20 76 61 6c  >Changes the val
4de0: 75 65 20 6f 66 20 74 68 65 20 73 70 65 63 69 66  ue of the specif
4df0: 69 65 64 20 70 72 6f 70 65 72 74 79 2e 20 4f 6e  ied property. On
4e00: 6c 79 20 76 61 6c 69 64 20 66 6f 72 20 70 72 6f  ly valid for pro
4e10: 70 65 72 74 69 65 73 20 77 69 74 68 0d 0a 77 72  perties with..wr
4e20: 69 74 65 20 6f 72 20 72 65 61 64 77 72 69 74 65  ite or readwrite
4e30: 20 61 63 63 65 73 73 2e 0d 0a 3c 64 74 3e 3c 65   access...<dt><e
4e40: 6d 3e 6f 72 67 2e 66 72 65 65 64 65 73 6b 74 6f  m>org.freedeskto
4e50: 70 2e 44 42 75 73 2e 50 72 6f 70 65 72 74 69 65  p.DBus.Propertie
4e60: 73 2e 47 65 74 41 6c 6c 3c 2f 65 6d 3e 0d 0a 3c  s.GetAll</em>..<
4e70: 64 64 3e 52 65 74 75 72 6e 73 20 61 20 64 69 63  dd>Returns a dic
4e80: 74 20 6f 66 20 61 6c 6c 20 70 72 6f 70 65 72 74  t of all propert
4e90: 69 65 73 20 77 69 74 68 20 72 65 61 64 20 6f 72  ies with read or
4ea0: 20 72 65 61 64 77 72 69 74 65 20 61 63 63 65 73   readwrite acces
4eb0: 73 2e 0d 0a 3c 64 74 3e 3c 65 6d 3e 6f 72 67 2e  s...<dt><em>org.
4ec0: 66 72 65 65 64 65 73 6b 74 6f 70 2e 44 42 75 73  freedesktop.DBus
4ed0: 2e 50 72 6f 70 65 72 74 69 65 73 2e 50 72 6f 70  .Properties.Prop
4ee0: 65 72 74 69 65 73 43 68 61 6e 67 65 64 3c 2f 65  ertiesChanged</e
4ef0: 6d 3e 0d 0a 3c 64 64 3e 54 68 69 73 20 73 69 67  m>..<dd>This sig
4f00: 6e 61 6c 20 69 73 20 65 6d 69 74 74 65 64 20 77  nal is emitted w
4f10: 68 65 6e 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  hen one or more 
4f20: 70 72 6f 70 65 72 74 69 65 73 20 63 68 61 6e 67  properties chang
4f30: 65 2e 0d 0a 54 68 65 20 62 65 68 61 76 69 6f 72  e...The behavior
4f40: 20 66 6f 72 20 69 6e 64 69 76 69 64 75 61 6c 20   for individual 
4f50: 70 72 6f 70 65 72 74 69 65 73 20 6d 61 79 20 62  properties may b
4f60: 65 20 69 6e 66 6c 75 65 6e 63 65 64 20 62 79 20  e influenced by 
4f70: 74 68 65 69 72 0d 0a 50 72 6f 70 65 72 74 79 2e  their..Property.
4f80: 45 6d 69 74 73 43 68 61 6e 67 65 64 53 69 67 6e  EmitsChangedSign
4f90: 61 6c 20 61 74 74 72 69 62 75 74 65 2e 20 53 65  al attribute. Se
4fa0: 65 20 3c 62 3e 41 54 54 52 49 42 55 54 45 53 3c  e <b>ATTRIBUTES<
4fb0: 2f 62 3e 20 62 65 6c 6f 77 2e 0d 0a 0d 0a 3c 70  /b> below.....<p
4fc0: 3e 0d 0a 0d 0a 41 6c 6c 20 61 70 70 6c 69 63 61  >....All applica
4fd0: 62 6c 65 20 70 72 6f 70 65 72 74 79 20 63 68 61  ble property cha
4fe0: 6e 67 65 73 20 61 72 65 20 63 6f 6c 6c 65 63 74  nges are collect
4ff0: 65 64 20 61 6e 64 20 72 65 70 6f 72 74 65 64 20  ed and reported 
5000: 76 69 61 20 61 20 73 69 6e 67 6c 65 0d 0a 3c 65  via a single..<e
5010: 6d 3e 50 72 6f 70 65 72 74 69 65 73 43 68 61 6e  m>PropertiesChan
5020: 67 65 64 3c 2f 65 6d 3e 20 73 69 67 6e 61 6c 20  ged</em> signal 
5030: 70 65 72 20 70 61 74 68 2f 69 6e 74 65 72 66 61  per path/interfa
5040: 63 65 2f 62 75 73 20 63 6f 6d 62 69 6e 61 74 69  ce/bus combinati
5050: 6f 6e 20 77 68 65 6e 20 74 68 65 0d 0a 61 70 70  on when the..app
5060: 6c 69 63 61 74 69 6f 6e 20 65 6e 74 65 72 73 20  lication enters 
5070: 74 68 65 20 69 64 6c 65 20 6c 6f 6f 70 2e 20 54  the idle loop. T
5080: 68 65 20 73 69 67 6e 61 6c 20 6d 61 79 20 61 6c  he signal may al
5090: 73 6f 20 62 65 20 67 65 6e 65 72 61 74 65 64 20  so be generated 
50a0: 6f 6e 20 64 65 6d 61 6e 64 0d 0a 76 69 61 20 74  on demand..via t
50b0: 68 65 20 63 6f 6d 6d 61 6e 64 3a 0d 0a 3c 64 6c  he command:..<dl
50c0: 3e 0d 0a 3c 64 6c 3e 0d 0a 3c 64 74 3e 3c 62 3e  >..<dl>..<dt><b>
50d0: 64 62 69 66 3c 2f 62 3e 20 3c 62 3e 67 65 6e 65  dbif</b> <b>gene
50e0: 72 61 74 65 3c 2f 62 3e 20 50 72 6f 70 65 72 74  rate</b> Propert
50f0: 69 65 73 43 68 61 6e 67 65 64 20 3c 69 3e 70 61  iesChanged <i>pa
5100: 74 68 3c 2f 69 3e 20 3f 3c 69 3e 69 6e 74 65 72  th</i> ?<i>inter
5110: 66 61 63 65 3c 2f 69 3e 3f 20 3f 3c 69 3e 62 75  face</i>? ?<i>bu
5120: 73 3c 2f 69 3e 3f 0d 0a 3c 64 64 3e 0d 0a 3c 2f  s</i>?..<dd>..</
5130: 64 6c 3e 0d 0a 3c 2f 64 6c 3e 0d 0a 0d 0a 3c 70  dl>..</dl>....<p
5140: 3e 0d 0a 0d 0a 54 68 65 20 66 75 6e 63 74 69 6f  >....The functio
5150: 6e 61 6c 69 74 79 20 66 6f 72 20 61 75 74 6f 6d  nality for autom
5160: 61 74 69 63 61 6c 6c 79 20 70 6f 70 75 6c 61 74  atically populat
5170: 69 6e 67 20 74 68 69 73 20 73 69 67 6e 61 6c 20  ing this signal 
5180: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 0d 0a  is implemented..
5190: 76 69 61 20 76 61 72 69 61 62 6c 65 20 74 72 61  via variable tra
51a0: 63 65 73 2e 20 49 66 20 74 68 69 73 20 66 65 61  ces. If this fea
51b0: 74 75 72 65 20 69 73 20 6e 6f 74 20 6e 65 65 64  ture is not need
51c0: 65 64 2c 20 79 6f 75 20 63 61 6e 20 61 76 6f 69  ed, you can avoi
51d0: 64 20 74 68 65 0d 0a 61 73 73 6f 63 69 61 74 65  d the..associate
51e0: 64 20 6f 76 65 72 68 65 61 64 20 62 79 20 72 65  d overhead by re
51f0: 64 65 66 69 6e 69 6e 67 20 74 68 65 20 50 72 6f  defining the Pro
5200: 70 65 72 74 69 65 73 43 68 61 6e 67 65 64 20 73  pertiesChanged s
5210: 69 67 6e 61 6c 20 69 64 20 74 6f 20 79 6f 75 72  ignal id to your
5220: 0d 0a 6f 77 6e 20 76 65 72 73 69 6f 6e 2e 0d 0a  ..own version...
5230: 54 6f 20 63 6f 6d 70 6c 65 74 65 6c 79 20 67 65  To completely ge
5240: 74 20 72 69 64 20 6f 66 20 74 68 65 20 73 69 67  t rid of the sig
5250: 6e 61 6c 2c 20 79 6f 75 20 63 61 6e 20 75 73 65  nal, you can use
5260: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
5270: 6f 64 65 20 73 6e 69 70 70 65 74 0d 0a 62 65 66  ode snippet..bef
5280: 6f 72 65 20 64 65 66 69 6e 69 6e 67 20 61 6e 79  ore defining any
5290: 20 6f 74 68 65 72 20 70 61 72 74 20 6f 66 20 79   other part of y
52a0: 6f 75 72 20 64 62 75 73 20 69 6e 74 65 72 66 61  our dbus interfa
52b0: 63 65 3a 0d 0a 0d 0a 3c 70 72 65 20 63 6c 61 73  ce:....<pre clas
52c0: 73 3d 22 65 78 61 6d 70 6c 65 22 3e 0d 0a 70 61  s="example">..pa
52d0: 63 6b 61 67 65 20 72 65 71 75 69 72 65 20 64 62  ckage require db
52e0: 69 66 0d 0a 64 62 69 66 20 73 69 67 6e 61 6c 20  if..dbif signal 
52f0: 2d 69 64 20 50 72 6f 70 65 72 74 69 65 73 43 68  -id PropertiesCh
5300: 61 6e 67 65 64 20 2f 20 66 6f 6f 62 61 72 0d 0a  anged / foobar..
5310: 64 62 69 66 20 64 65 6c 65 74 65 20 2f 0d 0a 3c  dbif delete /..<
5320: 2f 70 72 65 3e 0d 0a 3c 2f 64 6c 3e 0d 0a 0d 0a  /pre>..</dl>....
5330: 3c 68 32 3e 41 54 54 52 49 42 55 54 45 53 3c 2f  <h2>ATTRIBUTES</
5340: 68 32 3e 0d 0a 0d 0a 41 74 74 72 69 62 75 74 65  h2>....Attribute
5350: 73 20 6d 61 79 20 62 65 20 73 70 65 63 69 66 69  s may be specifi
5360: 65 64 20 61 73 20 61 20 6c 69 73 74 20 6f 66 20  ed as a list of 
5370: 6b 65 79 2f 76 61 6c 75 65 20 70 61 69 72 73 20  key/value pairs 
5380: 66 6f 72 20 6d 65 74 68 6f 64 73 2c 0d 0a 73 69  for methods,..si
5390: 67 6e 61 6c 73 2c 20 61 6e 64 20 70 72 6f 70 65  gnals, and prope
53a0: 72 74 69 65 73 2e 20 54 68 65 73 65 20 61 74 74  rties. These att
53b0: 72 69 62 75 74 65 73 20 61 72 65 20 72 65 70 6f  ributes are repo
53c0: 72 74 65 64 20 76 69 61 20 61 6e 6e 6f 74 61 74  rted via annotat
53d0: 69 6f 6e 73 20 69 6e 0d 0a 74 68 65 20 58 4d 4c  ions in..the XML
53e0: 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 62 74   description obt
53f0: 61 69 6e 65 64 20 76 69 61 20 61 6e 20 3c 65 6d  ained via an <em
5400: 3e 49 6e 74 72 6f 73 70 65 63 74 3c 2f 65 6d 3e  >Introspect</em>
5410: 20 6d 65 74 68 6f 64 20 63 61 6c 6c 2e 0d 0a 41   method call...A
5420: 6e 6e 6f 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  nnotations may b
5430: 65 20 75 73 65 64 20 74 6f 20 70 72 6f 76 69 64  e used to provid
5440: 65 20 68 69 6e 74 73 20 74 6f 20 75 73 65 72 73  e hints to users
5450: 20 6f 66 20 79 6f 75 72 20 41 50 49 2e 0d 0a 0d   of your API....
5460: 0a 3c 70 3e 0d 0a 0d 0a 53 6f 6d 65 20 77 65 6c  .<p>....Some wel
5470: 6c 2d 6b 6e 6f 77 20 61 74 74 72 69 62 75 74 65  l-know attribute
5480: 73 20 61 72 65 20 28 64 65 66 61 75 6c 74 2c 20  s are (default, 
5490: 69 66 20 61 6e 79 2c 20 73 68 6f 77 6e 20 69 6e  if any, shown in
54a0: 20 69 74 61 6c 69 63 73 29 3a 0d 0a 3c 64 6c 3e   italics):..<dl>
54b0: 0d 0a 3c 64 74 3e 44 65 73 63 72 69 70 74 69 6f  ..<dt>Descriptio
54c0: 6e 0d 0a 3c 64 64 3e 50 72 6f 76 69 64 65 20 61  n..<dd>Provide a
54d0: 20 73 68 6f 72 74 20 31 2d 6c 69 6e 65 20 64 65   short 1-line de
54e0: 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
54f0: 20 6d 65 74 68 6f 64 2c 20 73 69 67 6e 61 6c 20   method, signal 
5500: 6f 72 20 70 72 6f 70 65 72 74 79 2e 0d 0a 3c 64  or property...<d
5510: 74 3e 44 65 70 72 65 63 61 74 65 64 0d 0a 3c 64  t>Deprecated..<d
5520: 64 3e 49 6e 64 69 63 61 74 65 20 74 68 61 74 20  d>Indicate that 
5530: 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 64  this method is d
5540: 65 70 72 65 63 61 74 65 64 20 28 74 72 75 65 2c  eprecated (true,
5550: 20 3c 65 6d 3e 66 61 6c 73 65 3c 2f 65 6d 3e 29   <em>false</em>)
5560: 2e 0d 0a 3c 64 74 3e 4d 65 74 68 6f 64 2e 4e 6f  ...<dt>Method.No
5570: 52 65 70 6c 79 0d 0a 3c 64 64 3e 54 68 69 73 20  Reply..<dd>This 
5580: 6d 65 74 68 6f 64 20 6d 61 79 20 6e 6f 74 20 70  method may not p
5590: 72 6f 64 75 63 65 20 61 20 72 65 70 6c 79 20 28  roduce a reply (
55a0: 74 72 75 65 2c 20 3c 65 6d 3e 66 61 6c 73 65 3c  true, <em>false<
55b0: 2f 65 6d 3e 29 2e 20 46 6f 72 20 65 78 61 6d 70  /em>). For examp
55c0: 6c 65 20 69 66 20 79 6f 75 0d 0a 70 72 6f 76 69  le if you..provi
55d0: 64 65 20 61 20 6d 65 74 68 6f 64 20 74 6f 20 65  de a method to e
55e0: 78 69 74 20 79 6f 75 72 20 61 70 70 6c 69 63 61  xit your applica
55f0: 74 69 6f 6e 2e 0d 0a 3c 64 74 3e 4d 65 74 68 6f  tion...<dt>Metho
5600: 64 2e 45 72 72 6f 72 0d 0a 3c 64 64 3e 54 68 69  d.Error..<dd>Thi
5610: 73 20 6d 65 74 68 6f 64 20 6d 61 79 20 74 68 72  s method may thr
5620: 6f 77 20 74 68 65 20 69 6e 64 69 63 61 74 65 64  ow the indicated
5630: 20 45 78 63 65 70 74 69 6f 6e 20 69 6e 20 61 64   Exception in ad
5640: 64 69 74 69 6f 6e 20 74 6f 20 74 68 65 20 73 74  dition to the st
5650: 61 6e 64 61 72 64 0d 0a 6f 6e 65 73 2e 0d 0a 3c  andard..ones...<
5660: 64 74 3e 50 72 6f 70 65 72 74 79 2e 45 6d 69 74  dt>Property.Emit
5670: 73 43 68 61 6e 67 65 64 53 69 67 6e 61 6c 0d 0a  sChangedSignal..
5680: 3c 64 64 3e 49 6e 64 69 63 61 74 65 73 20 77 68  <dd>Indicates wh
5690: 65 74 68 65 72 20 61 20 63 68 61 6e 67 65 20 74  ether a change t
56a0: 6f 20 74 68 65 20 70 72 6f 70 65 72 74 79 20 69  o the property i
56b0: 73 20 72 65 70 6f 72 74 65 64 20 76 69 61 20 74  s reported via t
56c0: 68 65 20 0d 0a 3c 65 6d 3e 50 72 6f 70 65 72 74  he ..<em>Propert
56d0: 69 65 73 43 68 61 6e 67 65 64 3c 2f 65 6d 3e 20  iesChanged</em> 
56e0: 73 69 67 6e 61 6c 20 28 3c 65 6d 3e 74 72 75 65  signal (<em>true
56f0: 3c 2f 65 6d 3e 2c 20 66 61 6c 73 65 2c 20 69 6e  </em>, false, in
5700: 76 61 6c 69 64 61 74 65 73 2c 20 63 6f 6e 73 74  validates, const
5710: 29 2e 0d 0a 3c 70 3e 0d 0a 54 68 65 20 76 61 6c  )...<p>..The val
5720: 75 65 20 6f 66 20 74 68 69 73 20 61 74 74 72 69  ue of this attri
5730: 62 75 74 65 2c 20 69 66 20 73 70 65 63 69 66 69  bute, if specifi
5740: 65 64 2c 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ed, is also used
5750: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 0d 0a   internally to..
5760: 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 61 75  influence the au
5770: 74 6f 6d 61 74 69 63 20 67 65 6e 65 72 61 74 69  tomatic generati
5780: 6f 6e 20 6f 66 20 74 68 65 20 3c 65 6d 3e 50 72  on of the <em>Pr
5790: 6f 70 65 72 74 69 65 73 43 68 61 6e 67 65 64 3c  opertiesChanged<
57a0: 2f 65 6d 3e 20 73 69 67 6e 61 6c 2e 0d 0a 3c 64  /em> signal...<d
57b0: 6c 3e 0d 0a 3c 64 74 3e 74 72 75 65 0d 0a 3c 64  l>..<dt>true..<d
57c0: 64 3e 54 68 65 20 73 69 67 6e 61 6c 20 69 73 20  d>The signal is 
57d0: 65 6d 69 74 74 65 64 20 77 69 74 68 20 74 68 65  emitted with the
57e0: 20 76 61 6c 75 65 20 69 6e 63 6c 75 64 65 64 2e   value included.
57f0: 20 54 68 69 73 20 69 73 20 74 68 65 20 64 65 66   This is the def
5800: 61 75 6c 74 2e 0d 0a 3c 64 74 3e 66 61 6c 73 65  ault...<dt>false
5810: 0d 0a 3c 64 64 3e 54 68 65 20 73 69 67 6e 61 6c  ..<dd>The signal
5820: 20 69 73 20 6e 6f 74 20 61 75 74 6f 6d 61 74 69   is not automati
5830: 63 61 6c 6c 79 20 65 6d 69 74 74 65 64 20 6f 6e  cally emitted on
5840: 20 61 20 63 68 61 6e 67 65 2e 0d 0a 50 61 72 74   a change...Part
5850: 69 65 73 20 69 6e 74 65 72 65 73 74 65 64 20 69  ies interested i
5860: 6e 20 74 68 65 20 70 72 6f 70 65 72 74 79 20 73  n the property s
5870: 68 6f 75 6c 64 20 6f 62 74 61 69 6e 20 69 74 20  hould obtain it 
5880: 65 76 65 72 79 20 74 69 6d 65 20 74 68 65 79 20  every time they 
5890: 6e 65 65 64 20 69 74 2e 0d 0a 54 68 65 20 61 70  need it...The ap
58a0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6d  plication code m
58b0: 61 79 20 73 74 69 6c 6c 20 65 6d 69 74 20 61 20  ay still emit a 
58c0: 3c 65 6d 3e 50 72 6f 70 65 72 74 69 65 73 43 68  <em>PropertiesCh
58d0: 61 6e 67 65 64 3c 2f 65 6d 3e 20 73 69 67 6e 61  anged</em> signa
58e0: 6c 0d 0a 77 68 65 6e 65 76 65 72 20 64 65 73 69  l..whenever desi
58f0: 72 65 64 2e 0d 0a 54 68 69 73 20 6d 61 79 20 62  red...This may b
5900: 65 20 75 73 65 64 20 66 6f 72 20 70 72 6f 70 65  e used for prope
5910: 72 74 69 65 73 20 74 68 61 74 20 61 72 65 20 69  rties that are i
5920: 6d 70 6c 65 6d 65 6e 74 65 64 20 77 69 74 68 20  mplemented with 
5930: 61 20 72 65 61 64 20 74 72 61 63 65 20 6f 6e 0d  a read trace on.
5940: 0a 74 68 65 20 67 6c 6f 62 61 6c 20 76 61 72 69  .the global vari
5950: 61 62 6c 65 2e 0d 0a 3c 64 74 3e 69 6e 76 61 6c  able...<dt>inval
5960: 69 64 61 74 65 73 0d 0a 3c 64 64 3e 54 68 65 20  idates..<dd>The 
5970: 73 69 67 6e 61 6c 20 69 73 20 65 6d 69 74 74 65  signal is emitte
5980: 64 20 62 75 74 20 74 68 65 20 76 61 6c 75 65 20  d but the value 
5990: 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
59a0: 69 6e 20 74 68 65 20 73 69 67 6e 61 6c 2e 20 54  in the signal. T
59b0: 68 69 73 20 6d 61 79 0d 0a 62 65 20 75 73 65 66  his may..be usef
59c0: 75 6c 20 66 6f 72 20 70 72 6f 70 65 72 74 69 65  ul for propertie
59d0: 73 20 74 68 61 74 20 63 68 61 6e 67 65 20 6d 75  s that change mu
59e0: 63 68 20 6d 6f 72 65 20 66 72 65 71 75 65 6e 74  ch more frequent
59f0: 6c 79 20 74 68 61 6e 20 74 68 65 79 20 61 72 65  ly than they are
5a00: 0d 0a 65 78 70 65 63 74 65 64 20 74 6f 20 62 65  ..expected to be
5a10: 20 71 75 65 72 69 65 64 2c 20 61 6e 64 2f 6f 72   queried, and/or
5a20: 20 68 61 76 65 20 6c 61 72 67 65 20 76 61 6c 75   have large valu
5a30: 65 73 2e 0d 0a 3c 64 74 3e 63 6f 6e 73 74 0d 0a  es...<dt>const..
5a40: 3c 64 64 3e 54 68 65 20 70 72 6f 70 65 72 74 79  <dd>The property
5a50: 20 6e 65 76 65 72 20 63 68 61 6e 67 65 73 20 69   never changes i
5a60: 74 73 20 76 61 6c 75 65 20 64 75 72 69 6e 67 20  ts value during 
5a70: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
5a80: 74 68 65 20 6f 62 6a 65 63 74 20 69 74 0d 0a 62  the object it..b
5a90: 65 6c 6f 6e 67 73 20 74 6f 2c 20 61 6e 64 20 68  elongs to, and h
5aa0: 65 6e 63 65 20 74 68 65 20 73 69 67 6e 61 6c 20  ence the signal 
5ab0: 69 73 20 6e 65 76 65 72 20 65 6d 69 74 74 65 64  is never emitted
5ac0: 20 66 6f 72 20 69 74 2e 0d 0a 3c 2f 64 6c 3e 0d   for it...</dl>.
5ad0: 0a 3c 2f 64 6c 3e 0d 0a 0d 0a 3c 2f 64 69 76 3e  .</dl>....</div>
5ae0: 0d 0a 0a 5a 20 65 30 62 61 64 64 34 39 32 61 32  ...Z e0badd492a2
5af0: 66 38 64 63 33 62 35 63 63 62 66 36 62 38 35 37  f8dc3b5ccbf6b857
5b00: 64 32 61 65 64 0a                                d2aed.