AC_ARG_ENABLE(verbose-mode, [ --enable-verbose-mode support verbose debug mode],enable_verbose_mode=$enableval,enable_verbose_mode=$USE_MAINTAINER_MODE)
AC_ARG_ENABLE(asserts, [ --enable-asserts include assertion checks],enable_asserts=$enableval,enable_asserts=$USE_MAINTAINER_MODE)
AC_ARG_ENABLE(checks, [ --enable-checks include sanity checks on public API],enable_checks=$enableval,enable_checks=yes)
-AC_ARG_ENABLE(docs, [ --enable-docs build documentation (requires Doxygen and jade)],enable_docs=$enableval,enable_docs=auto)
+AC_ARG_ENABLE(xml-docs, [ --enable-xml-docs build XML documentation (requires xmlto)],enable_xml_docs=$enableval,enable_xml_docs=auto)
+AC_ARG_ENABLE(doxygen-docs, [ --enable-doxygen-docs build DOXYGEN documentation (requires Doxygen)],enable_doxygen_docs=$enableval,enable_doxygen_docs=auto)
AC_ARG_ENABLE(gcov, [ --enable-gcov compile with coverage profiling instrumentation (gcc only)],enable_gcov=$enableval,enable_gcov=no)
AC_ARG_ENABLE(abstract-sockets, [ --enable-abstract-sockets use abstract socket namespace (linux only)],enable_abstract_sockets=$enableval,enable_abstract_sockets=auto)
AC_ARG_ENABLE(gcj, [ --enable-gcj build gcj bindings],enable_gcj=$enableval,enable_gcj=no)
AC_SUBST(DBUS_X_CFLAGS)
AC_SUBST(DBUS_X_LIBS)
-### Documentation
+### Doxygen Documentation
AC_PATH_PROG(DOXYGEN, doxygen, no)
-AC_PATH_PROG(DB2HTML, db2html, no)
-AC_MSG_CHECKING([whether to build documentation])
+AC_MSG_CHECKING([whether to build Doxygen documentation])
-if test x$DOXYGEN = xno -o x$DB2HTML = xno ; then
- have_docs_tools=no
+if test x$DOXYGEN = xno ; then
+ have_doxygen=no
else
- have_docs_tools=yes
+ have_doxygen=yes
fi
-if test x$enable_docs = xauto ; then
- if test x$have_docs_tools = xno ; then
- enable_docs=no
+if test x$enable_doxygen_docs = xauto ; then
+ if test x$have_doxygen = xno ; then
+ enable_doxygen_docs=no
else
- enable_docs=yes
+ enable_doxygen_docs=yes
fi
fi
-if test x$enable_docs = xyes; then
- if test x$have_docs_tools = xno; then
- AC_MSG_ERROR([Building docs explicitly required, but Doxygen or db2html not found])
+if test x$enable_doxygen_docs = xyes; then
+ if test x$have_doxygen = xno; then
+ AC_MSG_ERROR([Building Doxygen docs explicitly required, but Doxygen not found])
fi
fi
-AM_CONDITIONAL(DBUS_DOCS_ENABLED, test x$enable_docs = xyes)
+AM_CONDITIONAL(DBUS_DOXYGEN_DOCS_ENABLED, test x$enable_doxygen_docs = xyes)
+AC_MSG_RESULT(yes)
+
+### XML Documentation
+
+AC_PATH_PROG(XMLTO, xmlto, no)
+
+AC_MSG_CHECKING([whether to build XML documentation])
+
+if test x$XMLTO = xno ; then
+ have_xmlto=no
+else
+ have_xmlto=yes
+fi
+
+if test x$enable_xml_docs = xauto ; then
+ if test x$have_xmlto = xno ; then
+ enable_xml_docs=no
+ else
+ enable_xml_docs=yes
+ fi
+fi
+
+if test x$enable_xml_docs = xyes; then
+ if test x$have_xmlto = xno; then
+ AC_MSG_ERROR([Building XML docs explicitly required, but xmlto not found])
+ fi
+fi
+
+AM_CONDITIONAL(DBUS_XML_DOCS_ENABLED, test x$enable_xml_docs = xyes)
AC_MSG_RESULT(yes)
#### Have to go $localstatedir->$prefix/var->/usr/local/var
cxxflags: ${CXXFLAGS}
64-bit int: ${DBUS_INT64_TYPE}
Doxygen: ${DOXYGEN}
- db2html: ${DB2HTML}"
+ xmlto: ${XMLTO}"
if test x$enable_gcj = xyes ; then
echo \
Building Python bindings: ${have_python}
Building GTK+ tools: ${have_gtk}
Building X11 code: ${enable_x11}
- Building documentation: ${enable_docs}
+ Building Doxygen docs: ${enable_doxygen_docs}
+ Building XML docs: ${enable_xml_docs}
Using XML parser: ${with_xml}
Init scripts style: ${with_init_scripts}
Abstract socket names: ${have_abstract_sockets}
EXTRA_DIST= \
dbus-specification.html \
- dbus-specification.sgml \
+ dbus-specification.xml \
dbus-test-plan.html \
- dbus-test-plan.sgml \
+ dbus-test-plan.xml \
+ dbus-tutorial.html \
+ dbus-tutorial.xml \
dcop-howto.txt \
file-boilerplate.c
-if DBUS_DOCS_ENABLED
-all-local: dbus-specification.html dbus-test-plan.html
+HTML_FILES= \
+ dbus-specification.html \
+ dbus-test-plan.html \
+ dbus-tutorial.html
+
+if DBUS_XML_DOCS_ENABLED
+all-local: $(HTML_FILES)
endif
-## Debian db2html outputs to stdout, so we collect stdout and use
-## it if we didn't get the proper output
+dbus-specification.html: dbus-specification.xml
+ $(XMLTO) html-nochunks $<
-dbus-specification.html: dbus-specification.sgml
- rm -f $@ && \
- $(DB2HTML) -o . --nochunks $< > $@.stdout && \
- (test -e $@ && rm -f $@.stdout || mv $@.stdout $@) && \
- rm -rf $(srcdir)/dbus-specification/stylesheet-images && \
- (if test -d $(srcdir)/dbus-specification ; then \
- rmdir $(srcdir)/dbus-specification ; fi)
+dbus-test-plan.html: dbus-test-plan.xml
+ $(XMLTO) html-nochunks $<
-dbus-test-plan.html: dbus-test-plan.sgml
- rm -f $@ && \
- $(DB2HTML) -o . --nochunks $< > $@.stdout && \
- (test -e $@ && rm -f $@.stdout || mv $@.stdout $@) && \
- rm -rf $(srcdir)/dbus-test-plan/stylesheet-images && \
- (if test -d $(srcdir)/dbus-test-plan ; then \
- rmdir $(srcdir)/dbus-test-plan ; fi)
+dbus-tutorial.html: dbus-tutorial.xml
+ $(XMLTO) html-nochunks $<
maintainer-clean-local:
- rm -f dbus-test-plan.html
- rm -rf dbus-test-plan/stylesheet-images
- test -d dbus-test-plan && rmdir dbus-test-plan
- rm -f dbus-specification.html
- rm -rf dbus-specification/stylesheet-images
- test -d dbus-specification && rmdir dbus-specification
+ rm -f $(HTML_FILES)
-<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
+[
]>
+
<article id="index">
- <artheader>
+ <articleinfo>
<title>D-BUS Specification</title>
<releaseinfo>Version 0.8</releaseinfo>
<date>06 September 2003</date>
<firstname>Havoc</firstname>
<surname>Pennington</surname>
<affiliation>
- <orgname>Red Hat, Inc</orgname>
+ <orgname>Red Hat, Inc.</orgname>
<address>
<email>hp@pobox.com</email>
</address>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
<affiliation>
- <orgname>Red Hat, Inc</orgname>
+ <orgname>Red Hat, Inc.</orgname>
<address>
<email>alexl@redhat.com</email>
</address>
</affiliation>
</author>
</authorgroup>
- </artheader>
+ </articleinfo>
<sect1 id="introduction">
<title>Introduction</title>
</para>
<para>
The base D-BUS protocol is a peer-to-peer protocol, specified in <xref
- linkend="message-protocol">. That is, it is a system for one application
+ linkend="message-protocol"/>. That is, it is a system for one application
to talk to a single other application. However, the primary intended
application of D-BUS is the D-BUS <firstterm>message bus</firstterm>,
- specified in <xref linkend="message-bus">. The message bus is a special
+ specified in <xref linkend="message-bus"/>. The message bus is a special
application that accepts connections from multiple other applications, and
forwards messages among them.
</para>
<title>Header Encoding</title>
<para>
Following the mandatory fields, there are zero or more named fields (see
- <xref linkend="message-protocol-header-fields">), and then nul bytes
+ <xref linkend="message-protocol-header-fields"/>), and then nul bytes
padding the header such that its total length in bytes is a multiple of
8.
</para>
The header MUST begin with the following mandatory fields in the following
order:
<informaltable>
- <tgroup cols=2>
+ <tgroup cols="2">
<thead>
<row>
<entry>Size</entry>
<para>
Types that can appear in the second byte of the header:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Conventional name</entry>
<para>
Flags that can appear in the third byte of the header:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Conventional name</entry>
<title>Header Fields</title>
<para>
In addition to the required header information mentioned
- in <xref linkend="message-protocol-header-encoding">,
+ in <xref linkend="message-protocol-header-encoding"/>,
the header may contain zero or more named
header fields. Future versions of this protocol
specification may add new fields. Implementations must
of which are defined below. Following the name, the field MUST have
a type code represented as a single unsigned byte, and then a
properly-aligned value of that type. See <xref
- linkend="message-protocol-arguments"> for a description of how each
+ linkend="message-protocol-arguments"/> for a description of how each
type is encoded. If an implementation sees a header field name that
it does not understand, it MUST ignore that field.
</para>
<para>
Here are the currently-defined named header fields:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Conventional Name</entry>
<entry>UINT32</entry>
<entry>The serial number of the message this message is a reply
to. (The serial number is one of the mandatory header fields,
- see <xref linkend="message-protocol-header-encoding">.)</entry>
+ see <xref linkend="message-protocol-header-encoding"/>.)</entry>
</row>
<row>
<entry>SERVICE</entry>
<entry>STRING</entry>
<entry>The name of the service this message should be routed to.
Only used in combination with the message bus, see
- <xref linkend="message-bus">.</entry>
+ <xref linkend="message-bus"/>.</entry>
</row>
<row>
<entry>SENDER_SERVICE</entry>
</para>
<para>
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Type name</entry>
<para>
The types are encoded as follows:
<informaltable>
- <tgroup cols=2>
+ <tgroup cols="2">
<thead>
<row>
<entry>Type name</entry>
<itemizedlist>
<listitem><para>AUTH [mechanism] [initial-response]</para></listitem>
- <listitem><para>CANCEL</para></listitem
-
<listitem><para>BEGIN</para></listitem>
-
<listitem><para>DATA <data in base 64 encoding></para></listitem>
-
<listitem><para>ERROR [human-readable error explanation]</para></listitem>
+ <listitem><para>CANCEL</para></listitem>
+ <listitem><para>BEGIN</para></listitem>
+ <listitem><para>DATA <data in base 64 encoding></para></listitem>
+ <listitem><para>ERROR [human-readable error explanation]</para></listitem>
</itemizedlist>
From server to client are as follows:
<sect1 id="standard-messages">
<title>Standard Peer-to-Peer Messages</title>
<para>
- See <xref linkend="message-protocol-types-notation"> for details on
+ See <xref linkend="message-protocol-types-notation"/> for details on
the notation used in this section.
</para>
<sect2 id="standard-messages-ping">
</programlisting>
Message arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</para>
<para>
Messages may have a <literal>SERVICE</literal> field (see <xref
- linkend="message-protocol-header-fields">). When the message bus
+ linkend="message-protocol-header-fields"/>). When the message bus
receives a message, if the <literal>SERVICE</literal> field is absent, the
message is taken to be a standard peer-to-peer message and interpreted
by the message bus itself. For example, sending
daemon looks for <firstterm>service description files</firstterm>.
Service description files define a mapping from service names to
executables. Different kinds of message bus will look for these files
- in different places, see <xref linkend="message-bus-types">.
+ in different places, see <xref linkend="message-bus-types"/>.
</para>
<para>
[FIXME the file format should be much better specified than
<para>
The executable being launched may want to know whether the message bus
activating it is one of the well-known message buses (see <xref
- linkend="message-bus-types">). To facilitate this, the bus MUST also set
+ linkend="message-bus-types"/>). To facilitate this, the bus MUST also set
the <literal>DBUS_ACTIVATION_BUS_TYPE</literal> environment variable if it is one
of the well-known buses. The currently-defined values for this variable
are <literal>system</literal> for the systemwide message bus,
</programlisting>
Reply arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</programlisting>
Reply arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</programlisting>
Message arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</informaltable>
Reply arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</programlisting>
Message arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</informaltable>
Reply arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
specified can be the following values logically ORed together:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Identifier</entry>
The return value can be one of the following values:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Identifier</entry>
</programlisting>
Message arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</programlisting>
Message arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</programlisting>
Message arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</programlisting>
Message arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</programlisting>
Message arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</informaltable>
Reply arguments:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Argument</entry>
</tbody>
</tgroup>
</informaltable>
- Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation">.
+ Tries to launch the executable associated with a service. For more information, see <xref linkend="message-bus-activation"/>.
[FIXME need semantics in much more detail here; for example,
if I activate a service then send it a message, is the message
<para>
The return value can be one of the following values:
<informaltable>
- <tgroup cols=3>
+ <tgroup cols="3">
<thead>
<row>
<entry>Identifier</entry>
An application is said to <firstterm>own</firstterm> a service if the
message bus has associated the application with the service name.
Services may also have <firstterm>secondary owners</firstterm> (see
- <xref linkend="term-secondary-owner">).
+ <xref linkend="term-secondary-owner"/>).
</para>
</glossdef>
</glossentry>
<glossdef>
<para>
".service files" tell the bus how to activate a particular service.
- See <xref linkend="term-activation">
+ See <xref linkend="term-activation"/>
</para>
</glossdef>
</glossentry>
projects / platform / upstream / dbus.git / commitdiff