components/gcm_driver/gcm_driver.h

   1 // Copyright 2014 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 COMPONENTS_GCM_DRIVER_GCM_DRIVER_H_
   6 #define COMPONENTS_GCM_DRIVER_GCM_DRIVER_H_
   7
   8 #include <map>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/callback.h"
  13 #include "base/macros.h"
  14 #include "base/memory/weak_ptr.h"
  15 #include "base/threading/thread_checker.h"
  16 #include "components/gcm_driver/default_gcm_app_handler.h"
  17 #include "components/gcm_driver/gcm_client.h"
  18
  19 namespace gcm {
  20
  21 class GCMAppHandler;
  22 class GCMConnectionObserver;
  23 struct AccountMapping;
  24
  25 // Provides the InstanceID support via GCMDriver.
  26 class InstanceIDHandler {
  27  public:
  28   typedef base::Callback<void(const std::string& token,
  29                               GCMClient::Result result)> GetTokenCallback;
  30   typedef base::Callback<void(GCMClient::Result result)> DeleteTokenCallback;
  31   typedef base::Callback<void(const std::string& instance_id,
  32                               const std::string& extra_data)>
  33       GetInstanceIDDataCallback;
  34
  35   InstanceIDHandler();
  36   virtual ~InstanceIDHandler();
  37
  38   // Delete all tokens assoicated with |app_id|.
  39   void DeleteAllTokensForApp(const std::string& app_id,
  40                              const DeleteTokenCallback& callback);
  41
  42   // Token service.
  43   virtual void GetToken(const std::string& app_id,
  44                         const std::string& authorized_entity,
  45                         const std::string& scope,
  46                         const std::map<std::string, std::string>& options,
  47                         const GetTokenCallback& callback) = 0;
  48   virtual void DeleteToken(const std::string& app_id,
  49                            const std::string& authorized_entity,
  50                            const std::string& scope,
  51                            const DeleteTokenCallback& callback) = 0;
  52
  53   // Persistence support.
  54   virtual void AddInstanceIDData(const std::string& app_id,
  55                                  const std::string& instance_id,
  56                                  const std::string& extra_data) = 0;
  57   virtual void RemoveInstanceIDData(const std::string& app_id) = 0;
  58   virtual void GetInstanceIDData(
  59       const std::string& app_id,
  60       const GetInstanceIDDataCallback& callback) = 0;
  61
  62  private:
  63   DISALLOW_COPY_AND_ASSIGN(InstanceIDHandler);
  64 };
  65
  66 // Bridge between GCM users in Chrome and the platform-specific implementation.
  67 class GCMDriver {
  68  public:
  69   typedef std::map<std::string, GCMAppHandler*> GCMAppHandlerMap;
  70   typedef base::Callback<void(const std::string& registration_id,
  71                               GCMClient::Result result)> RegisterCallback;
  72   typedef base::Callback<void(const std::string& message_id,
  73                               GCMClient::Result result)> SendCallback;
  74   typedef base::Callback<void(GCMClient::Result result)> UnregisterCallback;
  75   typedef base::Callback<void(const GCMClient::GCMStatistics& stats)>
  76       GetGCMStatisticsCallback;
  77
  78   GCMDriver();
  79   virtual ~GCMDriver();
  80
  81   // Registers |sender_ids| for an app. A registration ID will be returned by
  82   // the GCM server. On Android, only a single sender ID is supported, but
  83   // instead multiple simultaneous registrations are allowed.
  84   // |app_id|: application ID.
  85   // |sender_ids|: list of IDs of the servers that are allowed to send the
  86   //               messages to the application. These IDs are assigned by the
  87   //               Google API Console.
  88   // |callback|: to be called once the asynchronous operation is done.
  89   void Register(const std::string& app_id,
  90                 const std::vector<std::string>& sender_ids,
  91                 const RegisterCallback& callback);
  92
  93   // Unregisters all sender_ids for an app. Only works on non-Android.
  94   // |app_id|: application ID.
  95   // |callback|: to be called once the asynchronous operation is done.
  96   void Unregister(const std::string& app_id,
  97                   const UnregisterCallback& callback);
  98
  99   // Unregisters an (app_id, sender_id) pair from using GCM. Only works on
 100   // Android.
 101   // TODO(jianli): Switch to using GCM's unsubscribe API.
 102   // |app_id|: application ID.
 103   // |sender_id|: the sender ID that was passed when registering.
 104   // |callback|: to be called once the asynchronous operation is done.
 105   void UnregisterWithSenderId(const std::string& app_id,
 106                               const std::string& sender_id,
 107                               const UnregisterCallback& callback);
 108
 109   // Sends a message to a given receiver.
 110   // |app_id|: application ID.
 111   // |receiver_id|: registration ID of the receiver party.
 112   // |message|: message to be sent.
 113   // |callback|: to be called once the asynchronous operation is done.
 114   void Send(const std::string& app_id,
 115             const std::string& receiver_id,
 116             const GCMClient::OutgoingMessage& message,
 117             const SendCallback& callback);
 118
 119   const GCMAppHandlerMap& app_handlers() const { return app_handlers_; }
 120
 121   // This method must be called before destroying the GCMDriver. Once it has
 122   // been called, no other GCMDriver methods may be used.
 123   virtual void Shutdown();
 124
 125   // Called when the user signs in to or out of a GAIA account.
 126   virtual void OnSignedIn() = 0;
 127   virtual void OnSignedOut() = 0;
 128
 129   // Adds a handler for a given app.
 130   virtual void AddAppHandler(const std::string& app_id, GCMAppHandler* handler);
 131
 132   // Remove the handler for a given app.
 133   virtual void RemoveAppHandler(const std::string& app_id);
 134
 135   // Returns the handler for the given app.
 136   GCMAppHandler* GetAppHandler(const std::string& app_id);
 137
 138   // Adds a connection state observer.
 139   virtual void AddConnectionObserver(GCMConnectionObserver* observer) = 0;
 140
 141   // Removes a connection state observer.
 142   virtual void RemoveConnectionObserver(GCMConnectionObserver* observer) = 0;
 143
 144   // Enables/disables GCM service.
 145   virtual void Enable() = 0;
 146   virtual void Disable() = 0;
 147
 148   // For testing purpose. Always NULL on Android.
 149   virtual GCMClient* GetGCMClientForTesting() const = 0;
 150
 151   // Returns true if the service was started.
 152   virtual bool IsStarted() const = 0;
 153
 154   // Returns true if the gcm client has an open and active connection.
 155   virtual bool IsConnected() const = 0;
 156
 157   // Get GCM client internal states and statistics.
 158   // If clear_logs is true then activity logs will be cleared before the stats
 159   // are returned.
 160   virtual void GetGCMStatistics(const GetGCMStatisticsCallback& callback,
 161                                 bool clear_logs) = 0;
 162
 163   // Enables/disables GCM activity recording, and then returns the stats.
 164   virtual void SetGCMRecording(const GetGCMStatisticsCallback& callback,
 165                                bool recording) = 0;
 166
 167   // sets a list of signed in accounts with OAuth2 access tokens, when GCMDriver
 168   // works in context of a signed in entity (e.g. browser profile where user is
 169   // signed into sync).
 170   // |account_tokens|: list of email addresses, account IDs and OAuth2 access
 171   //                   tokens.
 172   virtual void SetAccountTokens(
 173       const std::vector<GCMClient::AccountTokenInfo>& account_tokens) = 0;
 174
 175   // Updates the |account_mapping| information in persistent store.
 176   virtual void UpdateAccountMapping(const AccountMapping& account_mapping) = 0;
 177
 178   // Removes the account mapping information reated to |account_id| from
 179   // persistent store.
 180   virtual void RemoveAccountMapping(const std::string& account_id) = 0;
 181
 182   // Getter and setter of last token fetch time.
 183   virtual base::Time GetLastTokenFetchTime() = 0;
 184   virtual void SetLastTokenFetchTime(const base::Time& time) = 0;
 185
 186   // Sets whether or not GCM should try to wake the system from suspend in order
 187   // to send a heartbeat message.
 188   virtual void WakeFromSuspendForHeartbeat(bool wake) = 0;
 189
 190   // Supports InstanceID handling.
 191   virtual InstanceIDHandler* GetInstanceIDHandler() = 0;
 192
 193   // Adds or removes a custom client requested heartbeat interval. If multiple
 194   // components set that setting, the lowest setting will be used. If the
 195   // setting is outside of GetMax/MinClientHeartbeatIntervalMs() it will be
 196   // ignored. If a new setting is less than the currently used, the connection
 197   // will be reset with the new heartbeat. Client that no longer require
 198   // aggressive heartbeats, should remove their requested interval. Heartbeats
 199   // set this way survive connection/Chrome restart.
 200   //
 201   // GCM Driver can decide to postpone the action until Client is properly
 202   // initialized, hence this setting can be called at any time.
 203   //
 204   // Server can overwrite the setting to a different value.
 205   //
 206   // |scope| is used to identify the component that requests a custom interval
 207   // to be set, and allows that component to later revoke the setting.
 208   // |interval_ms| should be between 2 minues and 15 minues (28 minues on
 209   // cellular networks). For details check
 210   // GetMin/MaxClientHeartbeatItnervalMs() in HeartbeatManager.
 211   virtual void AddHeartbeatInterval(const std::string& scope,
 212                                     int interval_ms) = 0;
 213   virtual void RemoveHeartbeatInterval(const std::string& scope) = 0;
 214
 215  protected:
 216   // Ensures that the GCM service starts (if necessary conditions are met).
 217   virtual GCMClient::Result EnsureStarted(GCMClient::StartMode start_mode) = 0;
 218
 219   // Platform-specific implementation of Register.
 220   virtual void RegisterImpl(const std::string& app_id,
 221                             const std::vector<std::string>& sender_ids) = 0;
 222
 223   // Platform-specific implementation of Unregister.
 224   virtual void UnregisterImpl(const std::string& app_id) = 0;
 225
 226   // Platform-specific implementation of UnregisterWithSenderId.
 227   virtual void UnregisterWithSenderIdImpl(const std::string& app_id,
 228                                           const std::string& sender_id);
 229
 230   // Platform-specific implementation of Send.
 231   virtual void SendImpl(const std::string& app_id,
 232                         const std::string& receiver_id,
 233                         const GCMClient::OutgoingMessage& message) = 0;
 234
 235   // Runs the Register callback.
 236   void RegisterFinished(const std::string& app_id,
 237                         const std::string& registration_id,
 238                         GCMClient::Result result);
 239
 240   // Runs the Unregister callback.
 241   void UnregisterFinished(const std::string& app_id,
 242                           GCMClient::Result result);
 243
 244   // Runs the Send callback.
 245   void SendFinished(const std::string& app_id,
 246                     const std::string& message_id,
 247                     GCMClient::Result result);
 248
 249   bool HasRegisterCallback(const std::string& app_id);
 250
 251   void ClearCallbacks();
 252
 253  private:
 254   // Common code shared by Unregister and UnregisterWithSenderId.
 255   void UnregisterInternal(const std::string& app_id,
 256                           const std::string* sender_id,
 257                           const UnregisterCallback& callback);
 258
 259   // Called after unregistration completes in order to trigger the pending
 260   // registration.
 261   void RegisterAfterUnregister(
 262       const std::string& app_id,
 263       const std::vector<std::string>& normalized_sender_ids,
 264       const UnregisterCallback& unregister_callback,
 265       GCMClient::Result result);
 266
 267   // Callback map (from app_id to callback) for Register.
 268   std::map<std::string, RegisterCallback> register_callbacks_;
 269
 270   // Callback map (from app_id to callback) for Unregister.
 271   std::map<std::string, UnregisterCallback> unregister_callbacks_;
 272
 273   // Callback map (from <app_id, message_id> to callback) for Send.
 274   std::map<std::pair<std::string, std::string>, SendCallback> send_callbacks_;
 275
 276   // App handler map (from app_id to handler pointer).
 277   // The handler is not owned.
 278   GCMAppHandlerMap app_handlers_;
 279
 280   // The default handler when no app handler can be found in the map.
 281   DefaultGCMAppHandler default_app_handler_;
 282
 283   base::WeakPtrFactory<GCMDriver> weak_ptr_factory_;
 284
 285   DISALLOW_COPY_AND_ASSIGN(GCMDriver);
 286 };
 287
 288 }  // namespace gcm
 289
 290 #endif  // COMPONENTS_GCM_DRIVER_GCM_DRIVER_H_