google_apis/gcm/gcm_client.h

// 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_