diff --git a/docs/reference/api/Makefile.am b/docs/reference/api/Makefile.am index c8b58a06..3b02ad23 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 97654fb9..aef28d31 100644 --- a/docs/reference/api/ModemManager-docs.xml +++ b/docs/reference/api/ModemManager-docs.xml @@ -44,6 +44,7 @@ 2010 2011 2012 + 2013 The ModemManager Authors @@ -75,6 +76,9 @@ + + + Index diff --git a/docs/reference/api/ModemManager-migration-reference.xml b/docs/reference/api/ModemManager-migration-reference.xml new file mode 100644 index 00000000..815c3142 --- /dev/null +++ b/docs/reference/api/ModemManager-migration-reference.xml @@ -0,0 +1,156 @@ + + + + Migrating from ModemManager 0.6 to ModemManager 0.8 + + + 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). + + + This section provides an introduction to the changes done in the DBus interface + with respect to the main operations performed with modems through ModemManager. + + + + +
+ Listing available modems + + The D-Bus name org.freedesktop.ModemManager1 + 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 + + org.freedesktop.DBus.ObjectManager + + 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. + + + Modems which are found but are not usable will be flagged with a + MM_MODEM_STATE_FAILED + state in the + + State + + property, and a more detailed reason about the failure will be given in the + + StateFailedReason + + property. The most common case of failure is to have the SIM missing in a modem which + requires one for operation. + +
+ +
+ PIN unlocking + + The process of PIN unlocking the modem is now performed with the + + SendPin() + + method in the + + org.freedesktop.ModemManager1.Sim + + interface. + + + The path of the SIM object is specified in the + + Sim + + property of the + + org.freedesktop.ModemManager1.Modem + + interface. If the modem doesn't have a SIM, no object path will be given. + +
+ +
+ Connection and disconnection + + The process of requesting to connect or disconnect the modem is now split into + two operations: creating a bearer with + + CreateBearer() + + in the + + org.freedesktop.ModemManager1.Modem + + interface and getting the bearer connected with + + Connect() + + in the + + org.freedesktop.ModemManager1.Bearer + + interface. These two steps are equivalent to the old Connect() + method in the previous org.freedesktop.ModemManager.Modem + interface. + + + The old Disconnect() + method in the previous org.freedesktop.ModemManager.Modem + interface is therefore also applied in a per-bearer basis through the new + + Disconnect() + + in the + + org.freedesktop.ModemManager1.Bearer + + interface. + + + 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). + +
+ +
+ Simple connection + + In order to simplify the whole sequence to get the modem connected, ModemManager + still exposes a Simple interface, renamed as: + + org.freedesktop.ModemManager1.Modem.Simple + . + + + The + + Connect() + + method will create a single bearer with the parameters specified in the call an get + it connected, while the + + Disconnect() + + method will disconnect all available bearers. + + + One of the main differences with respect to the 0.6 interface, is that + + Connect() + + doesn't support to change allowed modes or bands. Instead, these operations should + be done through the methods in the + + org.freedesktop.ModemManager1.Modem + + interface. + +
+ +