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..486088208e305c4981518c8815555a275a5e79aa 100644
--- a/doc/manager-api.txt
+++ b/doc/manager-api.txt
@@ -32,22 +32,77 @@ 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.
+
+			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
 
-		void RemoveProfile(object path)
+		object PushProfile(string name)
 
-			Remove profile with specified object path.
+			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.
 
-			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.
+			A profile may be pushed only once.
 
-			At minimum one profile must be available all the time.
+			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(string name)
+
+			Remove profile with specified identifier.
+
+			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)
 
@@ -250,7 +305,7 @@ Properties	string State [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