network_device_handler.h revision ca12bfac764ba476d6cd062bf1dde12cc64c3f40
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/gtest_prod_util.h" 12#include "base/memory/weak_ptr.h" 13#include "chromeos/chromeos_export.h" 14#include "chromeos/network/network_handler.h" 15#include "chromeos/network/network_handler_callbacks.h" 16 17namespace base { 18 19class Value; 20 21} // namespace base 22 23namespace chromeos { 24 25// The NetworkDeviceHandler class allows making device specific requests on a 26// ChromeOS network device. All calls are asynchronous and interact with the 27// Shill device API. No calls will block on DBus calls. 28// 29// This is owned and its lifetime managed by the Chrome startup code. It's 30// basically a singleton, but with explicit lifetime management. 31// 32// Note on callbacks: Because all the functions here are meant to be 33// asynchronous, they all take a |callback| of some type, and an 34// |error_callback|. When the operation succeeds, |callback| will be called, and 35// when it doesn't, |error_callback| will be called with information about the 36// error, including a symbolic name for the error and often some error message 37// that is suitable for logging. None of the error message text is meant for 38// user consumption. 39 40class CHROMEOS_EXPORT NetworkDeviceHandler { 41 public: 42 43 // Constants for |error_name| from |error_callback|. 44 static const char kErrorFailure[]; 45 static const char kErrorIncorrectPin[]; 46 static const char kErrorNotFound[]; 47 static const char kErrorNotSupported[]; 48 static const char kErrorPinBlocked[]; 49 static const char kErrorPinRequired[]; 50 static const char kErrorUnknown[]; 51 52 virtual ~NetworkDeviceHandler(); 53 54 // Gets the properties of the device with id |device_path|. See note on 55 // |callback| and |error_callback|, in class description above. 56 void GetDeviceProperties( 57 const std::string& device_path, 58 const network_handler::DictionaryResultCallback& callback, 59 const network_handler::ErrorCallback& error_callback) const; 60 61 // Sets the value of property |name| on device with id |device_path| to 62 // |value|. 63 void SetDeviceProperty( 64 const std::string& device_path, 65 const std::string& name, 66 const base::Value& value, 67 const base::Closure& callback, 68 const network_handler::ErrorCallback& error_callback); 69 70 // Requests a refresh of the IP configuration for the device specified by 71 // |device_path| if it exists. This will apply any newly configured 72 // properties and renew the DHCP lease. 73 void RequestRefreshIPConfigs( 74 const std::string& device_path, 75 const base::Closure& callback, 76 const network_handler::ErrorCallback& error_callback); 77 78 // Tells the device to set the modem carrier firmware, as specified by 79 // |carrier|. 80 // 81 // See note on |callback| and |error_callback| in the class description 82 // above. The operation will fail if: 83 // - Device |device_path| could not be found. 84 // - |carrier| doesn't match one of the supported carriers, as reported by 85 // - Shill. 86 // - Operation is not supported by the device. 87 void SetCarrier( 88 const std::string& device_path, 89 const std::string& carrier, 90 const base::Closure& callback, 91 const network_handler::ErrorCallback& error_callback); 92 93 // SIM PIN/PUK methods 94 95 // Tells the device whether or not a SIM PIN lock should be enforced by 96 // the device referenced by |device_path|. If |require_pin| is true, a PIN 97 // code (specified in |pin|) will be required before the next time the device 98 // can be enabled. If |require_pin| is false, the existing requirement will 99 // be lifted. 100 // 101 // See note on |callback| and |error_callback| in the class description 102 // above. The operation will fail if: 103 // - Device |device_path| could not be found. 104 // - The PIN requirement status already matches |require_pin|. 105 // - |pin| doesn't match the PIN code currently stored by the SIM. 106 // - No SIM exists on the device. 107 // 108 // This method applies to Cellular devices only. The call will fail with a 109 // "not-supported" error if called on a non-cellular device. 110 void RequirePin( 111 const std::string& device_path, 112 bool require_pin, 113 const std::string& pin, 114 const base::Closure& callback, 115 const network_handler::ErrorCallback& error_callback); 116 117 // Sends the PIN code |pin| to the device |device_path|. 118 // 119 // See note on |callback| and |error_callback| in the class description 120 // above. The operation will fail if: 121 // - Device |device_path| could not be found. 122 // - |pin| is incorrect. 123 // - The SIM is blocked. 124 // 125 // This method applies to Cellular devices only. The call will fail with a 126 // "not-supported" error if called on a non-cellular device. 127 void EnterPin( 128 const std::string& device_path, 129 const std::string& pin, 130 const base::Closure& callback, 131 const network_handler::ErrorCallback& error_callback); 132 133 // Sends the PUK code |puk| to the SIM to unblock a blocked SIM. On success, 134 // the SIM will be unblocked and its PIN code will be set to |pin|. 135 // 136 // See note on |callback| and |error_callback| in the class description 137 // above. The operation will fail if: 138 // - Device |device_path| could not be found. 139 // - |puk| is incorrect. 140 // 141 // This method applies to Cellular devices only. The call will fail with a 142 // "not-supported" error if called on a non-cellular device. 143 void UnblockPin( 144 const std::string& device_path, 145 const std::string& puk, 146 const std::string& new_pin, 147 const base::Closure& callback, 148 const network_handler::ErrorCallback& error_callback); 149 150 // Tells the device to change the PIN code used to unlock a locked SIM card. 151 // 152 // See note on |callback| and |error_callback| in the class description 153 // above. The operation will fail if: 154 // - Device |device_path| could not be found. 155 // - |old_pin| does not match the current PIN on the device. 156 // - The SIM is locked. 157 // - The SIM is blocked. 158 // 159 // This method applies to Cellular devices only. The call will fail with a 160 // "not-supported" error if called on a non-cellular device. 161 void ChangePin( 162 const std::string& device_path, 163 const std::string& old_pin, 164 const std::string& new_pin, 165 const base::Closure& callback, 166 const network_handler::ErrorCallback& error_callback); 167 168 private: 169 friend class NetworkHandler; 170 friend class NetworkDeviceHandlerTest; 171 FRIEND_TEST_ALL_PREFIXES(NetworkDeviceHandlerTest, ErrorTranslation); 172 173 NetworkDeviceHandler(); 174 175 void HandleShillCallFailureForTest( 176 const std::string& device_path, 177 const network_handler::ErrorCallback& error_callback, 178 const std::string& error_name, 179 const std::string& error_message); 180 181 DISALLOW_COPY_AND_ASSIGN(NetworkDeviceHandler); 182}; 183 184} // namespace chromeos 185 186#endif // CHROMEOS_NETWORK_NETWORK_DEVICE_HANDLER_H_ 187