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