src/chromeos/network/network_device_handler.h

   1 // Copyright 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_NETWORK_DEVICE_HANDLER_H_
   6 #define CHROMEOS_NETWORK_NETWORK_DEVICE_HANDLER_H_
   7
   8 #include <string>
   9
  10 #include "base/callback.h"
  11 #include "base/gtest_prod_util.h"
  12 #include "base/memory/weak_ptr.h"
  13 #include "chromeos/chromeos_export.h"
  14 #include "chromeos/network/network_handler.h"
  15 #include "chromeos/network/network_handler_callbacks.h"
  16
  17 namespace base {
  18
  19 class Value;
  20
  21 }  // namespace base
  22
  23 namespace chromeos {
  24
  25 // The NetworkDeviceHandler class allows making device specific requests on a
  26 // ChromeOS network device. All calls are asynchronous and interact with the
  27 // Shill device API. No calls will block on DBus calls.
  28 //
  29 // This is owned and its lifetime managed by the Chrome startup code. It's
  30 // basically a singleton, but with explicit lifetime management.
  31 //
  32 // Note on callbacks: Because all the functions here are meant to be
  33 // asynchronous, they all take a |callback| of some type, and an
  34 // |error_callback|. When the operation succeeds, |callback| will be called, and
  35 // when it doesn't, |error_callback| will be called with information about the
  36 // error, including a symbolic name for the error and often some error message
  37 // that is suitable for logging. None of the error message text is meant for
  38 // user consumption.
  39
  40 class CHROMEOS_EXPORT NetworkDeviceHandler {
  41  public:
  42
  43   // Constants for |error_name| from |error_callback|.
  44   static const char kErrorFailure[];
  45   static const char kErrorIncorrectPin[];
  46   static const char kErrorNotFound[];
  47   static const char kErrorNotSupported[];
  48   static const char kErrorPinBlocked[];
  49   static const char kErrorPinRequired[];
  50   static const char kErrorUnknown[];
  51
  52   virtual ~NetworkDeviceHandler();
  53
  54   // Gets the properties of the device with id |device_path|. See note on
  55   // |callback| and |error_callback|, in class description above.
  56   void GetDeviceProperties(
  57       const std::string& device_path,
  58       const network_handler::DictionaryResultCallback& callback,
  59       const network_handler::ErrorCallback& error_callback) const;
  60
  61   // Sets the value of property |name| on device with id |device_path| to
  62   // |value|.
  63   void SetDeviceProperty(
  64       const std::string& device_path,
  65       const std::string& name,
  66       const base::Value& value,
  67       const base::Closure& callback,
  68       const network_handler::ErrorCallback& error_callback);
  69
  70   // Requests a refresh of the IP configuration for the device specified by
  71   // |device_path| if it exists. This will apply any newly configured
  72   // properties and renew the DHCP lease.
  73   void RequestRefreshIPConfigs(
  74       const std::string& device_path,
  75       const base::Closure& callback,
  76       const network_handler::ErrorCallback& error_callback);
  77
  78   // Requests a network scan on the device specified by |device_path|.
  79   // For cellular networks, the result of this call gets asynchronously stored
  80   // in the corresponding DeviceState object through a property update. For all
  81   // other technologies a service gets created for each found network, which
  82   // can be accessed through the corresponding NetworkState object.
  83   //
  84   // TODO(armansito): Device.ProposeScan is deprecated and the preferred method
  85   // of requesting a network scan is Manager.RequestScan, however shill
  86   // currently doesn't support cellular network scans via Manager.RequestScan.
  87   // Remove this method once shill supports it (crbug.com/262356).
  88   void ProposeScan(
  89       const std::string& device_path,
  90       const base::Closure& callback,
  91       const network_handler::ErrorCallback& error_callback);
  92
  93   // Tells the device specified by |device_path| to register to the cellular
  94   // network with id |network_id|. If |network_id| is empty then registration
  95   // will proceed in automatic mode, which will cause the modem to register
  96   // with the home network.
  97   // This call is only available on cellular devices and will fail with
  98   // Error.NotSupported on all other technologies.
  99   void RegisterCellularNetwork(
 100       const std::string& device_path,
 101       const std::string& network_id,
 102       const base::Closure& callback,
 103       const network_handler::ErrorCallback& error_callback);
 104
 105   // Tells the device to set the modem carrier firmware, as specified by
 106   // |carrier|.
 107   //
 108   // See note on |callback| and |error_callback| in the class description
 109   // above. The operation will fail if:
 110   //    - Device |device_path| could not be found.
 111   //    - |carrier| doesn't match one of the supported carriers, as reported by
 112   //    - Shill.
 113   //    - Operation is not supported by the device.
 114   void SetCarrier(
 115       const std::string& device_path,
 116       const std::string& carrier,
 117       const base::Closure& callback,
 118       const network_handler::ErrorCallback& error_callback);
 119
 120   // SIM PIN/PUK methods
 121
 122   // Tells the device whether or not a SIM PIN lock should be enforced by
 123   // the device referenced by |device_path|. If |require_pin| is true, a PIN
 124   // code (specified in |pin|) will be required before the next time the device
 125   // can be enabled. If |require_pin| is false, the existing requirement will
 126   // be lifted.
 127   //
 128   // See note on |callback| and |error_callback| in the class description
 129   // above. The operation will fail if:
 130   //    - Device |device_path| could not be found.
 131   //    - The PIN requirement status already matches |require_pin|.
 132   //    - |pin| doesn't match the PIN code currently stored by the SIM.
 133   //    - No SIM exists on the device.
 134   //
 135   // This method applies to Cellular devices only. The call will fail with a
 136   // "not-supported" error if called on a non-cellular device.
 137   void RequirePin(
 138       const std::string& device_path,
 139       bool require_pin,
 140       const std::string& pin,
 141       const base::Closure& callback,
 142       const network_handler::ErrorCallback& error_callback);
 143
 144   // Sends the PIN code |pin| to the device |device_path|.
 145   //
 146   // See note on |callback| and |error_callback| in the class description
 147   // above. The operation will fail if:
 148   //    - Device |device_path| could not be found.
 149   //    - |pin| is incorrect.
 150   //    - The SIM is blocked.
 151   //
 152   // This method applies to Cellular devices only. The call will fail with a
 153   // "not-supported" error if called on a non-cellular device.
 154   void EnterPin(
 155       const std::string& device_path,
 156       const std::string& pin,
 157       const base::Closure& callback,
 158       const network_handler::ErrorCallback& error_callback);
 159
 160   // Sends the PUK code |puk| to the SIM to unblock a blocked SIM. On success,
 161   // the SIM will be unblocked and its PIN code will be set to |pin|.
 162   //
 163   // See note on |callback| and |error_callback| in the class description
 164   // above. The operation will fail if:
 165   //    - Device |device_path| could not be found.
 166   //    - |puk| is incorrect.
 167   //
 168   // This method applies to Cellular devices only. The call will fail with a
 169   // "not-supported" error if called on a non-cellular device.
 170   void UnblockPin(
 171       const std::string& device_path,
 172       const std::string& puk,
 173       const std::string& new_pin,
 174       const base::Closure& callback,
 175       const network_handler::ErrorCallback& error_callback);
 176
 177   // Tells the device to change the PIN code used to unlock a locked SIM card.
 178   //
 179   // See note on |callback| and |error_callback| in the class description
 180   // above. The operation will fail if:
 181   //    - Device |device_path| could not be found.
 182   //    - |old_pin| does not match the current PIN on the device.
 183   //    - The SIM is locked.
 184   //    - The SIM is blocked.
 185   //
 186   // This method applies to Cellular devices only. The call will fail with a
 187   // "not-supported" error if called on a non-cellular device.
 188   void ChangePin(
 189       const std::string& device_path,
 190       const std::string& old_pin,
 191       const std::string& new_pin,
 192       const base::Closure& callback,
 193       const network_handler::ErrorCallback& error_callback);
 194
 195  private:
 196   friend class NetworkHandler;
 197   friend class NetworkDeviceHandlerTest;
 198   FRIEND_TEST_ALL_PREFIXES(NetworkDeviceHandlerTest, ErrorTranslation);
 199
 200   NetworkDeviceHandler();
 201
 202   void HandleShillCallFailureForTest(
 203       const std::string& device_path,
 204       const network_handler::ErrorCallback& error_callback,
 205       const std::string& error_name,
 206       const std::string& error_message);
 207
 208   DISALLOW_COPY_AND_ASSIGN(NetworkDeviceHandler);
 209 };
 210
 211 }  // namespace chromeos
 212
 213 #endif  // CHROMEOS_NETWORK_NETWORK_DEVICE_HANDLER_H_