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