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.
+
+                        If any existing profile is specified its contents
+                        are reset to a default (minimal) contents.  If the
+                        profile is already registered with a CreateProfile
+                        or PushProfile request then an error is returned.
+
+                        Possible Errors: [service].Error.InvalidArguments
+                                         [service].Error.AlreadyExists
+
+                object PushProfile(string name)
+
+                        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
+
+                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.
+
+                        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)
+                void RemoveProfile(string name)
 
-                        Remove profile with specified object path.
+                        Remove profile with specified identifier.
 
-                        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.
-
-                        At minimum one profile must be available all the time.
+                        The profile may not be resident on the stack.
+                        The default profile may not be removed.
 
                         Possible Errors: [service].Error.InvalidArguments
+                                         [service].Error.AlreadyExists
 
                 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
 
                 void EnableTechnology(string type)
@@ skipping 182 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]
 
                         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.