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 14namespace base { 15class Value; 16} 17 18namespace 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. 33class 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_ 219