Re: [MM] API changes for 0.8

[Dan Williams <dcbw redhat com>]

On Thu, 2013-05-30 at 16:56 -0500, Dan Williams wrote:
> On Thu, 2013-05-30 at 14:40 +0200, Aleksander Morgado wrote:
> > Hey,
> >
> > We are reviewing the DBus interfaces in ModemManager before making a 0.8
> > release, and we've come up with several changes to the Modem interface
> > (see list below). Some of the changes are pretty useful, like being able
> > to know which are the allowed+preferred mode combinations supported by
> > the modem before actually trying to change them; or being able to switch
> > capabilities when supported.
> >
> > The changes are available in the "aleksander/api-breaks" branch in git
> > master, please review/test them if you're already using the new
> > ModemManager. The plan is to get the branch merged to git master soon.
> >
> > Cheers!
> >
> > =======================================================================
> > Changes to the 'Modem' interface
> > =======================================================================
> >
> > * MMBearerIpFamily is now flags instead of an enumeration.
> >
> > * A new 'SupportedIpFamilies' property is given (signature "u"), showing
> > which are the IP types that we can use when requesting a connection. The
> > given value is a mask of MMBearerIpFamily flags.
>
> Looks like the changes for QMI to support IPV4V6 didn't quite make it
> into the api-changes branch?
>
>         /* Assume IPv4 + IPv6 supported */
>         g_simple_async_result_set_op_res_gpointer (
>             result,
>             GUINT_TO_POINTER (MM_BEARER_IP_FAMILY_IPV4 |
> MM_BEARER_IP_FAMILY_IPV6),
>             NULL);
>
> Dan
>
> >  * Renamed 'Bands' property to 'CurrentBands'.
> >
> >  * Renamed 'SetBands()' method to 'SetCurrentBands()'.
> >
> >  * Updated the 'SupportedModes' property to give a list of
> > allowed+preferred combinations, instead of just a mask with all allowed
> > ones. Signature changed from "u" to "a(uu)", where each item in the
> > array is a pair of MMModemMode values (first one mask of allowed modes,
> > second one a preferred mode). Modems supporting the change of
> > allowed+preferred modes will expose the combinations they actually
> > support. E.g.:
> >
> >     $> sudo mmcli -m 0
> >       -------------------------
> >       Modes    |      supported: 'allowed: 2g; preferred: none
> >                |                  allowed: 3g; preferred: none
> >                |                  allowed: 2g, 3g; preferred: none
> >                |                  allowed: 2g, 3g; preferred: 2g
> >                |                  allowed: 2g, 3g; preferred: 3g
> >
> >  * Merged the 'AllowedModes' and 'PreferredMode' into a single
> > 'CurrentModes' property, with signature "(uu)". The pair of integers has
> > the same logic as in 'SupportedModes', first one is mask of allowed
> > modes and second one is a preferred mode.
> >
> >  * Renamed 'SetAllowedModes()' method to 'SetCurrentModes()', and
> > updated the argument list to have only one item with signature "(uu)"
> > (allowed mask + preferred). The allowed+preferred combination given must
> > be one of those listed in 'SupportedModes', otherwise the operation will
> > fail.

This probably was the case before, but I noticed that CurrentModes isn't
read from the modem until we enable the modem.  Correspondingly, we
should probably reject any SetCurrentModes() calls unless the modem is
enabled?  If we want to keep this behavior, then we should probably
update the introspection data to note which properties can't be set
until the modem is enabled.

Otherwise, if we allow modes and other stuff to be changed before the
modem is enabled, we should ensure that stuff is read before Enable()
gets called.

I could see an argument for changing bands, capabilities, modes, etc
before the modem is enabled, but I'm pretty sure we should reject
changing these properties while the SIM is locked, since half the time
the AT commands for changing this stuff would be rejected by the device
anyway.  Since the device has to be unlocked in order to be enabled,
perhaps we should just enforce that restriction.

On the other hand, it seems a bit odd to require the  modem to be
powered up and potentially registered to the network to change
properties that would make the modem re-register and reboot, too.  Not
sure it's that big of a deal though?

Dan


> >  * Renamed 'ModemCapabilities' property to 'SupportedCapabilities', and
> > also updated the signature from "u" to "au", where each item in the
> > array is a MMModemCapability mask. Modems supporting the change of
> > capabilities will expose the combinations they actually support. E.g.:
> >     $> sudo mmcli -m 0
> >       -------------------------
> >       Hardware |   supported: 'gsm-umts
> >                |               cdma-evdo
> >                |               gsm-umts, cdma-evdo'
> >                |     current: 'gsm-umts'
> >
> >
> >  * New 'SetCurrentCapabilities()' method, which accepts a "u" specifying
> > the capability combinations wanted (of those listed in
> > 'SupportedCapabilities'). Changing capabilities with this method will
> > force a device power-cycle (modem will disappear and probed again). This
> > method allows to e.g. switch the UML290 from CDMA/EVDO mode to GSM/UMTS
> > mode, as done with the 'uml290mode' program.