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