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   virtual void GetProperties(
  64       const std::string& service_path,
  65       const network_handler::DictionaryResultCallback& callback,
  66       const network_handler::ErrorCallback& error_callback) = 0;
  67
  68   // Provides the managed properties of the network with |service_path| to
  69   // |callback|. |userhash| is only used to ensure that the user's policy is
  70   // already applied.
  71   virtual void GetManagedProperties(
  72       const std::string& userhash,
  73       const std::string& service_path,
  74       const network_handler::DictionaryResultCallback& callback,
  75       const network_handler::ErrorCallback& error_callback) = 0;
  76
  77   // Sets the user's settings of an already configured network with
  78   // |service_path|. A network can be initially configured by calling
  79   // CreateConfiguration or if it is managed by a policy. The given properties
  80   // will be merged with the existing settings, and it won't clear any existing
  81   // properties.
  82   virtual void SetProperties(
  83       const std::string& service_path,
  84       const base::DictionaryValue& user_settings,
  85       const base::Closure& callback,
  86       const network_handler::ErrorCallback& error_callback) const = 0;
  87
  88   // Initially configures an unconfigured network with the given user settings
  89   // and returns the new identifier to |callback| if successful. Fails if the
  90   // network was already configured by a call to this function or because of a
  91   // policy. The new configuration will be owned by user |userhash|. If
  92   // |userhash| is empty, the new configuration will be shared.
  93   virtual void CreateConfiguration(
  94       const std::string& userhash,
  95       const base::DictionaryValue& properties,
  96       const network_handler::StringResultCallback& callback,
  97       const network_handler::ErrorCallback& error_callback) const = 0;
  98
  99   // Removes the user's configuration from the network with |service_path|. The
 100   // network may still show up in the visible networks after this, but no user
 101   // configuration will remain. If it was managed, it will still be configured.
 102   virtual void RemoveConfiguration(
 103       const std::string& service_path,
 104       const base::Closure& callback,
 105       const network_handler::ErrorCallback& error_callback) const = 0;
 106
 107   // Only to be called by NetworkConfigurationUpdater or from tests. Sets
 108   // |network_configs_onc| and |global_network_config| as the current policy of
 109   // |userhash| and |onc_source|. The policy will be applied (not necessarily
 110   // immediately) to Shill's profiles and enforced in future configurations
 111   // until the policy associated with |userhash| and |onc_source| is changed
 112   // again with this function. For device policies, |userhash| must be empty.
 113   virtual void SetPolicy(
 114       ::onc::ONCSource onc_source,
 115       const std::string& userhash,
 116       const base::ListValue& network_configs_onc,
 117       const base::DictionaryValue& global_network_config) = 0;
 118
 119   // Returns true if any policy application is currently running or pending.
 120   // NetworkPolicyObservers are notified about applications finishing.
 121   virtual bool IsAnyPolicyApplicationRunning() const = 0;
 122
 123   // Returns the user policy for user |userhash| or device policy, which has
 124   // |guid|. If |userhash| is empty, only looks for a device policy. If such
 125   // doesn't exist, returns NULL. Sets |onc_source| accordingly.
 126   virtual const base::DictionaryValue* FindPolicyByGUID(
 127       const std::string userhash,
 128       const std::string& guid,
 129       ::onc::ONCSource* onc_source) const = 0;
 130
 131   virtual const GuidToPolicyMap* GetNetworkConfigsFromPolicy(
 132       const std::string& userhash) const = 0;
 133
 134   // Returns the global configuration of the policy of user |userhash| or device
 135   // policy if |userhash| is empty.
 136   virtual const base::DictionaryValue* GetGlobalConfigFromPolicy(
 137       const std::string& userhash) const = 0;
 138
 139   // Returns the policy with |guid| for profile |profile_path|. If such
 140   // doesn't exist, returns NULL.
 141   virtual const base::DictionaryValue* FindPolicyByGuidAndProfile(
 142       const std::string& guid,
 143       const std::string& profile_path) const = 0;
 144
 145  private:
 146   DISALLOW_ASSIGN(ManagedNetworkConfigurationHandler);
 147 };
 148
 149 }  // namespace chromeos
 150
 151 #endif  // CHROMEOS_NETWORK_MANAGED_NETWORK_CONFIGURATION_HANDLER_H_