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