flimflam: add support for multiple profiles

doc/manager-api.txt

Index: doc/manager-api.txt
diff --git a/doc/manager-api.txt b/doc/manager-api.txt
index a8826ed6a2adc61b1626b8fe111928daef18a967..9240e39dbb225e5143e99a3f84222ae20f22df03 100644
--- a/doc/manager-api.txt
+++ b/doc/manager-api.txt
@@ -32,7 +32,63 @@ Methods		dict GetProperties()
 		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
 
@@ -250,7 +306,7 @@ Properties	string State [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