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