networking.config API: Add an example to the documentation.

chrome/common/extensions/docs/templates/intros/networking_config.html

Index: chrome/common/extensions/docs/templates/intros/networking_config.html
diff --git a/chrome/common/extensions/docs/templates/intros/networking_config.html b/chrome/common/extensions/docs/templates/intros/networking_config.html
new file mode 100644
index 0000000000000000000000000000000000000000..eb37760608b5393428300b8b9353cb1ca120d7dc
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/intros/networking_config.html
@@ -0,0 +1,75 @@
+<h2 id="usage">Implementing a Captive Portal Authenticator</h2>
+This API allows an Extension to implement an authenticator for captive portals.
+The interaction between Extension, Chrome, and the user will be:
+<ol>
+  <li>Using $(ref:setNetworkFilter), the Extension registers for a list of Wi-Fi
+  networks that it wants to handle captive portals on.</li>
+  <li>If one of these networks is detected by Chrome, it will appear in the
+  network list, badged with an icon to indicate that a captive portal handler is
+  available.</li>
+  <li>If the user selects such a network, but a captive portal is not detected,
+  Chrome will connect as usual - the Extension will never be involved.</li>
+  <li>Otherwise, if a captive portal is detected, the user is notified and asked
+  to authenticate using the registered Extension or whether to visit the captive
+  portal page.</li>
+  <li>If the user selects the Extension, Chrome notifies the Extension through
+  the $(ref:onCaptivePortalDetected) event.</li>
+  <li>The Extension should now interact with the user if necessary and
+  authenticate at the captive portal.</li>
+  <li>Once the Extension finished the authentication, it notifies the API using
+  $(ref:finishAuthentication) about its success or failure.</li>
+</ol>
+
+<p>
+In the Extension, this can look similar to the following snippet:
+</p>
+
+<pre data-filename="background.js">
+var myNetworks = [
+  { Type: 'WiFi', SSID: 'MyHotSpot-1' },
+  { Type: 'WiFi', SSID: 'MyHotSpot-2' }
+];
+
+chrome.networking.config.setNetworkFilter(myNetworks, function() {
+    if (chrome.runtime.lastError) {
+        // Handle Error
+    }
+});
+
+chrome.networking.config.onCaptivePortalDetected.addListener(
+  function(networkInfo) {
+    var guid = networkInfo.GUID;
+
+    // Check at first whether we really care about this network.
+    // This can look at additional network properties like BSSID that are not
+    // supported in the filter.
+    if (isBadNetwork(networkInfo)) {
+      chrome.networking.config.finishAuthentication(guid, 'unhandled');
+      return;
+    }
+    checkForMyCaptivePortalServer(function(serverStatus) {
+      if (serverStatus == 'not-detected') {
+        chrome.networking.config.finishAuthentication(guid, 'unhandled');
+        return;
+      }
+      if (serverStatus == 'error') {
+        chrome.networking.config.finishAuthentication(guid, 'failed');
+        return;
+      }
+
+      // If required, interact with the user, e.g. for registration on first
+      // usage. Credentials can be cached for subsequent authentications.
+      ShowUIToRegisterUser(continueAuthentication.bind(null, guid));
+    });
+});
+
+function continueAuthentication(guid, credentials) {
+  if (!credentials) {
+    chrome.networking.config.finishAuthentication(guid, 'failed');
+  }
+  AuthenticateToMyCaptivePortalServer(credentials, function(success) {
+    chrome.networking.config.finishAuthentication(
+        guid, success ? 'succeeded' : 'rejected');
+  });
+}
+</pre>