diff options
| -rw-r--r-- | .gitignore | 13 | ||||
| -rw-r--r-- | Makefile.am | 2 | ||||
| -rwxr-xr-x | autogen.sh | 1 | ||||
| -rw-r--r-- | configure.ac | 21 | ||||
| -rw-r--r-- | docs/Makefile.am | 2 | ||||
| -rw-r--r-- | docs/reference/Makefile.am | 2 | ||||
| -rw-r--r-- | docs/reference/api/Makefile.am | 93 | ||||
| -rw-r--r-- | docs/reference/api/mm-docs.xml | 138 | ||||
| -rw-r--r-- | docs/reference/api/mm-overview.xml | 56 | ||||
| -rw-r--r-- | docs/reference/api/mm-sections.txt | 32 | ||||
| -rw-r--r-- | docs/reference/api/mm.types | 0 | ||||
| -rw-r--r-- | docs/reference/api/version.xml.in | 1 |
12 files changed, 360 insertions, 1 deletions
@@ -12,6 +12,7 @@ ltmain.sh intltool-* missing stamp-h1 +gtk-doc.make *~ *.o *.lo @@ -61,6 +62,18 @@ po/insert-header.sin po/quot.sed po/remove-potcdate.sin +docs/reference/api/version.xml +docs/reference/api/mm.args +docs/reference/api/mm.hierarchy +docs/reference/api/mm.interfaces +docs/reference/api/mm.prerequisites +docs/reference/api/mm.signals +docs/reference/api/*.stamp +docs/reference/api/*.txt +docs/reference/api/html +docs/reference/api/tmpl +docs/reference/api/xml + m4/gtk-doc.m4 m4/intltool.m4 m4/libtool.m4 diff --git a/Makefile.am b/Makefile.am index 646df6dd..3dcecc27 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,5 +1,5 @@ -SUBDIRS = . marshallers build-aux include libmm-common libqcdm libwmc src plugins introspection po test +SUBDIRS = . marshallers build-aux include libmm-common libqcdm libwmc src plugins introspection po test docs if WITH_POLKIT SUBDIRS += policy @@ -14,6 +14,7 @@ PKG_NAME=ModemManager } (cd $srcdir; + gtkdocize || exit 1 autopoint --force AUTOPOINT='intltoolize --automake --copy' autoreconf --force --install --verbose if test -z "$NOCONFIGURE"; then diff --git a/configure.ac b/configure.ac index a73e863e..efd24244 100644 --- a/configure.ac +++ b/configure.ac @@ -22,6 +22,23 @@ LT_PREREQ([2.2]) LT_INIT dnl +dnl Documentation +dnl + +AC_ARG_WITH(docs, AS_HELP_STRING([--with-docs], [Build ModemManager documentation])) +AM_CONDITIONAL(WITH_DOCS, test "x$with_docs" = "xyes") +case $with_docs in + yes) + enable_gtk_doc=yes + ;; + *) + with_docs=no + ;; +esac + +GTK_DOC_CHECK(1.0) + +dnl dnl translation support dnl IT_PROG_INTLTOOL([0.40.0]) @@ -172,6 +189,10 @@ test/Makefile introspection/Makefile po/Makefile.in policy/Makefile +docs/Makefile +docs/reference/Makefile +docs/reference/api/Makefile +docs/reference/api/version.xml ]) AC_OUTPUT diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 00000000..cac25f2d --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,2 @@ + +SUBDIRS = reference diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am new file mode 100644 index 00000000..42627b5b --- /dev/null +++ b/docs/reference/Makefile.am @@ -0,0 +1,2 @@ + +SUBDIRS = api diff --git a/docs/reference/api/Makefile.am b/docs/reference/api/Makefile.am new file mode 100644 index 00000000..0c6c3866 --- /dev/null +++ b/docs/reference/api/Makefile.am @@ -0,0 +1,93 @@ + +# The name of the module. +DOC_MODULE = mm + +# The top-level SGML file. +DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml + +# Extra options to supply to gtkdoc-scan +SCAN_OPTIONS = + +# The directory containing the source code. +DOC_SOURCE_DIR = $(top_srcdir)/include + +HFILE_GLOB = +CFILE_GLOB = + +# Headers to ignore +IGNORE_HFILES = \ + ModemManager.h \ + ModemManager-names.h \ + $(NULL) + +# CFLAGS and LDFLAGS for compiling scan program. Only needed +# if $(DOC_MODULE).types is non-empty. +INCLUDES = \ + -I$(srcdir) \ + -I$(top_srcdir) \ + -I$(top_builddir) \ + $(MM_CFLAGS) \ + $(NULL) + +GTKDOC_LIBS = \ + $(MM_LIBS) \ + $(NULL) + +# Extra options to supply to gtkdoc-mkdb +MKDB_OPTIONS = --output-format=xml --sgml-mode --name-space=mm + +# Images to copy into HTML directory +HTML_IMAGES = \ + $(NULL) + +content_files = \ + $(NULL) + +expand_content_files = \ + mm-overview.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 \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Bearer.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Messaging.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Location.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Firmware.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Contacts.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Cdma.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.Ussd.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Simple.xml \ + $(NULL) + +extra_files = \ + $(NULL) + +if ENABLE_GTK_DOC +include $(top_srcdir)/gtk-doc.make +else +EXTRA_DIST = +CLEANFILES = +endif + +EXTRA_DIST += \ + mm-overview.xml \ + version.xml.in \ + $(NULL) + +CLEANFILES += \ + $(DOC_MODULE)-decl-list.txt \ + $(DOC_MODULE)-decl.txt \ + $(DOC_MODULE)-overrides.txt \ + $(DOC_MODULE)-undeclared.txt \ + $(DOC_MODULE)-undocumented.txt \ + $(DOC_MODULE)-overrides.txt \ + $(DOC_MODULE)-unused.txt \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).interfaces \ + $(DOC_MODULE).prerequisites \ + $(DOC_MODULE).signals \ + *.stamp \ + -rf xml html tmpl \ + $(NULL) diff --git a/docs/reference/api/mm-docs.xml b/docs/reference/api/mm-docs.xml new file mode 100644 index 00000000..06e80565 --- /dev/null +++ b/docs/reference/api/mm-docs.xml @@ -0,0 +1,138 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" +"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY version SYSTEM "version.xml"> +]> +<book id="mm" xmlns:xi="http://www.w3.org/2003/XInclude"> + <bookinfo> + <title>ModemManager Reference Manual</title> + <releaseinfo>Version &version;</releaseinfo> + + <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> + </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 + 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 + Documentation License</citetitle> from the Free Software + Foundation by visiting <ulink type="http" + url="http://www.fsf.org">their Web site</ulink> or by writing + to: + <address> + <street>51 Franklin Street</street>, Suite 500 + <city>Boston</city>, <state>MA</state> <postcode>02110-1335</postcode> + <country>USA</country> + </address> + </para> + </legalnotice> + </bookinfo> + + <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.3gpp.xml"/> + <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.Ussd.xml"/> + </section> + <section> + <title>CDMA specific</title> + <xi:include href="../../../libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Cdma.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> + + <index> + <title>Index</title> + </index> + + <chapter id="mm-hierarchy"> + <title>Object Hierarchy</title> + <xi:include href="xml/tree_index.sgml"/> + </chapter> +</book> diff --git a/docs/reference/api/mm-overview.xml b/docs/reference/api/mm-overview.xml new file mode 100644 index 00000000..675acabe --- /dev/null +++ b/docs/reference/api/mm-overview.xml @@ -0,0 +1,56 @@ +<?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" [ +<!ENTITY version SYSTEM "version.xml"> +]> +<part id="overview"> + <title>ModemManager Overview</title> + + <chapter id="overview-modemmanager"> + <title>ModemManager</title> + <para> + ModemManager provides a unified high level API for communicating with + (mobile broadband) modems. While the basic commands are standardized, + the more advanced operations (like signal quality monitoring while + connected) varies a lot. + </para> + + <formalpara> + <title>Using</title> + <para> + ModemManager is a system daemon and is not meant to be used directly from + the command line. However, since it provides DBus API, it is possible to use + 'dbus-send' command to control it from the terminal. There's an example + program (tests/mm-test.py) that demonstrates the basic API usage. + </para> + </formalpara> + + <formalpara> + <title>Implementation</title> + <para> + ModemManager is a DBus system bus activated service (meaning it's started + automatically when a request arrives). It is written in C. The devices are + queried from udev and automatically updated based on hardware events. There's + a GInterface (MMModem) that defines the modem interface and any device specific + implementation must implement it. There are two generic MMModem implementations + to support the basic operations (one for GSM, one for CDMA,) which are common + for all cards. + </para> + </formalpara> + + <formalpara> + <title>Plugins</title> + <para> + Plugins are loaded on startup, and must implement the MMPlugin interface. It + consists of a couple of methods which tell the daemon whether the plugin + supports a port and to create custom MMModem implementations. It most likely + makes sense to derive custom modem implementations from one of the generic + classes and just add (or override) operations which are not standard. There's a + fully working plugin in the plugins/ directory for Huawei cards that can be + used as an example for writing new plugins. Writing new plugins is highly + encouraged! + </para> + </formalpara> + + </chapter> +</part> diff --git a/docs/reference/api/mm-sections.txt b/docs/reference/api/mm-sections.txt new file mode 100644 index 00000000..329414dc --- /dev/null +++ b/docs/reference/api/mm-sections.txt @@ -0,0 +1,32 @@ +<SECTION> +<FILE>mm-enums</FILE> +<TITLE>Flags and Enumerations</TITLE> +MMBearerIpMethod +MMModem3gppFacility +MMModem3gppNetworkAvailability +MMModem3gppRegistrationState +MMModem3gppUssdSessionState +MMModemAccessTech +MMModemBand +MMModemCapability +MMModemCdmaActivationError +MMModemCdmaActivationState +MMModemCdmaRegistrationState +MMModemContactsStorage +MMModemLocationSource +MMModemLock +MMModemMode +MMModemSmsState +MMModemState +MMModemStateChangeReason +</SECTION> + +<SECTION> +<FILE>mm-errors</FILE> +<TITLE>Errors</TITLE> +MMConnectionError +MMCoreError +MMMessageError +MMMobileEquipmentError +MMSerialError +</SECTION> diff --git a/docs/reference/api/mm.types b/docs/reference/api/mm.types new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/docs/reference/api/mm.types diff --git a/docs/reference/api/version.xml.in b/docs/reference/api/version.xml.in new file mode 100644 index 00000000..d78bda93 --- /dev/null +++ b/docs/reference/api/version.xml.in @@ -0,0 +1 @@ +@VERSION@ |