blob: 8e0fb2f369d6fca14e13d819d869555fb0acb792 [file] [log] [blame]
// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <map>
#include <string>
#include <vector>
#include "base/basictypes.h"
#include "base/memory/scoped_ptr.h"
#include "components/gcm_driver/gcm_activity.h"
template <class T> class scoped_refptr;
class GURL;
namespace base {
class FilePath;
class SequencedTaskRunner;
namespace net {
class IPEndPoint;
class URLRequestContextGetter;
namespace gcm {
class Encryptor;
// Interface that encapsulates the network communications with the Google Cloud
// Messaging server. This interface is not supposed to be thread-safe.
class GCMClient {
enum Result {
// Successful operation.
// Invalid parameter.
// GCM is disabled.
// Profile not signed in.
// Previous asynchronous operation is still pending to finish. Certain
// operation, like register, is only allowed one at a time.
// Network socket error.
// Problem at the server.
// Exceeded the specified TTL during message sending.
// Other errors.
enum ChromePlatform {
enum ChromeChannel {
struct ChromeBuildInfo {
ChromePlatform platform;
ChromeChannel channel;
std::string version;
// Message data consisting of key-value pairs.
typedef std::map<std::string, std::string> MessageData;
// Message to be delivered to the other party.
struct OutgoingMessage {
// Message ID.
std::string id;
// In seconds.
int time_to_live;
MessageData data;
static const int kMaximumTTL = 4 * 7 * 24 * 60 * 60; // 4 weeks.
// Message being received from the other party.
struct IncomingMessage {
MessageData data;
std::string collapse_key;
std::string sender_id;
// Detailed information of the Send Error event.
struct SendErrorDetails {
std::string message_id;
MessageData additional_data;
Result result;
// Internal states and activity statistics of a GCM client.
struct GCMStatistics {
bool is_recording;
bool gcm_client_created;
std::string gcm_client_state;
bool connection_client_created;
std::string connection_state;
uint64 android_id;
std::vector<std::string> registered_app_ids;
int send_queue_size;
int resend_queue_size;
RecordedActivities recorded_activities;
// A delegate interface that allows the GCMClient instance to interact with
// its caller, i.e. notifying asynchronous event.
class Delegate {
// Called when the registration completed successfully or an error occurs.
// |app_id|: application ID.
// |registration_id|: non-empty if the registration completed successfully.
// |result|: the type of the error if an error occured, success otherwise.
virtual void OnRegisterFinished(const std::string& app_id,
const std::string& registration_id,
Result result) = 0;
// Called when the unregistration completed.
// |app_id|: application ID.
// |result|: result of the unregistration.
virtual void OnUnregisterFinished(const std::string& app_id,
GCMClient::Result result) = 0;
// Called when the message is scheduled to send successfully or an error
// occurs.
// |app_id|: application ID.
// |message_id|: ID of the message being sent.
// |result|: the type of the error if an error occured, success otherwise.
virtual void OnSendFinished(const std::string& app_id,
const std::string& message_id,
Result result) = 0;
// Called when a message has been received.
// |app_id|: application ID.
// |message|: message received.
virtual void OnMessageReceived(const std::string& app_id,
const IncomingMessage& message) = 0;
// Called when some messages have been deleted from the server.
// |app_id|: application ID.
virtual void OnMessagesDeleted(const std::string& app_id) = 0;
// Called when a message failed to send to the server.
// |app_id|: application ID.
// |send_error_detials|: Details of the send error event, like mesasge ID.
virtual void OnMessageSendError(
const std::string& app_id,
const SendErrorDetails& send_error_details) = 0;
// Called when the GCM becomes ready. To get to this state, GCMClient
// finished loading from the GCM store and retrieved the device check-in
// from the server if it hadn't yet.
virtual void OnGCMReady() = 0;
// Called when activities are being recorded and a new activity has just
// been recorded.
virtual void OnActivityRecorded() = 0;
// Called when a new connection is established and a successful handshake
// has been performed.
virtual void OnConnected(const net::IPEndPoint& ip_endpoint) = 0;
// Called when the connection is interrupted.
virtual void OnDisconnected() = 0;
virtual ~GCMClient();
// Begins initialization of the GCM Client. This will not trigger a
// connection.
// |chrome_build_info|: chrome info, i.e., version, channel and etc.
// |store_path|: path to the GCM store.
// |blocking_task_runner|: for running blocking file tasks.
// |url_request_context_getter|: for url requests.
// |delegate|: the delegate whose methods will be called asynchronously in
// response to events and messages.
virtual void Initialize(
const ChromeBuildInfo& chrome_build_info,
const base::FilePath& store_path,
const scoped_refptr<base::SequencedTaskRunner>& blocking_task_runner,
const scoped_refptr<net::URLRequestContextGetter>&
scoped_ptr<Encryptor> encryptor,
Delegate* delegate) = 0;
// Starts the GCM service by first loading the data from the persistent store.
// This will then kick off the check-in if the check-in info is not found in
// the store.
virtual void Start() = 0;
// Stops using the GCM service. This will not erase the persisted data.
virtual void Stop() = 0;
// Checks out of the GCM service. This will erase all the cached and persisted
// data.
virtual void CheckOut() = 0;
// Registers the application for GCM. Delegate::OnRegisterFinished will be
// called asynchronously upon completion.
// |app_id|: application ID.
// |sender_ids|: list of IDs of the servers that are allowed to send the
// messages to the application. These IDs are assigned by the
// Google API Console.
virtual void Register(const std::string& app_id,
const std::vector<std::string>& sender_ids) = 0;
// Unregisters the application from GCM when it is uninstalled.
// Delegate::OnUnregisterFinished will be called asynchronously upon
// completion.
// |app_id|: application ID.
virtual void Unregister(const std::string& app_id) = 0;
// Sends a message to a given receiver. Delegate::OnSendFinished will be
// called asynchronously upon completion.
// |app_id|: application ID.
// |receiver_id|: registration ID of the receiver party.
// |message|: message to be sent.
virtual void Send(const std::string& app_id,
const std::string& receiver_id,
const OutgoingMessage& message) = 0;
// Enables or disables internal activity recording.
virtual void SetRecording(bool recording) = 0;
// Clear all recorded GCM activity logs.
virtual void ClearActivityLogs() = 0;
// Gets internal states and statistics.
virtual GCMStatistics GetStatistics() const = 0;
} // namespace gcm