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