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