chromeos/network/managed_network_configuration_handler.h

   1 // Copyright (c) 2013 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 #ifndef CHROMEOS_NETWORK_MANAGED_NETWORK_CONFIGURATION_HANDLER_H_
   6 #define CHROMEOS_NETWORK_MANAGED_NETWORK_CONFIGURATION_HANDLER_H_
   7
   8 #include <map>
   9 #include <string>
  10
  11 #include "base/basictypes.h"
  12 #include "base/callback.h"
  13 #include "base/compiler_specific.h"
  14 #include "base/observer_list.h"
  15 #include "chromeos/chromeos_export.h"
  16 #include "chromeos/network/network_handler.h"
  17 #include "chromeos/network/network_handler_callbacks.h"
  18 #include "components/onc/onc_constants.h"
  19
  20 namespace base {
  21 class DictionaryValue;
  22 class ListValue;
  23 }
  24
  25 namespace chromeos {
  26
  27 class NetworkPolicyObserver;
  28
  29 // The ManagedNetworkConfigurationHandler class is used to create and configure
  30 // networks in ChromeOS using ONC and takes care of network policies.
  31 //
  32 // Its interface exposes only ONC and should decouple users from Shill.
  33 // Internally it translates ONC to Shill dictionaries and calls through to the
  34 // NetworkConfigurationHandler.
  35 //
  36 // For accessing lists of visible networks, and other state information, see the
  37 // class NetworkStateHandler.
  38 //
  39 // This is a singleton and its lifetime is managed by the Chrome startup code.
  40 //
  41 // Network configurations are referred to by Shill's service path. These
  42 // identifiers should at most be used to also access network state using the
  43 // NetworkStateHandler, but dependencies to Shill should be avoided. In the
  44 // future, we may switch to other identifiers.
  45 //
  46 // Note on callbacks: Because all the functions here are meant to be
  47 // asynchronous, they all take a |callback| of some type, and an
  48 // |error_callback|. When the operation succeeds, |callback| will be called, and
  49 // when it doesn't, |error_callback| will be called with information about the
  50 // error, including a symbolic name for the error and often some error message
  51 // that is suitable for logging. None of the error message text is meant for
  52 // user consumption.
  53 class CHROMEOS_EXPORT ManagedNetworkConfigurationHandler {
  54  public:
  55   using GuidToPolicyMap = std::map<std::string, const base::DictionaryValue*>;
  56
  57   virtual ~ManagedNetworkConfigurationHandler();
  58
  59   virtual void AddObserver(NetworkPolicyObserver* observer) = 0;
  60   virtual void RemoveObserver(NetworkPolicyObserver* observer) = 0;
  61
  62   // Provides the properties of the network with |service_path| to |callback|.
  63   // |userhash| is used to set the "Source" property. If not provided then
  64   // user polcies will be ignored.
  65   virtual void GetProperties(
  66       const std::string& userhash,
  67       const std::string& service_path,
  68       const network_handler::DictionaryResultCallback& callback,
  69       const network_handler::ErrorCallback& error_callback) = 0;
  70
  71   // Provides the managed properties of the network with |service_path| to
  72   // |callback|. |userhash| is used to ensure that the user's policy is
  73   // already applied, and to set the "Source" property (see note for
  74   // GetProperties).
  75   virtual void GetManagedProperties(
  76       const std::string& userhash,
  77       const std::string& service_path,
  78       const network_handler::DictionaryResultCallback& callback,
  79       const network_handler::ErrorCallback& error_callback) = 0;
  80
  81   // Sets the user's settings of an already configured network with
  82   // |service_path|. A network can be initially configured by calling
  83   // CreateConfiguration or if it is managed by a policy. The given properties
  84   // will be merged with the existing settings, and it won't clear any existing
  85   // properties. This method is expected to be called by a user initiated
  86   // action (see NetworkConfigurationObserver::Source).
  87   virtual void SetProperties(
  88       const std::string& service_path,
  89       const base::DictionaryValue& user_settings,
  90       const base::Closure& callback,
  91       const network_handler::ErrorCallback& error_callback) = 0;
  92
  93   // Initially configures an unconfigured network with the given user settings
  94   // and returns the new identifier to |callback| if successful. Fails if the
  95   // network was already configured by a call to this function or because of a
  96   // policy. The new configuration will be owned by user |userhash|. If
  97   // |userhash| is empty, the new configuration will be shared. This method is
  98   // expected to be called by a user initiated action (see
  99   // NetworkConfigurationObserver::Source).
 100   virtual void CreateConfiguration(
 101       const std::string& userhash,
 102       const base::DictionaryValue& properties,
 103       const network_handler::StringResultCallback& callback,
 104       const network_handler::ErrorCallback& error_callback) const = 0;
 105
 106   // Removes the user's configuration from the network with |service_path|. The
 107   // network may still show up in the visible networks after this, but no user
 108   // configuration will remain. If it was managed, it will still be configured.
 109   // This method is expected to be called by a user initiated action (see
 110   // NetworkConfigurationObserver::Source).
 111   virtual void RemoveConfiguration(
 112       const std::string& service_path,
 113       const base::Closure& callback,
 114       const network_handler::ErrorCallback& error_callback) const = 0;
 115
 116   // Only to be called by NetworkConfigurationUpdater or from tests. Sets
 117   // |network_configs_onc| and |global_network_config| as the current policy of
 118   // |userhash| and |onc_source|. The policy will be applied (not necessarily
 119   // immediately) to Shill's profiles and enforced in future configurations
 120   // until the policy associated with |userhash| and |onc_source| is changed
 121   // again with this function. For device policies, |userhash| must be empty.
 122   virtual void SetPolicy(
 123       ::onc::ONCSource onc_source,
 124       const std::string& userhash,
 125       const base::ListValue& network_configs_onc,
 126       const base::DictionaryValue& global_network_config) = 0;
 127
 128   // Returns true if any policy application is currently running or pending.
 129   // NetworkPolicyObservers are notified about applications finishing.
 130   virtual bool IsAnyPolicyApplicationRunning() const = 0;
 131
 132   // Returns the user policy for user |userhash| or device policy, which has
 133   // |guid|. If |userhash| is empty, only looks for a device policy. If such
 134   // doesn't exist, returns NULL. Sets |onc_source| accordingly.
 135   virtual const base::DictionaryValue* FindPolicyByGUID(
 136       const std::string userhash,
 137       const std::string& guid,
 138       ::onc::ONCSource* onc_source) const = 0;
 139
 140   virtual const GuidToPolicyMap* GetNetworkConfigsFromPolicy(
 141       const std::string& userhash) const = 0;
 142
 143   // Returns the global configuration of the policy of user |userhash| or device
 144   // policy if |userhash| is empty.
 145   virtual const base::DictionaryValue* GetGlobalConfigFromPolicy(
 146       const std::string& userhash) const = 0;
 147
 148   // Returns the policy with |guid| for profile |profile_path|. If such
 149   // doesn't exist, returns NULL.
 150   virtual const base::DictionaryValue* FindPolicyByGuidAndProfile(
 151       const std::string& guid,
 152       const std::string& profile_path) const = 0;
 153
 154  private:
 155   DISALLOW_ASSIGN(ManagedNetworkConfigurationHandler);
 156 };
 157
 158 }  // namespace chromeos
 159
 160 #endif  // CHROMEOS_NETWORK_MANAGED_NETWORK_CONFIGURATION_HANDLER_H_