← Back to branch summary

~ubuntu-branches/ubuntu/wily/modemmanager/wily

« back to all changes in this revision

Viewing changes to docs/reference/api/ModemManager-migration-reference.xml

  • Committer: Package Import Robot
  • Author(s): Mathieu Trudel-Lapierre
  • Date: 2013-12-20 15:35:26 UTC
  • mfrom: (1.2.2)
  • Revision ID: package-import@ubuntu.com-20131220153526-j3xu9gp51ltzlizc
Tags: 1.0.0-1
http://bugs.debian.org/728214
http://bugs.debian.org/728215
* New upstream release. (Closes: #728214, #728215)
* debian/control: add a versioned dependency for libqmi -- we need at least
  version 1.4.
* debian/control: build-depends on libmbim-glib-dev 1.4
* debian/rules: run the local autogen.sh rather than gnome-autogen.sh.
* debian/rules: drop --with-tests. 
* debian/rules: clean up after gtk-doc files left around.
* debian/patches/glib_fixes.patch: link against glib explicitly for the
  huawei modem helper tests.
* debian/libmm-glib0.symbols: updated symbols.
* debian/watch: update watch file for new location of upstream source.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/api/ModemManager-migration-reference.xml
 
1
<?xml version="1.0"?>
 
2
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 
4
]>
 
5
<part id="ref-migrating" xmlns:xi="http://www.w3.org/2003/XInclude">
 
6
  <title>Migrating from ModemManager 0.6 to ModemManager 1.0</title>
 
7
  <partintro>
 
8
    <para>
 
9
      ModemManager 1.0 is a new major version of ModemManager that breaks both
 
10
      API and ABI compared to previous versions. These changes allow better
 
11
      managing new types of devices (e.g. those with multiple capabilities),
 
12
      or those not based in AT commands for operation (e.g. QMI or MBIM modems).
 
13
    </para>
 
14
    <para>
 
15
      This section provides an introduction to the changes done in the DBus interface
 
16
      with respect to the main operations performed with modems through ModemManager.
 
17
    </para>
 
18
  </partintro>
 
19
 
 
20
  <chapter>
 
21
    <section>
 
22
      <title>Listing available modems</title>
 
23
      <para>
 
24
        The D-Bus name <literal>org.freedesktop.ModemManager1</literal>
 
25
        on the system bus is the new name used by the ModemManager 1.0 daemon, and it
 
26
        implements several standard DBus interfaces, including the new
 
27
        <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">
 
28
          <literal>org.freedesktop.DBus.ObjectManager</literal>
 
29
        </ulink>
 
30
        interface, which allows to list available modem objects and get notifications
 
31
        where new ones are added or when existing ones are removed. There are therefore
 
32
        neither a custom method to enumerate devices as in the old 0.6 interface, nor
 
33
        custom signals to notify about added or removed modems.
 
34
      </para>
 
35
      <para>
 
36
        Modems which are found but are not usable will be flagged with a
 
37
        <link linkend="MM-MODEM-STATE-FAILED:CAPS"><constant>MM_MODEM_STATE_FAILED</constant></link>
 
38
        state in the
 
39
        <link linkend="gdbus-property-org-freedesktop-ModemManager1-Modem.State">
 
40
          <literal>State</literal>
 
41
        </link>
 
42
        property, and a more detailed reason about the failure will be given in the
 
43
        <link linkend="gdbus-property-org-freedesktop-ModemManager1-Modem.StateFailedReason">
 
44
          <literal>StateFailedReason</literal>
 
45
        </link>
 
46
        property. The most common case of failure is to have the SIM missing in a modem which
 
47
        requires one for operation.
 
48
      </para>
 
49
    </section>
 
50
 
 
51
    <section>
 
52
      <title>PIN unlocking</title>
 
53
      <para>
 
54
        The process of PIN unlocking the modem is now performed with the
 
55
        <link linkend="gdbus-method-org-freedesktop-ModemManager1-Sim.SendPin">
 
56
          <literal>SendPin()</literal>
 
57
        </link>
 
58
        method in the
 
59
        <link linkend="gdbus-org.freedesktop.ModemManager1.Sim">
 
60
          <literal>org.freedesktop.ModemManager1.Sim</literal>
 
61
        </link>
 
62
        interface.
 
