google_apis/gcm/gcm_client.h

   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 GOOGLE_APIS_GCM_GCM_CLIENT_H_
   6 #define GOOGLE_APIS_GCM_GCM_CLIENT_H_
   7
   8 #include <map>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/basictypes.h"
  13 #include "base/memory/scoped_ptr.h"
  14 #include "google_apis/gcm/base/gcm_export.h"
  15 #include "google_apis/gcm/gcm_activity.h"
  16
  17 template <class T> class scoped_refptr;
  18
  19 namespace base {
  20 class FilePath;
  21 class SequencedTaskRunner;
  22 }
  23
  24 namespace net {
  25 class URLRequestContextGetter;
  26 }
  27
  28 namespace gcm {
  29
  30 class Encryptor;
  31
  32 // Interface that encapsulates the network communications with the Google Cloud
  33 // Messaging server. This interface is not supposed to be thread-safe.
  34 class GCM_EXPORT GCMClient {
  35  public:
  36   enum Result {
  37     // Successful operation.
  38     SUCCESS,
  39     // Invalid parameter.
  40     INVALID_PARAMETER,
  41     // GCM is disabled.
  42     GCM_DISABLED,
  43     // Profile not signed in.
  44     NOT_SIGNED_IN,
  45     // Previous asynchronous operation is still pending to finish. Certain
  46     // operation, like register, is only allowed one at a time.
  47     ASYNC_OPERATION_PENDING,
  48     // Network socket error.
  49     NETWORK_ERROR,
  50     // Problem at the server.
  51     SERVER_ERROR,
  52     // Exceeded the specified TTL during message sending.
  53     TTL_EXCEEDED,
  54     // Other errors.
  55     UNKNOWN_ERROR
  56   };
  57
  58   enum ChromePlatform {
  59     PLATFORM_WIN,
  60     PLATFORM_MAC,
  61     PLATFORM_LINUX,
  62     PLATFORM_CROS,
  63     PLATFORM_IOS,
  64     PLATFORM_ANDROID,
  65     PLATFORM_UNKNOWN
  66   };
  67
  68   enum ChromeChannel {
  69     CHANNEL_STABLE,
  70     CHANNEL_BETA,
  71     CHANNEL_DEV,
  72     CHANNEL_CANARY,
  73     CHANNEL_UNKNOWN
  74   };
  75
  76   struct GCM_EXPORT ChromeBuildInfo {
  77     ChromeBuildInfo();
  78     ~ChromeBuildInfo();
  79
  80     ChromePlatform platform;
  81     ChromeChannel channel;
  82     std::string version;
  83   };
  84
  85   // Message data consisting of key-value pairs.
  86   typedef std::map<std::string, std::string> MessageData;
  87
  88   // Message to be delivered to the other party.
  89   struct GCM_EXPORT OutgoingMessage {
  90     OutgoingMessage();
  91     ~OutgoingMessage();
  92
  93     // Message ID.
  94     std::string id;
  95     // In seconds.
  96     int time_to_live;
  97     MessageData data;
  98
  99     static const int kMaximumTTL = 4 * 7 * 24 * 60 * 60;  // 4 weeks.
 100   };
 101
 102   // Message being received from the other party.
 103   struct GCM_EXPORT IncomingMessage {
 104     IncomingMessage();
 105     ~IncomingMessage();
 106
 107     MessageData data;
 108     std::string collapse_key;
 109     std::string sender_id;
 110   };
 111
 112   // Detailed information of the Send Error event.
 113   struct GCM_EXPORT SendErrorDetails {
 114     SendErrorDetails();
 115     ~SendErrorDetails();
 116
 117     std::string message_id;
 118     MessageData additional_data;
 119     Result result;
 120   };
 121
 122   // Internal states and activity statistics of a GCM client.
 123   struct GCM_EXPORT GCMStatistics {
 124    public:
 125     GCMStatistics();
 126     ~GCMStatistics();
 127
 128     bool is_recording;
 129     bool gcm_client_created;
 130     std::string gcm_client_state;
 131     bool connection_client_created;
 132     std::string connection_state;
 133     uint64 android_id;
 134     std::vector<std::string> registered_app_ids;
 135     int send_queue_size;
 136     int resend_queue_size;
 137
 138     RecordedActivities recorded_activities;
 139   };
 140
 141   // A delegate interface that allows the GCMClient instance to interact with
 142   // its caller, i.e. notifying asynchronous event.
 143   class Delegate {
 144    public:
 145     // Called when the registration completed successfully or an error occurs.
 146     // |app_id|: application ID.
 147     // |registration_id|: non-empty if the registration completed successfully.
 148     // |result|: the type of the error if an error occured, success otherwise.
 149     virtual void OnRegisterFinished(const std::string& app_id,
 150                                     const std::string& registration_id,
 151                                     Result result) = 0;
 152
 153     // Called when the unregistration completed.
 154     // |app_id|: application ID.
 155     // |result|: result of the unregistration.
 156     virtual void OnUnregisterFinished(const std::string& app_id,
 157                                       GCMClient::Result result) = 0;
 158
 159     // Called when the message is scheduled to send successfully or an error
 160     // occurs.
 161     // |app_id|: application ID.
 162     // |message_id|: ID of the message being sent.
 163     // |result|: the type of the error if an error occured, success otherwise.
 164     virtual void OnSendFinished(const std::string& app_id,
 165                                 const std::string& message_id,
 166                                 Result result) = 0;
 167
 168     // Called when a message has been received.
 169     // |app_id|: application ID.
 170     // |message|: message received.
 171     virtual void OnMessageReceived(const std::string& app_id,
 172                                    const IncomingMessage& message) = 0;
 173
 174     // Called when some messages have been deleted from the server.
 175     // |app_id|: application ID.
 176     virtual void OnMessagesDeleted(const std::string& app_id) = 0;
 177
 178     // Called when a message failed to send to the server.
 179     // |app_id|: application ID.
 180     // |send_error_detials|: Details of the send error event, like mesasge ID.
 181     virtual void OnMessageSendError(
 182         const std::string& app_id,
 183         const SendErrorDetails& send_error_details) = 0;
 184
 185     // Called when the GCM becomes ready. To get to this state, GCMClient
 186     // finished loading from the GCM store and retrieved the device check-in
 187     // from the server if it hadn't yet.
 188     virtual void OnGCMReady() = 0;
 189
 190     // Called when activities are being recorded and a new activity has just
 191     // been recorded.
 192     virtual void OnActivityRecorded() = 0;
 193   };
 194
 195   GCMClient();
 196   virtual ~GCMClient();
 197
 198   // Begins initialization of the GCM Client. This will not trigger a
 199   // connection.
 200   // |chrome_build_info|: chrome info, i.e., version, channel and etc.
 201   // |store_path|: path to the GCM store.
 202   // |account_ids|: account IDs to be related to the device when checking in.
 203   // |blocking_task_runner|: for running blocking file tasks.
 204   // |url_request_context_getter|: for url requests.
 205   // |delegate|: the delegate whose methods will be called asynchronously in
 206   //             response to events and messages.
 207   virtual void Initialize(
 208       const ChromeBuildInfo& chrome_build_info,
 209       const base::FilePath& store_path,
 210       const std::vector<std::string>& account_ids,
 211       const scoped_refptr<base::SequencedTaskRunner>& blocking_task_runner,
 212       const scoped_refptr<net::URLRequestContextGetter>&
 213           url_request_context_getter,
 214       scoped_ptr<Encryptor> encryptor,
 215       Delegate* delegate) = 0;
 216
 217   // Starts the GCM service by first loading the data from the persistent store.
 218   // This will then kick off the check-in if the check-in info is not found in
 219   // the store.
 220   virtual void Start() = 0;
 221
 222   // Stops using the GCM service. This will not erase the persisted data.
 223   virtual void Stop() = 0;
 224
 225   // Checks out of the GCM service. This will erase all the cached and persisted
 226   // data.
 227   virtual void CheckOut() = 0;
 228
 229   // Registers the application for GCM. Delegate::OnRegisterFinished will be
 230   // called asynchronously upon completion.
 231   // |app_id|: application ID.
 232   // |sender_ids|: list of IDs of the servers that are allowed to send the
 233   //               messages to the application. These IDs are assigned by the
 234   //               Google API Console.
 235   virtual void Register(const std::string& app_id,
 236                         const std::vector<std::string>& sender_ids) = 0;
 237
 238   // Unregisters the application from GCM when it is uninstalled.
 239   // Delegate::OnUnregisterFinished will be called asynchronously upon
 240   // completion.
 241   // |app_id|: application ID.
 242   virtual void Unregister(const std::string& app_id) = 0;
 243
 244   // Sends a message to a given receiver. Delegate::OnSendFinished will be
 245   // called asynchronously upon completion.
 246   // |app_id|: application ID.
 247   // |receiver_id|: registration ID of the receiver party.
 248   // |message|: message to be sent.
 249   virtual void Send(const std::string& app_id,
 250                     const std::string& receiver_id,
 251                     const OutgoingMessage& message) = 0;
 252
 253   // Enables or disables internal activity recording.
 254   virtual void SetRecording(bool recording) = 0;
 255
 256   // Clear all recorded GCM activity logs.
 257   virtual void ClearActivityLogs() = 0;
 258
 259   // Gets internal states and statistics.
 260   virtual GCMStatistics GetStatistics() const = 0;
 261 };
 262
 263 }  // namespace gcm
 264
 265 #endif  // GOOGLE_APIS_GCM_GCM_CLIENT_H_