text: // Copyright 2013 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.
  
  #ifndef GOOGLE_APIS_GCM_GCM_CLIENT_H_
  #define GOOGLE_APIS_GCM_GCM_CLIENT_H_
  
  #include <map>
  #include <string>
  #include <vector>
  
  #include "base/basictypes.h"
  #include "google_apis/gcm/base/gcm_export.h"
  
  namespace base {
  class TaskRunner;
  }
  
  namespace gcm {
  
  // Interface that encapsulates the network communications with the Google Cloud
  // Messaging server. This interface is not supposed to be thread-safe.
  class GCM_EXPORT GCMClient {
   public:
    enum Result {
      // Successful operation.
      SUCCESS,
      // Invalid parameter.
      INVALID_PARAMETER,
      // Previous asynchronous operation is still pending to finish. Certain
      // operation, like register, is only allowed one at a time.
      ASYNC_OPERATION_PENDING,
      // Network socket error.
      NETWORK_ERROR,
      // Problem at the server.
      SERVER_ERROR,
      // Exceeded the specified TTL during message sending.
      TTL_EXCEEDED,
      // Other errors.
      UNKNOWN_ERROR
    };
  
    // Message data consisting of key-value pairs.
    typedef std::map<std::string, std::string> MessageData;
  
    // Message to be delivered to the other party.
    struct GCM_EXPORT OutgoingMessage {
      OutgoingMessage();
      ~OutgoingMessage();
  
      // Message ID.
      std::string id;
      // In seconds.
      int time_to_live;
      MessageData data;
    };
  
    // Message being received from the other party.
    struct GCM_EXPORT IncomingMessage {
      IncomingMessage();
      ~IncomingMessage();
  
      MessageData data;
    };
  
    // The check-in info for the user. Returned by the server.
    struct GCM_EXPORT CheckInInfo {
      CheckInInfo() : android_id(0), secret(0) {}
      bool IsValid() const { return android_id != 0 && secret != 0; }
      void Reset() {
        android_id = 0;
        secret = 0;
      }
  
      uint64 android_id;
      uint64 secret;
    };
  
    // A delegate interface that allows the GCMClient instance to interact with
    // its caller, i.e. notifying asynchronous event.
    class Delegate {
     public:
      // Called when the user has been checked in successfully or an error occurs.
      // |checkin_info|: valid if the checkin completed successfully.
      // |result|: the type of the error if an error occured, success otherwise.
      virtual void OnCheckInFinished(const CheckInInfo& checkin_info,
                                     Result result) = 0;
  
      // 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 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.
      // |message_id|: ID of the message being sent.
      // |result|: the type of the error if an error occured, success otherwise.
      virtual void OnMessageSendError(const std::string& app_id,
                                      const std::string& message_id,
                                      Result result) = 0;
  
      // Returns the checkin info associated with this user. The delegate class
      // is expected to persist the checkin info that is provided by
      // OnCheckInFinished.
      virtual CheckInInfo GetCheckInInfo() const = 0;
  
      // Called when the loading from the persistent store is done. The loading
      // is triggered asynchronously when GCMClient is created.
      virtual void OnLoadingCompleted() = 0;
  
      // Returns a task runner for file operations that may block. This is used
      // in writing to or reading from the persistent store.
      virtual base::TaskRunner* GetFileTaskRunner() = 0;
    };
  
    // Returns the single instance. Multiple profiles share the same client
    // that makes use of the same MCS connection.
    static GCMClient* Get();
  
    // Passes a mocked instance for testing purpose.
    static void SetForTesting(GCMClient* client);
  
    // Checks in the user to use GCM. If the device has not been checked in, it
    // will be done first.
    // |username|: the username (email address) used to check in with the server.
    // |delegate|: the delegate whose methods will be called asynchronously in
    //             response to events and messages.
    virtual void CheckIn(const std::string& username, Delegate* delegate) = 0;
  
    // Registers the application for GCM. Delegate::OnRegisterFinished will be
    // called asynchronously upon completion.
    // |username|: the username (email address) passed in CheckIn.
    // |app_id|: application ID.
    // |cert|: SHA-1 of public key of the application, in base16 format.
    // |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& username,
                          const std::string& app_id,
                          const std::string& cert,
                          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.
    // |username|: the username (email address) passed in CheckIn.
    // |app_id|: application ID.
    virtual void Unregister(const std::string& username,
                            const std::string& app_id) = 0;
  
    // Sends a message to a given receiver. Delegate::OnSendFinished will be
    // called asynchronously upon completion.
    // |username|: the username (email address) passed in CheckIn.
    // |app_id|: application ID.
    // |receiver_id|: registration ID of the receiver party.
    // |message|: message to be sent.
    virtual void Send(const std::string& username,
                      const std::string& app_id,
                      const std::string& receiver_id,
                      const OutgoingMessage& message) = 0;
  
    // Returns true if the loading from the persistent store is still in progress.
    virtual bool IsLoading() const = 0;
  
   protected:
    virtual ~GCMClient() {}
  };
  
  }  // namespace gcm
  
  #endif  // GOOGLE_APIS_GCM_GCM_CLIENT_H_
  