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