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