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