Imported Upstream version 1.4.1upstream/1.4.1

4 files changed, 561 insertions, 0 deletions

diff --git a/cmake/tools/CMakeLists.txt b/cmake/tools/CMakeLists.txt
new file mode 100644
index 00000000..e91a5094
--- /dev/null
+++ b/cmake/tools/CMakeLists.txt
@@ -0,0 +1,57 @@
+project(tools)
+
+set (dbus_send_SOURCES
+	../../tools/dbus-print-message.c			
+	../../tools/dbus-print-message.h			
+	../../tools/dbus-send.c
+)
+
+set (dbus_monitor_SOURCES
+	../../tools/dbus-monitor.c				
+	../../tools/dbus-print-message.c			
+	../../tools/dbus-print-message.h
+)
+
+if (WIN32)
+set (dbus_launch_SOURCES
+	../../tools/dbus-launch-win.c
+)
+else (WIN32)
+set (dbus_launch_SOURCES
+	../../tools/dbus-launch.c
+)
+endif (WIN32)
+
+if (DBUS_BUILD_X11)
+set (dbus_launch_SOURCES
+     ${dbus_launch_SOURCES}
+     ../../tools/dbus-launch-x11.c
+)
+endif(DBUS_BUILD_X11)
+
+set (dbus_cleanup_sockets_SOURCES
+	../../tools/dbus-cleanup-sockets.c
+)
+
+set (dbus_viewer_SOURCES
+	../../tools/dbus-names-model.c			
+	../../tools/dbus-names-model.h			
+	../../tools/dbus-tree-view.c			
+	../../tools/dbus-tree-view.h			
+	../../tools/dbus-viewer.c
+)
+
+add_executable(dbus-send ${dbus_send_SOURCES})
+target_link_libraries(dbus-send ${DBUS_LIBRARIES})
+install_targets(/bin dbus-send )
+
+add_executable(dbus-launch ${dbus_launch_SOURCES})
+target_link_libraries(dbus-launch )
+if (DBUS_BUILD_X11)
+  target_link_libraries(dbus-launch ${X11_LIBRARIES} )
+endif (DBUS_BUILD_X11)
+install_targets(/bin dbus-launch )
+
+add_executable(dbus-monitor ${dbus_monitor_SOURCES})
+target_link_libraries(dbus-monitor ${DBUS_LIBRARIES})
+install_targets(/bin dbus-monitor )
diff --git a/cmake/tools/dbus-launch.xml b/cmake/tools/dbus-launch.xml
new file mode 100644
index 00000000..dc34898f
--- /dev/null
+++ b/cmake/tools/dbus-launch.xml
@@ -0,0 +1,240 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<!-- lifted from troff+man by doclifter -->
+<refentry id='dbuslaunch1'>
+<!--   -->
+<!--  dbus\-launch manual page. -->
+<!--  Copyright (C) 2003 Red Hat, Inc. -->
+
+<refmeta>
+<refentrytitle>dbus-launch</refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+<refnamediv id='name'>
+<refname>dbus-launch</refname>
+<refpurpose>Utility to start a message bus from a shell script</refpurpose>
+</refnamediv>
+<!-- body begins here -->
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>dbus-launch</command>    <arg choice='opt'>--version </arg>
+    <arg choice='opt'>--sh-syntax </arg>
+    <arg choice='opt'>--csh-syntax </arg>
+    <arg choice='opt'>--auto-syntax </arg>
+    <arg choice='opt'>--exit-with-session </arg>
+    <arg choice='opt'>--autolaunch=<replaceable>MACHINEID</replaceable></arg>
+    <arg choice='opt'>--config-file=<replaceable>FILENAME</replaceable></arg>
+    <arg choice='opt'><replaceable>PROGRAM</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>ARGS</replaceable></arg>
+    <sbr/>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The <command>dbus-launch</command> command is used to start a session bus 
+instance of <emphasis remap='I'>dbus-daemon</emphasis> from a shell script.
+It would normally be called from a user's login
+scripts. Unlike the daemon itself, <command>dbus-launch</command> exits, so
+backticks or the $() construct can be used to read information from
+<command>dbus-launch</command>.</para>
+
+<para>With no arguments, <command>dbus-launch</command> will launch a session bus
+instance and print the address and pid of that instance to standard
+output.</para>
+
+<para>You may specify a program to be run; in this case, <command>dbus-launch</command>
+will launch a session bus instance, set the appropriate environment
+variables so the specified program can find the bus, and then execute the
+specified program, with the specified arguments.  See below for
+examples.</para>
+
+<para>If you launch a program, <command>dbus-launch</command> will not print the
+information about the new bus to standard output.</para>
+
+<para>When <command>dbus-launch</command> prints bus information to standard output, by
+default it is in a simple key-value pairs format. However, you may 
+request several alternate syntaxes using the --sh-syntax, --csh-syntax,
+--binary-syntax, or
+--auto-syntax options. Several of these cause <command>dbus-launch</command> to emit shell code
+to set up the environment.</para>
+
+<para>With the --auto-syntax option, <command>dbus-launch</command> looks at the value
+of the SHELL environment variable to determine which shell syntax
+should be used.  If SHELL ends in "csh", then csh-compatible code is
+emitted; otherwise Bourne shell code is emitted.  Instead of passing
+--auto-syntax, you may explicity specify a particular one by using
+--sh-syntax for Bourne syntax, or --csh-syntax for csh syntax.
+In scripts, it's more robust to avoid --auto-syntax and you hopefully
+know which shell your script is written in.</para>
+
+
+<para>See <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink> for more information
+about D-Bus. See also the man page for <emphasis remap='I'>dbus-daemon</emphasis>.</para>
+
+
+<para>Here is an example of how to use <command>dbus-launch</command> with an 
+sh-compatible shell to start the per-session bus daemon:</para>
+<literallayout remap='.nf'>
+
+  ## test for an existing bus daemon, just to be safe
+  if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
+      ## if not found, launch a new one
+      eval `dbus-launch --sh-syntax --exit-with-session`
+      echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
+  fi
+
+</literallayout> <!-- .fi -->
+<para>You might run something like that in your login scripts.</para>
+
+
+<para>Another way to use <command>dbus-launch</command> is to run your main session
+program, like so:</para>
+<literallayout remap='.nf'>
+
+dbus-launch gnome-session
+
+</literallayout> <!-- .fi -->
+<para>The above would likely be appropriate for ~/.xsession or ~/.Xclients.</para>
+
+</refsect1>
+
+<refsect1 id='automatic_launching'><title>AUTOMATIC LAUNCHING</title>
+<para>If DBUS_SESSION_BUS_ADDRESS is not set for a process that tries to use
+D-Bus, by default the process will attempt to invoke dbus-launch with
+the --autolaunch option to start up a new session bus or find the 
+existing bus address on the X display or in a file in
+~/.dbus/session-bus/</para>
+
+
+<para>Whenever an autolaunch occurs, the application that had to
+start a new bus will be in its own little world; it can effectively
+end up starting a whole new session if it tries to use a lot of 
+bus services. This can be suboptimal or even totally broken, depending
+on the app and what it tries to do.</para>
+
+
+<para>There are two common reasons for autolaunch. One is ssh to a remote
+machine. The ideal fix for that would be forwarding of
+DBUS_SESSION_BUS_ADDRESS in the same way that DISPLAY is forwarded.
+In the meantime, you can edit the session.conf config file to 
+have your session bus listen on TCP, and manually set
+DBUS_SESSION_BUS_ADDRESS, if you like.</para>
+
+
+<para>The second common reason for autolaunch is an su to another user, and
+display of X applications running as the second user on the display
+belonging to the first user. Perhaps the ideal fix in this case
+would be to allow the second user to connect to the session bus of the
+first user, just as they can connect to the first user's display.
+However, a mechanism for that has not been coded.</para>
+
+
+<para>You can always avoid autolaunch by manually setting
+DBUS_SESSION_BUS_ADDRESS. Autolaunch happens because the default
+address if none is set is "autolaunch:", so if any other address is
+set there will be no autolaunch. You can however include autolaunch in
+an explicit session bus address as a fallback, for example
+DBUS_SESSION_BUS_ADDRESS="something:,autolaunch:" - in that case if
+the first address doesn't work, processes will autolaunch. (The bus
+address variable contains a comma-separated list of addresses to try.)</para>
+
+
+<para>The --autolaunch option is considered an internal implementation
+detail of libdbus, and in fact there are plans to change it. There's
+no real reason to use it outside of the libdbus implementation anyhow.</para>
+
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<para>The following options are supported:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term><option>--auto-syntax</option></term>
+  <listitem>
+<para>Choose --csh-syntax or --sh-syntax based on the SHELL environment variable.</para>
+
+<para><option>--binary-syntax</option>
+Write to stdout a nul-terminated bus address, then the bus PID as a
+binary integer of size sizeof(pid_t), then the bus X window ID as a
+binary integer of size sizeof(long). Integers are in the machine's
+byte order, not network byte order or any other canonical byte order.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--close-stderr</option></term>
+  <listitem>
+<para>Close the standard error output stream before starting the D-Bus
+daemon. This is useful if you want to capture dbus-launch error
+messages but you don't want dbus-daemon to keep the stream open to
+your application.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--config-file=FILENAME</option></term>
+  <listitem>
+<para>Pass --config-file=FILENAME to the bus daemon, instead of passing it 
+the --session argument. See the man page for dbus-daemon</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--csh-syntax</option></term>
+  <listitem>
+<para>Emit csh compatible code to set up environment variables.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--exit-with-session</option></term>
+  <listitem>
+<para>If this option is provided, a persistent "babysitter" process will be 
+created that watches stdin for HUP and tries to connect to the X
+server. If this process gets a HUP on stdin or loses its X connection,
+it kills the message bus daemon.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--autolaunch=MACHINEID</option></term>
+  <listitem>
+<para>This option implies that <command>dbus-launch</command> should scan for a
+previously-started session and reuse the values found there. If no
+session is found, it will start a new session. The
+--exit-with-session option is implied if --autolaunch is given.
+This option is for the exclusive use of libdbus, you do not want to
+use it manually. It may change in the future.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--sh-syntax</option></term>
+  <listitem>
+<para>Emit Bourne-shell compatible code to set up environment variables.</para>
+
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--version</option></term>
+  <listitem>
+<para>Print the version of dbus-launch</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='author'><title>AUTHOR</title>
+<para>See <ulink url='http://www.freedesktop.org/software/dbus/doc/AUTHORS'>http://www.freedesktop.org/software/dbus/doc/AUTHORS</ulink></para>
+
+</refsect1>
+
+<refsect1 id='bugs'><title>BUGS</title>
+<para>Please send bug reports to the D-Bus mailing list or bug tracker,
+see <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink></para>
+</refsect1>
+</refentry>
+
diff --git a/cmake/tools/dbus-monitor.xml b/cmake/tools/dbus-monitor.xml
new file mode 100644
index 00000000..b41cace2
--- /dev/null
+++ b/cmake/tools/dbus-monitor.xml
@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<!-- lifted from troff+man by doclifter -->
+<refentry id='dbusmonitor1'>
+<!--   -->
+<!--  dbus\-monitor manual page. -->
+<!--  Copyright (C) 2003 Red Hat, Inc. -->
+
+<refmeta>
+<refentrytitle>dbus-monitor</refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+<refnamediv id='name'>
+<refname>dbus-monitor</refname>
+<refpurpose>debug probe to print message bus messages</refpurpose>
+</refnamediv>
+<!-- body begins here -->
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>dbus-monitor</command>    
+    <group choice='opt'><arg choice='plain'>--system </arg><arg choice='plain'>--session </arg><arg choice='plain'>--address <replaceable>ADDRESS</replaceable></arg></group>
+    <group choice='opt'><arg choice='plain'>--profile </arg><arg choice='plain'>--monitor </arg></group>
+    <arg choice='opt'><arg choice='plain'><replaceable>watch</replaceable></arg><arg choice='plain'><replaceable>expressions</replaceable></arg></arg>
+    <sbr/>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The <command>dbus-monitor</command> command is used to monitor messages going
+through a D-Bus message bus.  See
+<ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink> for more information about
+the big picture.</para>
+
+
+<para>There are two well-known message buses: the systemwide message bus
+(installed on many systems as the "messagebus" service) and the
+per-user-login-session message bus (started each time a user logs in).
+The --system and --session options direct <command>dbus-monitor</command> to
+monitor the system or session buses respectively.  If neither is
+specified, <command>dbus-monitor</command> monitors the session bus.</para>
+
+
+<para><command>dbus-monitor</command> has two different output modes, the 'classic'-style
+monitoring mode and profiling mode. The profiling format is a compact
+format with a single line per message and microsecond-resolution timing
+information. The --profile and --monitor options select the profiling
+and monitoring output format respectively. If neither is specified,
+<command>dbus-monitor</command> uses the monitoring output format.</para>
+
+
+<para>In order to get <command>dbus-monitor</command> to see the messages you are interested
+in, you should specify a set of watch expressions as you would expect to
+be passed to the <emphasis remap='I'>dbus_bus_add_match</emphasis> function.</para>
+
+
+<para>The message bus configuration may keep <command>dbus-monitor</command> from seeing
+all messages, especially if you run the monitor as a non-root user.</para>
+
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term><option>--system</option></term>
+  <listitem>
+<para>Monitor the system message bus.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--session</option></term>
+  <listitem>
+<para>Monitor the session message bus.  (This is the default.)</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--address ADDRESS</option></term>
+  <listitem>
+<para>Monitor an arbitrary message bus given at ADDRESS.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--profile</option></term>
+  <listitem>
+<para>Use the profiling output format.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--monitor</option></term>
+  <listitem>
+<para>Use the monitoring output format.  (This is the default.)</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='example'><title>EXAMPLE</title>
+<para>Here is an example of using dbus-monitor to watch for the gnome typing
+monitor to say things</para>
+<literallayout remap='.nf'>
+
+  dbus-monitor "type='signal',sender='org.gnome.TypingMonitor',interface='org.gnome.TypingMonitor'"
+
+</literallayout> <!-- .fi -->
+
+</refsect1>
+
+<refsect1 id='author'><title>AUTHOR</title>
+<para>dbus-monitor was written by Philip Blundell.
+The profiling output mode was added by Olli Salli.</para>
+
+</refsect1>
+
+<refsect1 id='bugs'><title>BUGS</title>
+<para>Please send bug reports to the D-Bus mailing list or bug tracker,
+see <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink></para>
+</refsect1>
+</refentry>
+
diff --git a/cmake/tools/dbus-send.xml b/cmake/tools/dbus-send.xml
new file mode 100644
index 00000000..7fefc03e
--- /dev/null
+++ b/cmake/tools/dbus-send.xml
@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<!-- lifted from troff+man by doclifter -->
+<refentry id='dbussend1'>
+<!--   -->
+<!--  dbus\-send manual page. -->
+<!--  Copyright (C) 2003 Red Hat, Inc. -->
+
+<refmeta>
+<refentrytitle>dbus-send</refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+<refnamediv id='name'>
+<refname>dbus-send</refname>
+<refpurpose>Send a message to a message bus</refpurpose>
+</refnamediv>
+<!-- body begins here -->
+<refsynopsisdiv id='synopsis'>
+<cmdsynopsis>
+  <command>dbus-send</command>    
+    <group choice='opt'><arg choice='plain'>--system </arg><arg choice='plain'>--session </arg></group>
+    <arg choice='opt'>--dest=<replaceable>NAME</replaceable></arg>
+    <arg choice='opt'>--print-reply </arg>
+    <arg choice='opt'>--type=<replaceable>TYPE</replaceable></arg>
+    <arg choice='plain'><replaceable>&lt;destination</replaceable></arg>
+    <arg choice='plain'><replaceable>object</replaceable></arg>
+    <arg choice='plain'><replaceable>path&gt;</replaceable></arg>
+    <arg choice='plain'><replaceable>&lt;message</replaceable></arg>
+    <arg choice='plain'><replaceable>name&gt;</replaceable></arg>
+    <arg choice='opt' rep='repeat'><replaceable>contents</replaceable></arg>
+    <sbr/>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>The <command>dbus-send</command> command is used to send a message to a D-Bus message
+bus. See <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink> for more 
+information about the big picture.</para>
+
+
+<para>There are two well-known message buses: the systemwide message bus 
+(installed on many systems as the "messagebus" service) and the 
+per-user-login-session message bus (started each time a user logs in).
+The --system and --session options direct <command>dbus-send</command> to send
+messages to the system or session buses respectively.  If neither is
+specified, <command>dbus-send</command> sends to the session bus.</para>
+
+
+<para>Nearly all uses of <command>dbus-send</command> must provide the --dest argument
+which is the name of a connection on the bus to send the message to. If
+--dest is omitted, no destination is set.</para>
+
+
+<para>The object path and the name of the message to send must always be
+specified. Following arguments, if any, are the message contents
+(message arguments).  These are given as type-specified values and 
+may include containers (arrays, dicts, and variants) as described below.</para>
+
+<literallayout remap='.nf'>
+&lt;contents&gt;   ::= &lt;item&gt; | &lt;container&gt; [ &lt;item&gt; | &lt;container&gt;...]
+&lt;item&gt;       ::= &lt;type&gt;:&lt;value&gt;
+&lt;container&gt;  ::= &lt;array&gt; | &lt;dict&gt; | &lt;variant&gt;
+&lt;array&gt;      ::= array:&lt;type&gt;:&lt;value&gt;[,&lt;value&gt;...] 
+&lt;dict&gt;       ::= dict:&lt;type&gt;:&lt;type&gt;:&lt;key&gt;,&lt;value&gt;[,&lt;key&gt;,&lt;value&gt;...]
+&lt;variant&gt;    ::= variant:&lt;type&gt;:&lt;value&gt;
+&lt;type&gt;       ::= string | int16 | uint 16 | int32 | uint32 | int64 | uint64 | double | byte | boolean | objpath
+</literallayout> <!-- .fi -->
+
+<para>D-Bus supports more types than these, but <command>dbus-send</command> currently
+does not.  Also, <command>dbus-send</command> does not permit empty containers
+or nested containers (e.g. arrays of variants).</para>
+
+
+<para>Here is an example invocation:</para>
+<literallayout remap='.nf'>
+
+  dbus-send --dest=org.freedesktop.ExampleName               \
+            /org/freedesktop/sample/object/name              \
+            org.freedesktop.ExampleInterface.ExampleMethod   \
+            int32:47 string:'hello world' double:65.32       \
+            array:string:"1st item","next item","last item"  \
+            dict:string:int32:"one",1,"two",2,"three",3      \
+            variant:int32:-8                                 \
+            objpath:/org/freedesktop/sample/object/name 
+
+</literallayout> <!-- .fi -->
+
+<para>Note that the interface is separated from a method or signal 
+name by a dot, though in the actual protocol the interface
+and the interface member are separate fields.</para>
+
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+<para>The following options are supported:</para>
+<variablelist remap='TP'>
+  <varlistentry>
+  <term><option>--dest=NAME</option></term>
+  <listitem>
+<para>Specify the name of the connection to receive the message.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--print-reply</option></term>
+  <listitem>
+<para>Block for a reply to the message sent, and print any reply received.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--system</option></term>
+  <listitem>
+<para>Send to the system message bus.</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--session</option></term>
+  <listitem>
+<para>Send to the session message bus.  (This is the default.)</para>
+  </listitem>
+  </varlistentry>
+  <varlistentry>
+  <term><option>--type=TYPE</option></term>
+  <listitem>
+<para>Specify "method_call" or "signal" (defaults to "signal").</para>
+
+  </listitem>
+  </varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='author'><title>AUTHOR</title>
+<para>dbus-send was written by Philip Blundell.</para>
+
+</refsect1>
+
+<refsect1 id='bugs'><title>BUGS</title>
+<para>Please send bug reports to the D-Bus mailing list or bug tracker,
+see <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink></para>
+</refsect1>
+</refentry>
+