extensions/common/api/networking_config.idl

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>networking.config</code> API to authenticate to captive
   6 // portals.
   7 namespace networking.config {
   8   // Indicator for the type of network used in $(ref:NetworkInfo).
   9   enum NetworkType { WiFi };
  10
  11   // A dictionary identifying filtered networks. One of <code>GUID</code>,
  12   // <code>SSID</code> or <code>HexSSID</code> must be set. <code>BSSID</code>
  13   // and <code>Security</code> are ignored when filtering networks.
  14   dictionary NetworkInfo {
  15     // Currently only WiFi supported.
  16     NetworkType Type;
  17
  18     // A unique identifier of the network.
  19     DOMString? GUID;
  20
  21     // A hex-encoded byte sequence.
  22     DOMString? HexSSID;
  23
  24     // The decoded SSID of the network (default encoding is UTF-8). To filter
  25     // for non-UTF-8 SSIDs, use HexSSID instead.
  26     DOMString? SSID;
  27
  28     // The basic service set identification (BSSID) uniquely identifying the
  29     // basic service set. <code>BSSID</code> is represented as a human readable,
  30     // hex-encoded string with bytes separated by colons, e.g.
  31     // 45:67:89:ab:cd:ef.
  32     DOMString? BSSID;
  33
  34     // Identifier indicating the security type of the network. Valid values are
  35     // <code>None</code>, <code>WEP-PSK</code>, <code>WPA-PSK</code> and
  36     // <code>WPA-EAP</code>.
  37     DOMString? Security;
  38   };
  39
  40   // Argument to $(ref:finishAuthentication) indicating the result of the
  41   // captive portal authentication attempt.
  42   enum AuthenticationResult {
  43     // The extension does not handle this network or captive portal (e.g. server
  44     // end-point not found or not compatible).
  45     unhandled,
  46
  47     // The extension handled this network and authenticated successfully.
  48     succeeded,
  49
  50     // The extension handled this network, tried to authenticate, however was
  51     // rejected by the server.
  52     rejected,
  53
  54     // The extension handled this network, tried to authenticate, however failed
  55     // due to an unspecified error.
  56     failed
  57   };
  58
  59   // Invoked by $(ref:setNetworkFilter) when the respective operation is
  60   // finished.
  61   callback SetNetworkFilterCallback = void();
  62
  63   // Invoked by $(ref:finishAuthentication) when the respective operation is
  64   // finished.
  65   callback FinishAuthenticationCallback = void();
  66
  67   interface Functions {
  68     // Allows an extension to define network filters for the networks it can
  69     // handle. A call to this function will remove all filters previously
  70     // installed by the extension before setting the new list.
  71     // |networks|: Network filters to set. Every <code>NetworkInfo</code> must
  72     //             either have the <code>SSID</code> or <code>HexSSID</code>
  73     //             set. Other fields will be ignored.
  74     // |callback|: Called back when this operation is finished.
  75     void setNetworkFilter(NetworkInfo[] networks,
  76                           SetNetworkFilterCallback callback);
  77
  78     // Called by the extension to notify the network config API that it finished
  79     // a captive portal authentication attempt and hand over the result of the
  80     // attempt. This function must only be called with the GUID of the latest
  81     // $(ref:onCaptivePortalDetected) event.
  82     // |GUID|: Unique network identifier obtained from
  83     //         $(ref:onCaptivePortalDetected).
  84     // |result|: The result of the authentication attempt.
  85     // |callback|: Called back when this operation is finished.
  86     void finishAuthentication(DOMString GUID, AuthenticationResult result,
  87                               optional FinishAuthenticationCallback callback);
  88   };
  89
  90   interface Events {
  91     // This event fires everytime a captive portal is detected on a network
  92     // matching any of the currently registered network filters and the user
  93     // consents to use the extension for authentication. Network filters may be
  94     // set using the $(ref:setNetworkFilter).
  95     // Upon receiving this event the extension should start its authentication
  96     // attempt with the captive portal. When the extension finishes its attempt,
  97     // it must call $(ref:finishAuthentication) with the <code>GUID</code>
  98     // received with this event and the appropriate authentication result.
  99     // |networkInfo|: Information about the network on which a captive portal
 100     // was detected.
 101     static void onCaptivePortalDetected(NetworkInfo networkInfo);
 102   };
 103 };