Add forgetNetwork to networkingPrivate

extensions/common/api/networking_private.json

Index: extensions/common/api/networking_private.json
diff --git a/extensions/common/api/networking_private.json b/extensions/common/api/networking_private.json
index 5d221283c932c4ae61e95661215da17f7c6c0a79..72126ee4df60e64bc4d8c3daf7e7103237c8ec2d 100644
--- a/extensions/common/api/networking_private.json
+++ b/extensions/common/api/networking_private.json
@@ -187,6 +187,24 @@
         ]
       },
       {
+        "name": "forgetNetwork",
+        "description": "Forgets a network configuration, clearing any configured properties.",

[pneubeck (no reviews), 2015/03/16 10:14:58]

Re "Clearing any configured properties.":
The current implementation of MNCH:: / NCH::RemoveConfiguration is that _all_
configurations, both user's and shared, are removed (using that
ProfileEntryDeleter).

I think this is not a good API to expose. All other API functions use GUID as a
_configuration_ identifier and allow control on the granularity of
configurations (e.g. modify the properties of a specific config).

The current behavior of forgetNetwork is like a hammer and simply removes all
configs.

I'd suggest to move towards a finer grained 'removes the configuration with GUID
networkGuid'

In which case we would either remove the user's _or_ the shared config, but not
automatically both.

Wdyt?

If really necessary, we could also expose the GUID of the shared config even if
it's currently hidden/overwritten by the user's config, e.g. by adding a
property with that GUID, or having additional network list entries.

[stevenjb, 2015/03/20 16:52:27]

What you suggest is reasonable, but I do not think it is worth the effort at
this time. We made a UI decision not to make that distinction and I don't expect
that to change any time soon.

The change you suggest will be easier once we migrate all the NetworkHandler
code to use GUID instead of service path.

I will clarify the description in the API for now. If we want to change the
behavior in the future we can add an optional 'source' parameter with the
default behavior being 'all'. The behavior will change slightly (only matching
guids, not identifiers will be removed), but I don't expect that to cause any
problems.

[pneubeck (no reviews), 2015/03/23 14:15:20]

I can believe that it was a UI decision to show at most one configuration per
SSID+SecurityType.
I very much doubt however, that it was a well-thought-out decision to remove all
network configurations at a time from the 'preferred networks' screen.
E.g. if a user indeed ends-up in the case that there is a shared and a private
configuration for the same network and he wants to 'repair' the current
configuration by removing it, he will accidentally remove the shared
configuration that he's very likely unaware of and will potentially break
connectivity on the login-screen and for other users.

Btw. the 'remove all configurations' behavior can be easily polyfilled in JS:
After the removal, get the updated network list and check for a 'similar'
configuration and remove it as well.
Sure, that would work as well. IMO, the default behavior (without providing the
optional 'source' parameter) would be irritating though.
If you want to go this route, pls invert the default:
 - initially make the additional argument mandatory and only support 'all' for
now
 - later add support for specific sources.

[stevenjb, 2015/03/23 16:11:02]

If we had already implemented NCH::RemoveConfiguration as you suggest, I would
have no problem with any of your suggestions. However, spending the time to
modify NCH and test it, only to implement the behavior as-is in the UI, is hard
for me to justify. Especially when adding the suggested behavior later will be
easy / straightforward. (The choice of default behavior won't actually be
important since we will also control the consumers).

(BTW, FWIW, IIRC, when we made the UI decision, we couldn't come up with a non
contrived use case where a user would want to forget a non-shared network that
was also shared, and leave the shared configuration intact).

+        "parameters": [
+          {
+            "name": "networkGuid",
+            "type": "string",
+            "description": "The unique identifier of the network to forget."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [],
+            "description": "A callback function that indicates that network has been forgotten."

[pneubeck (no reviews), 2015/03/16 10:14:58]

the callback itself doesn't indicate success. only if there is no
runtime.lastError set.

Maybe more neutral (and less helpful :-) ): "Will be called after the operation
completed."

[stevenjb, 2015/03/20 16:52:27]

Done.

+          }
+        ]
+      },
+      {
         "name": "getNetworks",
         "description": "Returns a list of network objects with the same properties provided by getState. A filter is provided to specify the type of networks returned and to limit the number of networks. Networks are ordered by the system based on their priority, with connected or connecting networks listed first.",
         "parameters": [