docs: improved DBus interface documentation
This commit is contained in:
Aleksander Morgado
@@ -45,6 +45,7 @@ content_files = \
|
||||
|
||||
expand_content_files = \
|
||||
mm-overview.xml \
|
||||
mm-dbus-reference.xml \
|
||||
$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml \
|
||||
$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml \
|
||||
$(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml \
|
||||
@@ -72,6 +73,7 @@ endif
|
||||
|
||||
EXTRA_DIST += \
|
||||
mm-overview.xml \
|
||||
mm-dbus-reference.xml \
|
||||
version.xml.in \
|
||||
$(NULL)
|
||||
|
||||
|
||||
@@ -0,0 +1,179 @@
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||
]>
|
||||
<part id="ref-dbus" xmlns:xi="http://www.w3.org/2003/XInclude">
|
||||
<title>D-Bus Reference</title>
|
||||
|
||||
<chapter id="ref-dbus-bus-name">
|
||||
<title>The <literal>org.freedesktop.ModemManager1</literal> bus name</title>
|
||||
<para>
|
||||
The D-Bus name <literal>org.freedesktop.ModemManager1</literal>
|
||||
on the system bus is used by the ModemManager daemon.
|
||||
</para>
|
||||
<para>
|
||||
If this daemon isn't running, it will be started if D-Bus messages are
|
||||
sent to the name.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="ref-dbus-standard-interfaces">
|
||||
<title>Standard interfaces</title>
|
||||
<para>
|
||||
Please refer to the
|
||||
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">
|
||||
DBus specification at <literal>freedesktop.org</literal>
|
||||
</ulink> for more information on how to use these standard interfaces.
|
||||
</para>
|
||||
<section id="ref-dbus-standard-interfaces-properties">
|
||||
<title>org.freedesktop.DBus.Properties</title>
|
||||
<para>
|
||||
All objects (<link linkend="ref-dbus-object-manager">Manager</link>,
|
||||
<link linkend="ref-dbus-object-modem">Modems</link>,
|
||||
<link linkend="ref-dbus-object-bearer">Bearers</link>,
|
||||
<link linkend="ref-dbus-object-sim">SIMs</link>,
|
||||
<link linkend="ref-dbus-object-sms">SMSs</link>) exported at the
|
||||
<link linkend="ref-dbus-bus-name"><literal>org.freedesktop.ModemManager1</literal></link>
|
||||
bus name implement the standard
|
||||
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">
|
||||
<literal>org.freedesktop.DBus.Properties</literal>
|
||||
</ulink> interface. Objects implementing this interface provide a
|
||||
common way to query for property values and also a generic signal to
|
||||
get notified about changes in those properties.
|
||||
</para>
|
||||
</section>
|
||||
<section id="ref-dbus-standard-interfaces-introspectables">
|
||||
<title>org.freedesktop.DBus.Introspectable</title>
|
||||
<para>
|
||||
All objects (<link linkend="ref-dbus-object-manager">Manager</link>,
|
||||
<link linkend="ref-dbus-object-modem">Modems</link>,
|
||||
<link linkend="ref-dbus-object-bearer">Bearers</link>,
|
||||
<link linkend="ref-dbus-object-sim">SIMs</link>,
|
||||
<link linkend="ref-dbus-object-sms">SMSs</link>) exported at the
|
||||
<link linkend="ref-dbus-bus-name"><literal>org.freedesktop.ModemManager1</literal></link>
|
||||
bus name implement the standard
|
||||
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-introspectable">
|
||||
<literal>org.freedesktop.DBus.Introspectable</literal>
|
||||
</ulink> interface. Objects implementing this interface will provide an
|
||||
XML-based description of the object and its interfaces.
|
||||
</para>
|
||||
</section>
|
||||
<section id="ref-dbus-standard-interfaces-objectmanager">
|
||||
<title>org.freedesktop.DBus.ObjectManager</title>
|
||||
<para>
|
||||
The <link linkend="ref-dbus-object-manager">Manager</link> object
|
||||
exported at the
|
||||
<link linkend="ref-dbus-bus-name"><literal>org.freedesktop.ModemManager1</literal></link>
|
||||
bus name implements the standard
|
||||
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">
|
||||
<literal>org.freedesktop.DBus.ObjectManager</literal>
|
||||
</ulink> interface. This interface, included in rev. 0.17 of the DBus
|
||||
specification, allows a generic way to control the addition and removal
|
||||
of Modem objects, as well as the addition and removal of interfaces in
|
||||
the given objects.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
|
||||
<chapter id="ref-dbus-common-types">
|
||||
<title>Common types</title>
|
||||
<xi:include href="mm-enums.xml"/>
|
||||
<xi:include href="mm-errors.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter id="ref-dbus-object-manager">
|
||||
<title>The <literal>/org/freedesktop/ModemManager1</literal> object</title>
|
||||
<para>
|
||||
The ModemManager process will export an object at the well-known
|
||||
path <literal>/org/freedesktop/ModemManager1</literal>.
|
||||
</para>
|
||||
<para>
|
||||
This object, which implements the standard
|
||||
<link linkend="ref-dbus-standard-interfaces-objectmanager"><literal>org.freedesktop.DBus.ObjectManager</literal></link>, is responsible for managing the list of
|
||||
<link linkend="ref-dbus-object-modem">Modem</link> objects.
|
||||
</para>
|
||||
<para>
|
||||
This object also controls any process-wide operation, such as the log
|
||||
level being used by the daemon.
|
||||
</para>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter id="ref-dbus-object-modem">
|
||||
<title>The <literal>/org/freedesktop/ModemManager/Modems</literal> objects</title>
|
||||
<para>
|
||||
Modem objects are exported in DBus with the following path base:
|
||||
<literal>/org/freedesktop/ModemManager1/Modems/#</literal>, where
|
||||
<literal>#</literal> indicates a unique unsigned integer which identifies
|
||||
the object.
|
||||
</para>
|
||||
<para>
|
||||
The Modem objects will export a generic
|
||||
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem">Modem interface</link>
|
||||
which includes common features and actions applicable to most modem types.
|
||||
This interface, among other actions, allows the management (creation,
|
||||
listing, deletion) of
|
||||
<link linkend="ref-dbus-object-bearer">Bearer</link> objects which can
|
||||
then be used to request the modem to get in connected state.
|
||||
</para>
|
||||
<para>
|
||||
Modem objects will also export the generic
|
||||
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Simple">Simple interface</link>.
|
||||
This interface provides an easy access to the most simple and common
|
||||
operations that may be performed with the modem, including connection and
|
||||
disconnection. Users of the Simple interface do not need to take care of
|
||||
getting the modem registered, and they also don't need to manage the
|
||||
creation of bearers themselves. All the logic required to get the modem
|
||||
connected or disconnected is handled by the Simple interface.
|
||||
</para>
|
||||
<para>
|
||||
Modems with specific 3GPP and/or CDMA capabilities will export modem type
|
||||
specific interfaces, like the
|
||||
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Modem3gpp">3GPP interface</link>
|
||||
or the
|
||||
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.ModemCdma">CDMA interface</link>.
|
||||
</para>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.xml"/>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Simple.xml"/>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Modem3gpp.xml"/>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Modem3gpp.Ussd.xml"/>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.ModemCdma.xml"/>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Messaging.xml"/>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Location.xml"/>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Firmware.xml"/>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Contacts.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter id="ref-dbus-object-bearer">
|
||||
<title>The <literal>/org/freedesktop/ModemManager/Bearers</literal> objects</title>
|
||||
<para>
|
||||
Bearer objects are owned and managed by specific
|
||||
<link linkend="ref-dbus-object-modem">Modem</link> objects. A single Modem
|
||||
may expose one or more Bearer objects, which can then be used to get the
|
||||
modem into connected state.
|
||||
</para>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Bearer.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter id="ref-dbus-object-sim">
|
||||
<title>The <literal>/org/freedesktop/ModemManager/SIMs</literal> objects</title>
|
||||
<para>
|
||||
Broadband modems usually need a SIM card to operate. Each
|
||||
<link linkend="ref-dbus-object-modem">Modem</link> object will therefore
|
||||
expose up to one SIM object, which allows SIM-specific actions such as PIN
|
||||
unlocking.
|
||||
</para>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml"/>
|
||||
</chapter>
|
||||
|
||||
<chapter id="ref-dbus-object-sms">
|
||||
<title>The <literal>/org/freedesktop/ModemManager/SMSs</literal> objects</title>
|
||||
<para>
|
||||
Modems implementing the
|
||||
<link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Messaging">Messaging interface</link>
|
||||
will export one SMS object for each SMS stored in the device.
|
||||
</para>
|
||||
<xi:include href="../../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml"/>
|
||||
</chapter>
|
||||
|
||||
</part>
|
||||
@@ -6,33 +6,43 @@
|
||||
<book id="mm" xmlns:xi="http://www.w3.org/2003/XInclude">
|
||||
<bookinfo>
|
||||
<title>ModemManager Reference Manual</title>
|
||||
<releaseinfo>Version &version;</releaseinfo>
|
||||
<releaseinfo>For ModemManager version &version;</releaseinfo>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Dan</firstname>
|
||||
<surname>Williams</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>dcbw@redhat.com</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Aleksander</firstname>
|
||||
<surname>Morgado</surname>
|
||||
<affiliation>
|
||||
<address>
|
||||
<email>aleksander@lanedo.com</email>
|
||||
</address>
|
||||
</affiliation>
|
||||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<copyright>
|
||||
<year>2008</year>
|
||||
<holder>Novell, Inc.</holder>
|
||||
</copyright>
|
||||
<copyright>
|
||||
<year>2008</year>
|
||||
<year>2009</year>
|
||||
<year>2010</year>
|
||||
<year>2011</year>
|
||||
<holder>Red Hat, Inc.</holder>
|
||||
</copyright>
|
||||
<copyright>
|
||||
<year>2011</year>
|
||||
<holder>The Chromium OS Authors</holder>
|
||||
</copyright>
|
||||
<copyright>
|
||||
<year>2011</year>
|
||||
<holder>Google, Inc.</holder>
|
||||
<year>2012</year>
|
||||
<holder>The ModemManager Authors</holder>
|
||||
</copyright>
|
||||
|
||||
<legalnotice>
|
||||
<para>
|
||||
Permission is granted to copy, distribute and/or modify this
|
||||
document under the terms of the <citetitle>GNU Free
|
||||
Documentation License</citetitle>, Version 1.1 or any later
|
||||
Documentation License</citetitle>, Version 1.3 or any later
|
||||
version published by the Free Software Foundation with no
|
||||
Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
||||
Texts. You may obtain a copy of the <citetitle>GNU Free
|
||||
@@ -41,6 +51,7 @@
|
||||
url="http://www.fsf.org">their Web site</ulink> or by writing
|
||||
to:
|
||||
<address>
|
||||
The Free Software Foundation, Inc.
|
||||
<street>51 Franklin Street</street>, Suite 500
|
||||
<city>Boston</city>, <state>MA</state> <postcode>02110-1335</postcode>
|
||||
<country>USA</country>
|
||||
@@ -49,90 +60,19 @@
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<!-- Part 1, overview -->
|
||||
<xi:include href="xml/mm-overview.xml"/>
|
||||
|
||||
<part id="ref-dbus">
|
||||
<title>D-Bus API Reference</title>
|
||||
|
||||
<chapter id="ref-dbus-objects-names">
|
||||
<title>Objects & Names</title>
|
||||
<sect1 id="ref-dbus-well-known-name">
|
||||
<title>The <literal>org.freedesktop.ModemManager1</literal> bus name</title>
|
||||
<para>
|
||||
The D-Bus name <literal>org.freedesktop.ModemManager1</literal>
|
||||
on the system bus is used by the ModemManager daemon. If this daemon
|
||||
isn't running, it will be started if D-Bus messages are sent to the
|
||||
name.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="ref-dbus-well-known-object">
|
||||
<title>
|
||||
The <literal>/org/freedesktop/ModemManager</literal>
|
||||
and <literal>/org/freedesktop/ModemManager/Modems</literal> objects
|
||||
</title>
|
||||
<para>
|
||||
The ModemManager process will export an object at the well-known
|
||||
path <literal>/org/freedesktop/ModemManager1</literal>. This object can
|
||||
be used to list available modem objects, which will also be exposed
|
||||
on paths with the folowing pattern
|
||||
<literal>/org/freedesktop/ModemManager1/Modems/#</literal>.
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
<title>Common types</title>
|
||||
<xi:include href="xml/mm-enums.xml"/>
|
||||
<xi:include href="xml/mm-errors.xml"/>
|
||||
</chapter>
|
||||
<chapter>
|
||||
<title>Manager interface</title>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml"/>
|
||||
</chapter>
|
||||
<chapter>
|
||||
<title>SIM interface</title>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml"/>
|
||||
</chapter>
|
||||
<chapter>
|
||||
<title>SMS interface</title>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml"/>
|
||||
</chapter>
|
||||
<chapter>
|
||||
<title>Bearer interface</title>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Bearer.xml"/>
|
||||
</chapter>
|
||||
<chapter>
|
||||
<title>Modem interfaces</title>
|
||||
<section>
|
||||
<title>Generic</title>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.xml"/>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Simple.xml"/>
|
||||
</section>
|
||||
<section>
|
||||
<title>3GPP specific</title>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Modem3gpp.xml"/>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Modem3gpp.Ussd.xml"/>
|
||||
</section>
|
||||
<section>
|
||||
<title>CDMA specific</title>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.ModemCdma.xml"/>
|
||||
</section>
|
||||
<section>
|
||||
<title>Other</title>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Messaging.xml"/>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Location.xml"/>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Firmware.xml"/>
|
||||
<xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Contacts.xml"/>
|
||||
</section>
|
||||
</chapter>
|
||||
</part>
|
||||
<!-- Part 2, DBus reference -->
|
||||
<xi:include href="xml/mm-dbus-reference.xml"/>
|
||||
|
||||
<index>
|
||||
<title>Index</title>
|
||||
</index>
|
||||
|
||||
<chapter id="mm-hierarchy">
|
||||
<!-- NOT needed in DBus API -->
|
||||
<!--chapter id="mm-hierarchy">
|
||||
<title>Object Hierarchy</title>
|
||||
<xi:include href="xml/tree_index.sgml"/>
|
||||
</chapter>
|
||||
</chapter-->
|
||||
</book>
|
||||
|
||||
Reference in New Issue
Block a user