blob: 39627139fa33b15c7eded7bf270454c009911776 [file] [log] [blame]
// Copyright (C) 2014 The Android Open Source Project
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
#include <memory>
#include <string>
#include <vector>
#include <base/files/file_util.h>
namespace shill {
class EventDispatcher;
class MobileOperatorInfoImpl;
// An MobileOperatorInfo object encapsulates the knowledge pertaining to all
// mobile operators. Typical usage consists of three steps:
// - Initialize the object, set database file paths for the operator
// information.
// - Add observers to be notified whenever an M[V]NO has been determined / any
// information about the M[V]NO changes.
// - Send operator information updates to the object.
// So a class Foo that wants to use this object typically looks like:
// class Foo {
// class OperatorObserver : public MobileOperatorInfoObserver {
// // Implement all Observer functions.
// }
// ...
// MobileOperatorInfo operator_info;
// // Optional: Set a non-default database file.
// operator_info.ClearDatabasePaths();
// operator_info.AddDatabasePath(some_path);
// operator_info.Init(); // Required.
// OperatorObserver my_observer;
// operator_info.AddObserver(my_observer);
// ...
// operator_info.UpdateIMSI(some_imsi);
// operator_info.UpdateName(some_name);
// ...
// // Whenever enough information is available, |operator_info| notifies us
// through |my_observer|.
// };
class MobileOperatorInfo {
class Observer {
virtual ~Observer() {}
// This event fires when
// - A mobile [virtual] network operator
// - is first determined.
// - changes.
// - becomes invalid.
// - Some information about the known operator changes.
virtual void OnOperatorChanged() = 0;
// |Init| must be called on the constructed object before it is used.
// This object does not take ownership of dispatcher, and |dispatcher| is
// expected to outlive this object.
MobileOperatorInfo(EventDispatcher* dispatcher,
const std::string& info_owner);
virtual ~MobileOperatorInfo();
// These functions can be called before Init to read non default database
// file(s). Files included earlier will take precedence over later additions.
void ClearDatabasePaths();
void AddDatabasePath(const base::FilePath& absolute_path);
std::string GetLogPrefix(const char* func) const;
bool Init();
// Add/remove observers to subscribe to notifications.
void AddObserver(MobileOperatorInfo::Observer* observer);
void RemoveObserver(MobileOperatorInfo::Observer* observer);
// ///////////////////////////////////////////////////////////////////////////
// Objects that encapsulate related information about the mobile operator.
// Encapsulates a name and the language that name has been localized to.
// The name can be a carrier name, or the name that a cellular carrier
// prefers to show for a certain access point.
struct LocalizedName {
// The name as it appears in the corresponding language.
std::string name;
// The language of this localized name. The format of a language is a two
// letter language code, e.g. 'en' for English.
// It is legal for an instance of LocalizedName to have an empty |language|
// field, as sometimes the underlying database does not contain that
// information.
std::string language;
// Encapsulates information on a mobile access point name. This information
// is usually necessary for 3GPP networks to be able to connect to a mobile
// network. So far, CDMA networks don't use this information.
struct MobileAPN {
// The access point url, which is fed to the modemmanager while connecting.
std::string apn;
// A list of localized names for this access point. Usually there is only
// one for each country that the associated cellular carrier operates in.
std::vector<LocalizedName> operator_name_list;
// The username and password fields that are required by the modemmanager.
// Either of these values can be empty if none is present. If a MobileAPN
// instance that is obtained from this parser contains a non-empty value
// for username/password, this usually means that the carrier requires
// a certain default pair.
std::string username;
std::string password;
// The authentication method for sending username / password, which could
// be one of the following values:
// * (empty):
// - When no username or password is provided, no authentication method
// is specified.
// - When a username and password is provided, the default authentication
// method is used (which is PAP for most cases in the current
// implementation of ModemManager).
// * "pap" (kApnAuthenticationPap):
// - Password Authentication Protocol (PAP) is used for authentication
// * "chap" (kApnAuthenticationChap):
// - Challenge-Handshake Authentication Protocol (CHAP) for authentication
std::string authentication;
// Encapsulates information about the Online payment portal used by chrome to
// redirect users for some carriers.
struct OnlinePortal {
std::string url;
std::string method;
std::string post_data;
// ///////////////////////////////////////////////////////////////////////////
// Functions to obtain information about the current mobile operator.
// Any of these accessors can return an emtpy response if the information is
// not available. Use |IsMobileNetworkOperatorKnown| and
// |IsMobileVirtualNetworkOperatorKnown| to determine if a fix on the operator
// has been made. Note that the information returned by the other accessors is
// only valid when at least |IsMobileNetworkOperatorKnown| returns true. Their
// values are undefined otherwise.
// Query whether a mobile network operator has been successfully determined.
virtual bool IsMobileNetworkOperatorKnown() const;
// Query whether a mobile network operator has been successfully
// determined.
bool IsMobileVirtualNetworkOperatorKnown() const;
// The unique identifier of this carrier. This is primarily used to
// identify the user profile in store for each carrier. This identifier is
// access technology agnostic and should be the same across 3GPP and CDMA.
virtual const std::string& uuid() const;
virtual const std::string& operator_name() const;
virtual const std::string& country() const;
virtual const std::string& mccmnc() const;
const std::string& sid() const;
const std::string& nid() const;
// A given MVNO can be associated with multiple mcc/mnc pairs. A list of all
// associated mcc/mnc pairs concatenated together.
const std::vector<std::string>& mccmnc_list() const;
// A given MVNO can be associated with multiple sid(s). A list of all
// associated sid(s).
// There are likely many SID values associated with a CDMA carrier as they
// vary across regions and are more fine grained than countries. An important
// thing to keep in mind is that, since an SID contains fine grained
// information on where a modem is physically located, it should be regarded
// as user-sensitive information.
const std::vector<std::string>& sid_list() const;
// All localized names associated with this carrier entry.
const std::vector<LocalizedName>& operator_name_list() const;
// All access point names associated with this carrier entry.
const std::vector<std::unique_ptr<MobileAPN>>& apn_list() const;
// All Online Payment Portal URLs associated with this carrier entry. There
// are usually multiple OLPs based on access technology and it is up to the
// application to use the appropriate one.
virtual const std::vector<OnlinePortal>& olp_list() const;
// The number to dial for automatic activation.
virtual const std::string& activation_code() const;
// Some carriers are only available while roaming. This is mainly used by
// Chrome.
bool requires_roaming() const;
// ///////////////////////////////////////////////////////////////////////////
// Functions used to notify this object of operator data changes.
// The Update* methods update the corresponding property of the network
// operator, and this value may be used to determine the M[V]NO.
// These values are also the values reported through accessors, overriding any
// information from the database.
// Throw away all information provided to the object, and start from top.
void Reset();
// Both MCCMNC and SID correspond to operator code in the different
// technologies. They are never to be used together. If you want to use SID
// after MCCMNC (or vice-versa), ensure a call to |Reset| to clear state.
virtual void UpdateMCCMNC(const std::string& mccmnc);
virtual void UpdateSID(const std::string& sid);
virtual void UpdateIMSI(const std::string& imsi);
void UpdateICCID(const std::string& iccid);
virtual void UpdateNID(const std::string& nid);
virtual void UpdateOperatorName(const std::string& operator_name);
void UpdateOnlinePortal(const std::string& url,
const std::string& method,
const std::string& post_data);
// ///////////////////////////////////////////////////////////////////////////
// Expose implementation for test purposes only.
MobileOperatorInfoImpl* impl() { return impl_.get(); }
std::unique_ptr<MobileOperatorInfoImpl> impl_;
} // namespace shill