src/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     // Certificate was missing. Certain operation, like register, requires it.
  44     CERTIFICATE_MISSING,
  45     // Previous asynchronous operation is still pending to finish. Certain
  46     // operation, like register, is only allowed one at a time.
  47     ASYNC_OPERATION_PENDING,
  48     // Network socket error.
  49     NETWORK_ERROR,
  50     // Problem at the server.
  51     SERVER_ERROR,
  52     // Exceeded the specified TTL during message sending.
  53     TTL_EXCEEDED,
  54     // Other errors.
  55     UNKNOWN_ERROR
  56   };
  57
  58   // Message data consisting of key-value pairs.
  59   typedef std::map<std::string, std::string> MessageData;
  60
  61   // Message to be delivered to the other party.
  62   struct GCM_EXPORT OutgoingMessage {
  63     OutgoingMessage();
  64     ~OutgoingMessage();
  65
  66     // Message ID.
  67     std::string id;
  68     // In seconds.
  69     int time_to_live;
  70     MessageData data;
  71   };
  72
  73   // Message being received from the other party.
  74   struct GCM_EXPORT IncomingMessage {
  75     IncomingMessage();
  76     ~IncomingMessage();
  77
  78     MessageData data;
  79   };
  80
  81   // A delegate interface that allows the GCMClient instance to interact with
  82   // its caller, i.e. notifying asynchronous event.
  83   class Delegate {
  84    public:
  85     // Called when the registration completed successfully or an error occurs.
  86     // |app_id|: application ID.
  87     // |registration_id|: non-empty if the registration completed successfully.
  88     // |result|: the type of the error if an error occured, success otherwise.
  89     virtual void OnRegisterFinished(const std::string& app_id,
  90                                     const std::string& registration_id,
  91                                     Result result) = 0;
  92
  93     // Called when the unregistration completed.
  94     // |app_id|: application ID.
  95     // |success|: indicates whether unregistration request was successful.
  96     virtual void OnUnregisterFinished(const std::string& app_id,
  97                                       bool success) = 0;
  98
  99     // Called when the message is scheduled to send successfully or an error
 100     // occurs.
 101     // |app_id|: application ID.
 102     // |message_id|: ID of the message being sent.
 103     // |result|: the type of the error if an error occured, success otherwise.
 104     virtual void OnSendFinished(const std::string& app_id,
 105                                 const std::string& message_id,
 106                                 Result result) = 0;
 107
 108     // Called when a message has been received.
 109     // |app_id|: application ID.
 110     // |message|: message received.
 111     virtual void OnMessageReceived(const std::string& app_id,
 112                                    const IncomingMessage& message) = 0;
 113
 114     // Called when some messages have been deleted from the server.
 115     // |app_id|: application ID.
 116     virtual void OnMessagesDeleted(const std::string& app_id) = 0;
 117
 118     // Called when a message failed to send to the server.
 119     // |app_id|: application ID.
 120     // |message_id|: ID of the message being sent.
 121     // |result|: the type of the error if an error occured, success otherwise.
 122     virtual void OnMessageSendError(const std::string& app_id,
 123                                     const std::string& message_id,
 124                                     Result result) = 0;
 125
 126     // Called when the GCM becomes ready. To get to this state, GCMClient
 127     // finished loading from the GCM store and retrieved the device check-in
 128     // from the server if it hadn't yet.
 129     virtual void OnGCMReady() = 0;
 130   };
 131
 132   GCMClient();
 133   virtual ~GCMClient();
 134
 135   // Begins initialization of the GCM Client.
 136   // |chrome_build_proto|: chrome info, i.e., version, channel and etc.
 137   // |store_path|: path to the GCM store.
 138   // |blocking_task_runner|: for running blocking file tasks.
 139   // |url_request_context_getter|: for url requests.
 140   // |delegate|: the delegate whose methods will be called asynchronously in
 141   //             response to events and messages.
 142   virtual void Initialize(
 143       const checkin_proto::ChromeBuildProto& chrome_build_proto,
 144       const base::FilePath& store_path,
 145       const scoped_refptr<base::SequencedTaskRunner>& blocking_task_runner,
 146       const scoped_refptr<net::URLRequestContextGetter>&
 147           url_request_context_getter,
 148       Delegate* delegate) = 0;
 149
 150   // Checks out of the GCM service. This will erase all the cached and persisted
 151   // data.
 152   virtual void CheckOut() = 0;
 153
 154   // Registers the application for GCM. Delegate::OnRegisterFinished will be
 155   // called asynchronously upon completion.
 156   // |app_id|: application ID.
 157   // |cert|: SHA-1 of public key of the application, in base16 format.
 158   // |sender_ids|: list of IDs of the servers that are allowed to send the
 159   //               messages to the application. These IDs are assigned by the
 160   //               Google API Console.
 161   virtual void Register(const std::string& app_id,
 162                         const std::string& cert,
 163                         const std::vector<std::string>& sender_ids) = 0;
 164
 165   // Unregisters the application from GCM when it is uninstalled.
 166   // Delegate::OnUnregisterFinished will be called asynchronously upon
 167   // completion.
 168   // |app_id|: application ID.
 169   virtual void Unregister(const std::string& app_id) = 0;
 170
 171   // Sends a message to a given receiver. Delegate::OnSendFinished will be
 172   // called asynchronously upon completion.
 173   // |app_id|: application ID.
 174   // |receiver_id|: registration ID of the receiver party.
 175   // |message|: message to be sent.
 176   virtual void Send(const std::string& app_id,
 177                     const std::string& receiver_id,
 178                     const OutgoingMessage& message) = 0;
 179
 180   // Returns true if GCM becomes ready.
 181   virtual bool IsReady() const = 0;
 182 };
 183
 184 }  // namespace gcm
 185
 186 #endif  // GOOGLE_APIS_GCM_GCM_CLIENT_H_