flimflam: add support for multiple profiles

doc/manager-api.txt

 Manager hierarchy
 =================
 
 Service         org.chromium.flimflam
 Interface       org.chromium.flimflam.Manager
 Object path     /
 
 Methods         dict GetProperties()
 
                         Returns all global system properties. See the
@@ skipping 14 matching lines @@
                 string GetState()
 
                         Return global connection state of a system. The
                         same value is return via the State property.
 
                         Possible Errors: [service].Error.InvalidArguments
 
                 object CreateProfile(string name)
 
                         Create and add new profile with the specified
-                        identifier name.
+                        identifier name.  The name should either be in the
+                        form ``name'' or ``~user/name'' where where ``user''
+                        is the login name of a user suitable for finding
+                        their home directory.  Both strings must contain
+                        only alpha-numeric ASCII characters.
+
+                        Profiles created without a user name are stored in
+                        a system directory readable only by the connection
+                        mananger.  Profiles created with a user name are
+                        stored in the user's home directory but readable
+                        only by, the connection manager.

[Eric Shienbrood, 2011/03/23 21:14:21]

comma not needed.

[Sam Leffler, 2011/03/26 00:30:03]

Done

+
+                        If any existing profile is specified it's contents

[Eric Shienbrood, 2011/03/23 21:14:21]

it's => its

[Sam Leffler, 2011/03/26 00:30:03]

Done

+                        are reset to a default (minimal) contents.
+
+                        Possible Errors: [service].Error.InvalidArguments
+                                         [service].Error.AlreadyExists

[Eric Shienbrood, 2011/03/23 21:14:21]

An AlreadyExists error seems inconsistent with the explanation of what happens
when an existing profile is specified.

[Sam Leffler, 2011/03/26 00:30:03]

Added an explanation that this is returned when a profile was previously
registered with CreateProfile or PushProfile.

+
+                object PushProfile(string name)

[Eric Shienbrood, 2011/03/23 21:14:21]

Why isn't the argument an object path instead of a string? What is the meaning
of the return value?

[Sam Leffler, 2011/03/26 00:30:03]

It's not an object path because there may not be an in-memory object backing the
on-disk profile data.  The usual scenario is that a profile is created once,
then push/pop'd many times.  Since we don't/can't auto-load all the profiles all
you may have is the identifier (e.g. ~chronos/foo).

+
+                        Push the profile with the specified identifier
+                        onto the profile stack.  The profile must have
+                        previously been created with CreateProfile.
+                        The profile becomes the ``active profile'' that
+                        is searched first when loading data and to which
+                        updates are stored.
+
+                        A profile may be pushed only once.
+
+                        Possible Errors: [service].Error.InvalidArguments
+                                         [service].Error.AlreadyExists

[Eric Shienbrood, 2011/03/23 21:14:21]

Is the default profile always at the bottom of the stack?

[Sam Leffler, 2011/03/26 00:30:03]

Not always; you can create an arbitrary stack contents.

+
+                object PopProfile(string name)
+
+                        Pop the top-most profile on the profile stack.
+                        Any profile beneath this profile becomes the
+                        ``active profile''.  Any services using security
+                        settings from the popped profile are disconnected
+                        and the credentials invalidated (the next time
+                        credentials are needed they are loaded from the
+                        (new) active profile).
+
+                        The name must match the identifer of the active
+                        profile.  This is a safeguard against accidentally
+                        removing the wrong profile.
+
+                        Note it is valid to pop all profiles from the
+                        stack; in this state the connection manager does
+                        not write any state to persistent storage.

[Eric Shienbrood, 2011/03/23 21:14:21]

In other words, it's possible to pop the default profile?

[Sam Leffler, 2011/03/26 00:30:03]

Yes, intentionally so.

+
+                        Possible Errors: [service].Error.InvalidArguments
+                                         [service].Error.NotFound
+
+                object PopAnyProfile()
+
+                        Like PopProfile but do not check the profile on
+                        the top of the stack; pop anything.
 
                         Possible Errors: [service].Error.InvalidArguments
 
                 void RemoveProfile(object path)

[Eric Shienbrood, 2011/03/23 21:14:21]

According to the code in manager.c, this now takes a string argument.

[Sam Leffler, 2011/03/26 00:30:03]

Fixed

 
                         Remove profile with specified object path.
 
                         It is not possible to remove the current active
                         profile. To remove the active profile a different
                         one must be selected via ActiveProfile property
                         first.

[Eric Shienbrood, 2011/03/23 21:14:21]

Presumably, the profile is removed from the stack if it is present there?

[Sam Leffler, 2011/03/26 00:30:03]

Actually I forgot to change this language.  The way things are implemented you
cannot remove a profile that is on the stack.  I'm not sure I even want this
method available as I don't see a lot of use for it and it's potentially risky. 
We probably could get away with using touch/rm but having methods encapsulates
the pathnames so I left it.

 
                         At minimum one profile must be available all the time.

[Eric Shienbrood, 2011/03/23 21:14:21]

What does "available" mean here? Above, under PopProfile, it says it's valid to
pop all profiles.

[Sam Leffler, 2011/03/26 00:30:03]

This is leftover; removed.

 
                         Possible Errors: [service].Error.InvalidArguments
 
                 void RequestScan(string type)
 
                         Request to trigger a scan for the specified
                         technology. The empty string "" triggers scanning
                         on all technologies.
 
                         Possible Errors: [service].Error.InvalidArguments
@@ skipping 184 matching lines @@
                 array{string} ConnectedTechnologies [readonly]
 
                         The list of connected technologies. The strings
                         are the same as the ones from the service type.
 
                 string DefaultTechnology [readonly]
 
                         The current connected technology which holds the
                         default route.
 
-                boolean OfflineMode [readwrite]
+                boolean OfflineMode [readonly]

[Eric Shienbrood, 2011/03/23 21:14:21]

According to the code in manager.c, this property is still writable.

[Sam Leffler, 2011/03/26 00:30:03]

This refers to setting the property through a profile object.  I intentionally
removed that since all usage presently goes through the Manager object and
OfflineMode is only meaningful for the default profile.

 
                         The offline mode indicates the global setting for
                         switching all radios on or off. Changing offline mode
                         to true results in powering down all devices. When
                         leaving offline mode the individual policy of each
                         device decides to switch the radio back on or not.
 
                         During offline mode, it is still possible to switch
                         certain technologies manually back on. For example
                         the limited usage of WiFi or Bluetooth devices might
@@ skipping 43 matching lines @@
                         order as the "Services" property above, but this
                         property is not considered "changed" if the ordering
                         changes.
 
                         Changes to this list are batched up for small periods
                         of time, so that batches of changes are collected
                         into a single message containing the final state, and
                         ephemeral changes where the list returns to the
                         previous state are filtered out.