1 // 2 // Copyright (C) 2014 The Android Open Source Project 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // 8 // http://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 // 16 17 #ifndef SHILL_CELLULAR_MOBILE_OPERATOR_INFO_H_ 18 #define SHILL_CELLULAR_MOBILE_OPERATOR_INFO_H_ 19 20 #include <memory> 21 #include <string> 22 #include <vector> 23 24 #include <base/files/file_util.h> 25 #include <base/memory/scoped_vector.h> 26 27 namespace shill { 28 29 class EventDispatcher; 30 class MobileOperatorInfoImpl; 31 32 // An MobileOperatorInfo object encapsulates the knowledge pertaining to all 33 // mobile operators. Typical usage consists of three steps: 34 // - Initialize the object, set database file paths for the operator 35 // information. 36 // - Add observers to be notified whenever an M[V]NO has been determined / any 37 // information about the M[V]NO changes. 38 // - Send operator information updates to the object. 39 // 40 // So a class Foo that wants to use this object typically looks like: 41 // 42 // class Foo { 43 // class OperatorObserver : public MobileOperatorInfoObserver { 44 // // Implement all Observer functions. 45 // } 46 // ... 47 // 48 // MobileOperatorInfo operator_info; 49 // // Optional: Set a non-default database file. 50 // operator_info.ClearDatabasePaths(); 51 // operator_info.AddDatabasePath(some_path); 52 // 53 // operator_info.Init(); // Required. 54 // 55 // OperatorObserver my_observer; 56 // operator_info.AddObserver(my_observer); 57 // ... 58 // operator_info.UpdateIMSI(some_imsi); 59 // operator_info.UpdateName(some_name); 60 // ... 61 // // Whenever enough information is available, |operator_info| notifies us 62 // through |my_observer|. 63 // }; 64 // 65 class MobileOperatorInfo { 66 public: 67 class Observer { 68 public: ~Observer()69 virtual ~Observer() {} 70 71 // This event fires when 72 // - A mobile [virtual] network operator 73 // - is first determined. 74 // - changes. 75 // - becomes invalid. 76 // - Some information about the known operator changes. 77 virtual void OnOperatorChanged() = 0; 78 }; 79 80 // |Init| must be called on the constructed object before it is used. 81 // This object does not take ownership of dispatcher, and |dispatcher| is 82 // expected to outlive this object. 83 MobileOperatorInfo(EventDispatcher* dispatcher, 84 const std::string& info_owner); 85 virtual ~MobileOperatorInfo(); 86 87 // These functions can be called before Init to read non default database 88 // file(s). 89 void ClearDatabasePaths(); 90 void AddDatabasePath(const base::FilePath& absolute_path); 91 92 std::string GetLogPrefix(const char* func) const; 93 bool Init(); 94 95 // Add/remove observers to subscribe to notifications. 96 void AddObserver(MobileOperatorInfo::Observer* observer); 97 void RemoveObserver(MobileOperatorInfo::Observer* observer); 98 99 // /////////////////////////////////////////////////////////////////////////// 100 // Objects that encapsulate related information about the mobile operator. 101 102 // Encapsulates a name and the language that name has been localized to. 103 // The name can be a carrier name, or the name that a cellular carrier 104 // prefers to show for a certain access point. 105 struct LocalizedName { 106 // The name as it appears in the corresponding language. 107 std::string name; 108 // The language of this localized name. The format of a language is a two 109 // letter language code, e.g. 'en' for English. 110 // It is legal for an instance of LocalizedName to have an empty |language| 111 // field, as sometimes the underlying database does not contain that 112 // information. 113 std::string language; 114 }; 115 116 // Encapsulates information on a mobile access point name. This information 117 // is usually necessary for 3GPP networks to be able to connect to a mobile 118 // network. So far, CDMA networks don't use this information. 119 struct MobileAPN { 120 // The access point url, which is fed to the modemmanager while connecting. 121 std::string apn; 122 // A list of localized names for this access point. Usually there is only 123 // one for each country that the associated cellular carrier operates in. 124 std::vector<LocalizedName> operator_name_list; 125 // The username and password fields that are required by the modemmanager. 126 // Either of these values can be empty if none is present. If a MobileAPN 127 // instance that is obtained from this parser contains a non-empty value 128 // for username/password, this usually means that the carrier requires 129 // a certain default pair. 130 std::string username; 131 std::string password; 132 }; 133 134 // Encapsulates information about the Online payment portal used by chrome to 135 // redirect users for some carriers. 136 struct OnlinePortal { 137 std::string url; 138 std::string method; 139 std::string post_data; 140 }; 141 142 // /////////////////////////////////////////////////////////////////////////// 143 // Functions to obtain information about the current mobile operator. 144 // Any of these accessors can return an emtpy response if the information is 145 // not available. Use |IsMobileNetworkOperatorKnown| and 146 // |IsMobileVirtualNetworkOperatorKnown| to determine if a fix on the operator 147 // has been made. Note that the information returned by the other accessors is 148 // only valid when at least |IsMobileNetworkOperatorKnown| returns true. Their 149 // values are undefined otherwise. 150 151 // Query whether a mobile network operator has been successfully determined. 152 virtual bool IsMobileNetworkOperatorKnown() const; 153 // Query whether a mobile network operator has been successfully 154 // determined. 155 bool IsMobileVirtualNetworkOperatorKnown() const; 156 157 158 // The unique identifier of this carrier. This is primarily used to 159 // identify the user profile in store for each carrier. This identifier is 160 // access technology agnostic and should be the same across 3GPP and CDMA. 161 virtual const std::string& uuid() const; 162 163 virtual const std::string& operator_name() const; 164 virtual const std::string& country() const; 165 virtual const std::string& mccmnc() const; 166 const std::string& sid() const; 167 const std::string& nid() const; 168 169 // A given MVNO can be associated with multiple mcc/mnc pairs. A list of all 170 // associated mcc/mnc pairs concatenated together. 171 const std::vector<std::string>& mccmnc_list() const; 172 // A given MVNO can be associated with multiple sid(s). A list of all 173 // associated sid(s). 174 // There are likely many SID values associated with a CDMA carrier as they 175 // vary across regions and are more fine grained than countries. An important 176 // thing to keep in mind is that, since an SID contains fine grained 177 // information on where a modem is physically located, it should be regarded 178 // as user-sensitive information. 179 const std::vector<std::string>& sid_list() const; 180 // All localized names associated with this carrier entry. 181 const std::vector<LocalizedName>& operator_name_list() const; 182 // All access point names associated with this carrier entry. 183 const ScopedVector<MobileAPN>& apn_list() const; 184 // All Online Payment Portal URLs associated with this carrier entry. There 185 // are usually multiple OLPs based on access technology and it is up to the 186 // application to use the appropriate one. 187 virtual const std::vector<OnlinePortal>& olp_list() const; 188 189 // The number to dial for automatic activation. 190 virtual const std::string& activation_code() const; 191 // Some carriers are only available while roaming. This is mainly used by 192 // Chrome. 193 bool requires_roaming() const; 194 195 // /////////////////////////////////////////////////////////////////////////// 196 // Functions used to notify this object of operator data changes. 197 // The Update* methods update the corresponding property of the network 198 // operator, and this value may be used to determine the M[V]NO. 199 // These values are also the values reported through accessors, overriding any 200 // information from the database. 201 202 // Throw away all information provided to the object, and start from top. 203 void Reset(); 204 205 // Both MCCMNC and SID correspond to operator code in the different 206 // technologies. They are never to be used together. If you want to use SID 207 // after MCCMNC (or vice-versa), ensure a call to |Reset| to clear state. 208 virtual void UpdateMCCMNC(const std::string& mccmnc); 209 virtual void UpdateSID(const std::string& sid); 210 211 virtual void UpdateIMSI(const std::string& imsi); 212 void UpdateICCID(const std::string& iccid); 213 virtual void UpdateNID(const std::string& nid); 214 virtual void UpdateOperatorName(const std::string& operator_name); 215 void UpdateOnlinePortal(const std::string& url, 216 const std::string& method, 217 const std::string& post_data); 218 219 // /////////////////////////////////////////////////////////////////////////// 220 // Expose implementation for test purposes only. impl()221 MobileOperatorInfoImpl* impl() { return impl_.get(); } 222 223 private: 224 std::unique_ptr<MobileOperatorInfoImpl> impl_; 225 DISALLOW_COPY_AND_ASSIGN(MobileOperatorInfo); 226 }; 227 228 } // namespace shill 229 230 #endif // SHILL_CELLULAR_MOBILE_OPERATOR_INFO_H_ 231