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 kErrorFailure[];
  37   static const char kErrorIncorrectPin[];
  38   static const char kErrorNotFound[];
  39   static const char kErrorNotSupported[];
  40   static const char kErrorPinBlocked[];
  41   static const char kErrorPinRequired[];
  42   static const char kErrorUnknown[];
  43
  44   NetworkDeviceHandler();
  45   virtual ~NetworkDeviceHandler();
  46
  47   // Gets the properties of the device with id |device_path|. See note on
  48   // |callback| and |error_callback|, in class description above.
  49   virtual void GetDeviceProperties(
  50       const std::string& device_path,
  51       const network_handler::DictionaryResultCallback& callback,
  52       const network_handler::ErrorCallback& error_callback) const = 0;
  53
  54   // Sets the value of property |name| on device with id |device_path| to
  55   // |value|. This function provides a generic setter to be used by the UI or
  56   // network API and doesn't allow changes to protected settings like cellular
  57   // roaming.
  58   virtual void SetDeviceProperty(
  59       const std::string& device_path,
  60       const std::string& property_name,
  61       const base::Value& value,
  62       const base::Closure& callback,
  63       const network_handler::ErrorCallback& error_callback) = 0;
  64
  65   // Requests a refresh of the IP configuration for the device specified by
  66   // |device_path| if it exists. This will apply any newly configured
  67   // properties and renew the DHCP lease.
  68   virtual void RequestRefreshIPConfigs(
  69       const std::string& device_path,
  70       const base::Closure& callback,
  71       const network_handler::ErrorCallback& error_callback) = 0;
  72
  73   // Requests a network scan on the device specified by |device_path|.
  74   // For cellular networks, the result of this call gets asynchronously stored
  75   // in the corresponding DeviceState object through a property update. For all
  76   // other technologies a service gets created for each found network, which
  77   // can be accessed through the corresponding NetworkState object.
  78   //
  79   // TODO(armansito): Device.ProposeScan is deprecated and the preferred method
  80   // of requesting a network scan is Manager.RequestScan, however shill
  81   // currently doesn't support cellular network scans via Manager.RequestScan.
  82   // Remove this method once shill supports it (crbug.com/262356).
  83   virtual void ProposeScan(
  84       const std::string& device_path,
  85       const base::Closure& callback,
  86       const network_handler::ErrorCallback& error_callback) = 0;
  87
  88   // Tells the device specified by |device_path| to register to the cellular
  89   // network with id |network_id|. If |network_id| is empty then registration
  90   // will proceed in automatic mode, which will cause the modem to register
  91   // with the home network.
  92   // This call is only available on cellular devices and will fail with
  93   // Error.NotSupported on all other technologies.
  94   virtual void RegisterCellularNetwork(
  95       const std::string& device_path,
  96       const std::string& network_id,
  97       const base::Closure& callback,
  98       const network_handler::ErrorCallback& error_callback) = 0;
  99
 100   // Tells the device to set the modem carrier firmware, as specified by
 101   // |carrier|.
 102   //
 103   // See note on |callback| and |error_callback| in the class description
 104   // above. The operation will fail if:
 105   //    - Device |device_path| could not be found.
 106   //    - |carrier| doesn't match one of the supported carriers, as reported by
 107   //    - Shill.
 108   //    - Operation is not supported by the device.
 109   virtual void SetCarrier(
 110       const std::string& device_path,
 111       const std::string& carrier,
 112       const base::Closure& callback,
 113       const network_handler::ErrorCallback& error_callback) = 0;
 114
 115   // SIM PIN/PUK methods
 116
 117   // Tells the device whether or not a SIM PIN lock should be enforced by
 118   // the device referenced by |device_path|. If |require_pin| is true, a PIN
 119   // code (specified in |pin|) will be required before the next time the device
 120   // can be enabled. If |require_pin| is false, the existing requirement will
 121   // be lifted.
 122   //
 123   // See note on |callback| and |error_callback| in the class description
 124   // above. The operation will fail if:
 125   //    - Device |device_path| could not be found.
 126   //    - The PIN requirement status already matches |require_pin|.
 127   //    - |pin| doesn't match the PIN code currently stored by the SIM.
 128   //    - No SIM exists on the device.
 129   //
 130   // This method applies to Cellular devices only. The call will fail with a
 131   // "not-supported" error if called on a non-cellular device.
 132   virtual void RequirePin(
 133       const std::string& device_path,
 134       bool require_pin,
 135       const std::string& pin,
 136       const base::Closure& callback,
 137       const network_handler::ErrorCallback& error_callback) = 0;
 138
 139   // Sends the PIN code |pin| to the device |device_path|.
 140   //
 141   // See note on |callback| and |error_callback| in the class description
 142   // above. The operation will fail if:
 143   //    - Device |device_path| could not be found.
 144   //    - |pin| is incorrect.
 145   //    - The SIM is blocked.
 146   //
 147   // This method applies to Cellular devices only. The call will fail with a
 148   // "not-supported" error if called on a non-cellular device.
 149   virtual void EnterPin(
 150       const std::string& device_path,
 151       const std::string& pin,
 152       const base::Closure& callback,
 153       const network_handler::ErrorCallback& error_callback) = 0;
 154
 155   // Sends the PUK code |puk| to the SIM to unblock a blocked SIM. On success,
 156   // the SIM will be unblocked and its PIN code will be set to |pin|.
 157   //
 158   // See note on |callback| and |error_callback| in the class description
 159   // above. The operation will fail if:
 160   //    - Device |device_path| could not be found.
 161   //    - |puk| is incorrect.
 162   //
 163   // This method applies to Cellular devices only. The call will fail with a
 164   // "not-supported" error if called on a non-cellular device.
 165   virtual void UnblockPin(
 166       const std::string& device_path,
 167       const std::string& puk,
 168       const std::string& new_pin,
 169       const base::Closure& callback,
 170       const network_handler::ErrorCallback& error_callback) = 0;
 171
 172   // Tells the device to change the PIN code used to unlock a locked SIM card.
 173   //
 174   // See note on |callback| and |error_callback| in the class description
 175   // above. The operation will fail if:
 176   //    - Device |device_path| could not be found.
 177   //    - |old_pin| does not match the current PIN on the device.
 178   //    - The SIM is locked.
 179   //    - The SIM is blocked.
 180   //
 181   // This method applies to Cellular devices only. The call will fail with a
 182   // "not-supported" error if called on a non-cellular device.
 183   virtual void ChangePin(
 184       const std::string& device_path,
 185       const std::string& old_pin,
 186       const std::string& new_pin,
 187       const base::Closure& callback,
 188       const network_handler::ErrorCallback& error_callback) = 0;
 189
 190   // Enables/disables roaming of all cellular devices. This happens
 191   // asychronously in the background and applies also to devices which become
 192   // available in the future.
 193   virtual void SetCellularAllowRoaming(bool allow_roaming) = 0;
 194
 195  private:
 196   DISALLOW_COPY_AND_ASSIGN(NetworkDeviceHandler);
 197 };
 198
 199 }  // namespace chromeos
 200
 201 #endif  // CHROMEOS_NETWORK_NETWORK_DEVICE_HANDLER_H_