// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>networking.config</code> API to authenticate to captive
// portals.
namespace networking.config {
  // Indicator for the type of network used in $(ref:NetworkInfo).
  enum NetworkType { WiFi };

  // A dictionary identifying filtered networks. One of <code>GUID</code>,
  // <code>SSID</code> or <code>HexSSID</code> must be set. <code>BSSID</code>
  // and <code>Security</code> are ignored when filtering networks.
  dictionary NetworkInfo {
    // Currently only WiFi supported.
    NetworkType Type;

    // A unique identifier of the network.
    DOMString? GUID;

    // A hex-encoded byte sequence.
    DOMString? HexSSID;

    // The decoded SSID of the network (default encoding is UTF-8). To filter
    // for non-UTF-8 SSIDs, use HexSSID instead.
    DOMString? SSID;

    // The basic service set identification (BSSID) uniquely identifying the
    // basic service set. <code>BSSID</code> is represented as a human readable,
    // hex-encoded string with bytes separated by colons, e.g.
    // 45:67:89:ab:cd:ef.
    DOMString? BSSID;

    // Identifier indicating the security type of the network. Valid values are
    // <code>None</code>, <code>WEP-PSK</code>, <code>WPA-PSK</code> and
    // <code>WPA-EAP</code>.
    DOMString? Security;
  };

  // Argument to $(ref:finishAuthentication) indicating the result of the
  // captive portal authentication attempt.
  enum AuthenticationResult {
    // The extension does not handle this network or captive portal (e.g. server
    // end-point not found or not compatible).
    unhandled,

    // The extension handled this network and authenticated successfully.
    succeeded,

    // The extension handled this network, tried to authenticate, however was
    // rejected by the server.
    rejected,

    // The extension handled this network, tried to authenticate, however failed
    // due to an unspecified error.
    failed
  };

  // Invoked by $(ref:setNetworkFilter) when the respective operation is
  // finished.
  callback SetNetworkFilterCallback = void();

  // Invoked by $(ref:finishAuthentication) when the respective operation is
  // finished.
  callback FinishAuthenticationCallback = void();

  interface Functions {
    // Allows an extension to define network filters for the networks it can
    // handle. A call to this function will remove all filters previously
    // installed by the extension before setting the new list.
    // |networks|: Network filters to set. Every <code>NetworkInfo</code> must
    //             either have the <code>SSID</code> or <code>HexSSID</code>
    //             set. Other fields will be ignored.
    // |callback|: Called back when this operation is finished.
    void setNetworkFilter(NetworkInfo[] networks,
                          SetNetworkFilterCallback callback);

    // Called by the extension to notify the network config API that it finished
    // a captive portal authentication attempt and hand over the result of the
    // attempt. This function must only be called with the GUID of the latest
    // $(ref:onCaptivePortalDetected) event.
    // |GUID|: Unique network identifier obtained from
    //         $(ref:onCaptivePortalDetected).
    // |result|: The result of the authentication attempt.
    // |callback|: Called back when this operation is finished.
    void finishAuthentication(DOMString GUID, AuthenticationResult result,
                              optional FinishAuthenticationCallback callback);
  };

  interface Events {
    // This event fires everytime a captive portal is detected on a network
    // matching any of the currently registered network filters and the user
    // consents to use the extension for authentication. Network filters may be
    // set using the $(ref:setNetworkFilter).
    // Upon receiving this event the extension should start its authentication
    // attempt with the captive portal. When the extension finishes its attempt,
    // it must call $(ref:finishAuthentication) with the <code>GUID</code>
    // received with this event and the appropriate authentication result.
    // |networkInfo|: Information about the network on which a captive portal
    // was detected.
    static void onCaptivePortalDetected(NetworkInfo networkInfo);
  };
};