diff options
| -rw-r--r-- | docs/reference/api/Makefile.am | 2 | ||||
| -rw-r--r-- | docs/reference/api/ModemManager-docs.xml | 4 | ||||
| -rw-r--r-- | docs/reference/api/ModemManager-migration-reference.xml | 156 |
3 files changed, 162 insertions, 0 deletions
diff --git a/docs/reference/api/Makefile.am b/docs/reference/api/Makefile.am index c8b58a061..3b02ad236 100644 --- a/docs/reference/api/Makefile.am +++ b/docs/reference/api/Makefile.am @@ -63,6 +63,7 @@ content_files = \ expand_content_files = \ ModemManager-overview.xml \ ModemManager-dbus-reference.xml \ + ModemManager-migration-reference.xml \ $(top_builddir)/libmm-glib/generated/mm-gdbus-doc-org.freedesktop.ModemManager1.xml \ $(top_builddir)/libmm-glib/generated/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml \ $(top_builddir)/libmm-glib/generated/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml \ @@ -92,6 +93,7 @@ endif EXTRA_DIST += \ ModemManager-overview.xml \ ModemManager-dbus-reference.xml \ + ModemManager-migration-reference.xml \ version.xml.in \ $(DIAGRAMS) \ $(NULL) diff --git a/docs/reference/api/ModemManager-docs.xml b/docs/reference/api/ModemManager-docs.xml index 97654fb9b..aef28d310 100644 --- a/docs/reference/api/ModemManager-docs.xml +++ b/docs/reference/api/ModemManager-docs.xml @@ -44,6 +44,7 @@ <year>2010</year> <year>2011</year> <year>2012</year> + <year>2013</year> <holder>The ModemManager Authors</holder> </copyright> @@ -75,6 +76,9 @@ <!-- Part 2, DBus reference --> <xi:include href="xml/ModemManager-dbus-reference.xml"/> + <!-- Part 3, Migration reference --> + <xi:include href="xml/ModemManager-migration-reference.xml"/> + <index> <title>Index</title> </index> diff --git a/docs/reference/api/ModemManager-migration-reference.xml b/docs/reference/api/ModemManager-migration-reference.xml new file mode 100644 index 000000000..815c3142c --- /dev/null +++ b/docs/reference/api/ModemManager-migration-reference.xml @@ -0,0 +1,156 @@ +<?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-migrating" xmlns:xi="http://www.w3.org/2003/XInclude"> + <title>Migrating from ModemManager 0.6 to ModemManager 0.8</title> + <partintro> + <para> + ModemManager 0.8 is a new major version of ModemManager that breaks both + API and ABI compared to previous versions. These changes allow better + managing new types of devices (e.g. those with multiple capabilities), + or those not based in AT commands for operation (e.g. QMI or MBIM modems). + </para> + <para> + This section provides an introduction to the changes done in the DBus interface + with respect to the main operations performed with modems through ModemManager. + </para> + </partintro> + + <chapter> + <section> + <title>Listing available modems</title> + <para> + The D-Bus name <literal>org.freedesktop.ModemManager1</literal> + on the system bus is the new name used by the ModemManager 0.8 daemon, and it + implements several standard DBus interfaces, including the new + <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager"> + <literal>org.freedesktop.DBus.ObjectManager</literal> + </ulink> + interface, which allows to list available modem objects and get notifications + where new ones are added or when existing ones are removed. There are therefore + neither a custom method to enumerate devices as in the old 0.6 interface, nor + custom signals to notify about added or removed modems. + </para> + <para> + Modems which are found but are not usable will be flagged with a + <link linkend="MM-MODEM-STATE-FAILED:CAPS"><constant>MM_MODEM_STATE_FAILED</constant></link> + state in the + <link linkend="gdbus-property-org-freedesktop-ModemManager1-Modem.State"> + <literal>State</literal> + </link> + property, and a more detailed reason about the failure will be given in the + <link linkend="gdbus-property-org-freedesktop-ModemManager1-Modem.StateFailedReason"> + <literal>StateFailedReason</literal> + </link> + property. The most common case of failure is to have the SIM missing in a modem which + requires one for operation. + </para> + </section> + + <section> + <title>PIN unlocking</title> + <para> + The process of PIN unlocking the modem is now performed with the + <link linkend="gdbus-method-org-freedesktop-ModemManager1-Sim.SendPin"> + <literal>SendPin()</literal> + </link> + method in the + <link linkend="gdbus-org.freedesktop.ModemManager1.Sim"> + <literal>org.freedesktop.ModemManager1.Sim</literal> + </link> + interface. + </para> + <para> + The path of the SIM object is specified in the + <link linkend="gdbus-property-org-freedesktop-ModemManager1-Modem.Sim"> + <literal>Sim</literal> + </link> + property of the + <link linkend="gdbus-org.freedesktop.ModemManager1.Modem"> + <literal>org.freedesktop.ModemManager1.Modem</literal> + </link> + interface. If the modem doesn't have a SIM, no object path will be given. + </para> + </section> + + <section> + <title>Connection and disconnection</title> + <para> + The process of requesting to connect or disconnect the modem is now split into + two operations: creating a bearer with + <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem.CreateBearer"> + <literal>CreateBearer()</literal> + </link> + in the + <link linkend="gdbus-org.freedesktop.ModemManager1.Modem"> + <literal>org.freedesktop.ModemManager1.Modem</literal> + </link> + interface and getting the bearer connected with + <link linkend="gdbus-method-org-freedesktop-ModemManager1-Bearer.Connect"> + <literal>Connect()</literal> + </link> + in the + <link linkend="gdbus-org.freedesktop.ModemManager1.Bearer"> + <literal>org.freedesktop.ModemManager1.Bearer</literal> + </link> + interface. These two steps are equivalent to the old <literal>Connect()</literal> + method in the previous <literal>org.freedesktop.ModemManager.Modem</literal> + interface. + </para> + <para> + The old <literal>Disconnect()</literal> + method in the previous <literal>org.freedesktop.ModemManager.Modem</literal> + interface is therefore also applied in a per-bearer basis through the new + <link linkend="gdbus-method-org-freedesktop-ModemManager1-Bearer.Disconnect"> + <literal>Disconnect()</literal> + </link> + in the + <link linkend="gdbus-org.freedesktop.ModemManager1.Bearer"> + <literal>org.freedesktop.ModemManager1.Bearer</literal> + </link> + interface. + </para> + <para> + This logic of splitting the connection logic allows ModemManager to create + multiple bearers that may be connected to e.g. different access points (if + the modem allows it). + </para> + </section> + + <section> + <title>Simple connection</title> + <para> + In order to simplify the whole sequence to get the modem connected, ModemManager + still exposes a Simple interface, renamed as: + <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Simple"> + <literal>org.freedesktop.ModemManager1.Modem.Simple</literal> + </link>. + </para> + <para> + The + <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Simple.Connect"> + <literal>Connect()</literal> + </link> + method will create a single bearer with the parameters specified in the call an get + it connected, while the + <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Simple.Disconnect"> + <literal>Disconnect()</literal> + </link> + method will disconnect all available bearers. + </para> + <para> + One of the main differences with respect to the 0.6 interface, is that + <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Simple.Connect"> + <literal>Connect()</literal> + </link> + doesn't support to change allowed modes or bands. Instead, these operations should + be done through the methods in the + <link linkend="gdbus-org.freedesktop.ModemManager1.Modem"> + <literal>org.freedesktop.ModemManager1.Modem</literal> + </link> + interface. + </para> + </section> + </chapter> +</part> |