63
      </para>
 
64
      <para>
 
65
        The path of the SIM object is specified in the
 
66
        <link linkend="gdbus-property-org-freedesktop-ModemManager1-Modem.Sim">
 
67
          <literal>Sim</literal>
 
68
        </link>
 
69
        property of the
 
70
        <link linkend="gdbus-org.freedesktop.ModemManager1.Modem">
 
71
          <literal>org.freedesktop.ModemManager1.Modem</literal>
 
72
        </link>
 
73
        interface. If the modem doesn't have a SIM, no object path will be given.
 
74
      </para>
 
75
    </section>
 
76
 
 
77
    <section>
 
78
      <title>Connection and disconnection</title>
 
79
      <para>
 
80
        The process of requesting to connect or disconnect the modem is now split into
 
81
        two operations: creating a bearer with
 
82
        <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem.CreateBearer">
 
83
          <literal>CreateBearer()</literal>
 
84
        </link>
 
85
        in the
 
86
        <link linkend="gdbus-org.freedesktop.ModemManager1.Modem">
 
87
          <literal>org.freedesktop.ModemManager1.Modem</literal>
 
88
        </link>
 
89
        interface and getting the bearer connected with
 
90
        <link linkend="gdbus-method-org-freedesktop-ModemManager1-Bearer.Connect">
 
91
          <literal>Connect()</literal>
 
92
        </link>
 
93
        in the
 
94
        <link linkend="gdbus-org.freedesktop.ModemManager1.Bearer">
 
95
          <literal>org.freedesktop.ModemManager1.Bearer</literal>
 
96
        </link>
 
97
        interface. These two steps are equivalent to the old <literal>Connect()</literal>
 
98
        method in the previous <literal>org.freedesktop.ModemManager.Modem</literal>
 
99
        interface.
 
100
      </para>
 
101
      <para>
 
102
        The old <literal>Disconnect()</literal>
 
103
        method in the previous <literal>org.freedesktop.ModemManager.Modem</literal>
 
104
        interface is therefore also applied in a per-bearer basis through the new
 
105
        <link linkend="gdbus-method-org-freedesktop-ModemManager1-Bearer.Disconnect">
 
106
          <literal>Disconnect()</literal>
 
107
        </link>
 
108
        in the
 
109
        <link linkend="gdbus-org.freedesktop.ModemManager1.Bearer">
 
110
          <literal>org.freedesktop.ModemManager1.Bearer</literal>
 
111
        </link>
 
112
        interface.
 
113
      </para>
 
114
      <para>
 
115
        This logic of splitting the connection logic allows ModemManager to create
 
116
        multiple bearers that may be connected to e.g. different access points (if
 
117
        the modem allows it).
 
118
      </para>
 
119
    </section>
 
120
 
 
121
    <section>
 
122
      <title>Simple connection</title>
 
123
      <para>
 
124
        In order to simplify the whole sequence to get the modem connected, ModemManager
 
125
        still exposes a Simple interface, renamed as:
 
126
        <link linkend="gdbus-org.freedesktop.ModemManager1.Modem.Simple">
 
127
          <literal>org.freedesktop.ModemManager1.Modem.Simple</literal>
 
128
          </link>.
 
129
      </para>
 
130
      <para>
 
131
        The
 
132
        <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Simple.Connect">
 
133
          <literal>Connect()</literal>
 
134
        </link>
 
135
        method will create a single bearer with the parameters specified in the call an get
 
136
        it connected, while the
 
137
        <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Simple.Disconnect">
 
138
          <literal>Disconnect()</literal>
 
139
        </link>
 
140
        method will disconnect all available bearers.
 
141
      </para>
 
142
      <para>
 
143
        One of the main differences with respect to the 0.6 interface, is that
 
144
        <link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Simple.Connect">
 
145
          <literal>Connect()</literal>
 
146
        </link>
 
147
        doesn't support to change allowed modes or bands. Instead, these operations should
 
148
        be done through the methods in the
 
149
        <link linkend="gdbus-org.freedesktop.ModemManager1.Modem">
 
150
          <literal>org.freedesktop.ModemManager1.Modem</literal>
 
151
        </link>
 
152
        interface.
 
153
      </para>
 
154
    </section>
 
155
  </chapter>
 
156
</part>