components/gcm_driver/gcm_client.h

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

#ifndef COMPONENTS_GCM_DRIVER_GCM_CLIENT_H_
#define COMPONENTS_GCM_DRIVER_GCM_CLIENT_H_

#include <stdint.h>

#include <map>
#include <memory>
#include <string>
#include <vector>

#include "base/memory/linked_ptr.h"
#include "components/gcm_driver/common/gcm_messages.h"
#include "components/gcm_driver/gcm_activity.h"
#include "components/gcm_driver/registration_info.h"

template <class T> class scoped_refptr;

namespace base {
class FilePath;
class SequencedTaskRunner;
class Timer;
}

namespace net {
class IPEndPoint;
class URLRequestContextGetter;
}

namespace gcm {

struct AccountMapping;
class Encryptor;
enum class GCMDecryptionResult;

// Interface that encapsulates the network communications with the Google Cloud
// Messaging server. This interface is not supposed to be thread-safe.
class GCMClient {
 public:
  // Controls how GCM is being started. At first, GCMClient will be initialized
  // and GCM store will be loaded. Then GCM connection may or may not be
  // initiated depending on this enum value.
  enum StartMode {
    // GCM should be started only when it is being actually used. If no
    // registration record is found, GCM will not kick off.
    DELAYED_START,
    // GCM should be started immediately.
    IMMEDIATE_START
  };

  // Used for UMA. Can add enum values, but never renumber or delete and reuse.
  enum Result {
    // Successful operation.
    SUCCESS,
    // Invalid parameter.
    INVALID_PARAMETER,
    // GCM is disabled.
    GCM_DISABLED,
    // 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,

    // Used for UMA. Keep LAST_RESULT up to date and sync with histograms.xml.
    LAST_RESULT = UNKNOWN_ERROR
  };

  enum ChromePlatform {
    PLATFORM_WIN,
    PLATFORM_MAC,
    PLATFORM_LINUX,
    PLATFORM_CROS,
    PLATFORM_IOS,
    PLATFORM_ANDROID,
    PLATFORM_UNSPECIFIED
  };

  enum ChromeChannel {
    CHANNEL_STABLE,
    CHANNEL_BETA,
    CHANNEL_DEV,
    CHANNEL_CANARY,
    CHANNEL_UNKNOWN
  };

  struct ChromeBuildInfo {
    ChromeBuildInfo();
    ~ChromeBuildInfo();

    ChromePlatform platform;
    ChromeChannel channel;
    std::string version;
    std::string product_category_for_subtypes;
  };

  // Detailed information of the Send Error event.
  struct SendErrorDetails {
    SendErrorDetails();
    SendErrorDetails(const SendErrorDetails& other);
    ~SendErrorDetails();

    std::string message_id;
    MessageData additional_data;
    Result result;
  };

  // Internal states and activity statistics of a GCM client.
  struct GCMStatistics {
   public:
    GCMStatistics();
    GCMStatistics(const GCMStatistics& other);
    ~GCMStatistics();

    bool is_recording;
    bool gcm_client_created;
    std::string gcm_client_state;
    bool connection_client_created;
    std::string connection_state;
    base::Time last_checkin;
    base::Time next_checkin;
    uint64_t android_id;
    uint64_t android_secret;
    std::vector<std::string> registered_app_ids;
    int send_queue_size;
    int resend_queue_size;

    RecordedActivities recorded_activities;
  };

  // Information about account.
  struct AccountTokenInfo {
    std::string account_id;
    std::string email;
    std::string access_token;
  };

  // A delegate interface that allows the GCMClient instance to interact with
  // its caller, i.e. notifying asynchronous event.
  class Delegate {
   public:
    // Called when the registration completed successfully or an error occurs.
    // |registration_info|: the specific information required for the
    //                      registration.
    // |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 linked_ptr<RegistrationInfo>& registration_info,
        const std::string& registration_id,
        Result result) = 0;

    // Called when the unregistration completed.
    // |registration_info|: the specific information required for the
    //                      registration.
    // |result|: result of the unregistration.
    virtual void OnUnregisterFinished(
        const linked_ptr<RegistrationInfo>& registration_info,
        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 a message was acknowledged by the GCM server.
    // |app_id|: application ID.
    // |message_id|: ID of the acknowledged message.
    virtual void OnSendAcknowledged(const std::string& app_id,
                                    const std::string& message_id) = 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.
    // |account_mappings|: a persisted list of accounts mapped to this GCM
    //                     client.
    // |last_token_fetch_time|: time of a last successful token fetch.
    virtual void OnGCMReady(const std::vector<AccountMapping>& account_mappings,
                            const base::Time& last_token_fetch_time) = 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;

    // Called when the GCM store is reset (e.g. due to corruption), which
    // changes the device ID, invalidating all prior registrations.
    virtual void OnStoreReset() = 0;
  };

  GCMClient();
  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. The GCMClient must be
  //     deleted before the Getter's underlying URLRequestContext.
  // |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>&
          url_request_context_getter,
      std::unique_ptr<Encryptor> encryptor,
      Delegate* delegate) = 0;

  // This will initiate the GCM connection only if |start_mode| means to start
  // the GCM immediately or the GCM registration records are found in the store.
  // Note that it is OK to call Start multiple times and the implementation
  // should handle it gracefully.
  virtual void Start(StartMode start_mode) = 0;

  // Stops using the GCM service. This will not erase the persisted data.
  virtual void Stop() = 0;

  // Registers with the server to access the provided service.
  // Delegate::OnRegisterFinished will be called asynchronously upon completion.
  // |registration_info|: the specific information required for the
  //                      registration. For GCM, it will contain app id and
  //                      sender IDs. For InstanceID, it will contain app_id,
  //                      authorized entity and scope.
  virtual void Register(
      const linked_ptr<RegistrationInfo>& registration_info) = 0;

  // Checks that the provided |registration_id| (aka token for Instance ID
  // registrations) matches the stored registration info. Also checks sender IDs
  // match for GCM registrations.
  virtual bool ValidateRegistration(
      const linked_ptr<RegistrationInfo>& registration_info,
      const std::string& registration_id) = 0;

  // Unregisters from the server to stop accessing the provided service.
  // Delegate::OnUnregisterFinished will be called asynchronously upon
  // completion.
  // |registration_info|: the specific information required for the
  //                      registration. For GCM, it will contain app id (sender
  //                      IDs can be ingored). For InstanceID, it will contain
  //                      app id, authorized entity and scope.
  virtual void Unregister(
      const linked_ptr<RegistrationInfo>& registration_info) = 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;

  // Records a decryption failure due to |result| for the |app_id|.
  virtual void RecordDecryptionFailure(const std::string& app_id,
                                       GCMDecryptionResult result) = 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;

  // Sets a list of accounts with OAuth2 tokens for the next checkin.
  // |account_tokens|: list of email addresses, account IDs and OAuth2 access
  //                   tokens.
  virtual void SetAccountTokens(
      const std::vector<AccountTokenInfo>& account_tokens) = 0;

  // Persists the |account_mapping| in the store.
  virtual void UpdateAccountMapping(const AccountMapping& account_mapping) = 0;

  // Removes the account mapping related to |account_id| from the persistent
  // store.
  virtual void RemoveAccountMapping(const std::string& account_id) = 0;

  // Sets last token fetch time in persistent store.
  virtual void SetLastTokenFetchTime(const base::Time& time) = 0;

  // Updates the timer used by the HeartbeatManager for sending heartbeats.
  virtual void UpdateHeartbeatTimer(std::unique_ptr<base::Timer> timer) = 0;

  // Adds the Instance ID data for a specific app to the persistent store.
  virtual void AddInstanceIDData(const std::string& app_id,
                                 const std::string& instance_id,
                                 const std::string& extra_data) = 0;

  // Removes the Instance ID data for a specific app from the persistent store.
  virtual void RemoveInstanceIDData(const std::string& app_id) = 0;

  // Retrieves the Instance ID data for a specific app from the persistent
  // store.
  virtual void GetInstanceIDData(const std::string& app_id,
                                 std::string* instance_id,
                                 std::string* extra_data) = 0;

  // Gets and sets custom heartbeat interval for the MCS connection.
  // |scope| is used to identify the component that requests a custom interval
  // to be set, and allows that component to later revoke the setting. It should
  // be unique.
  virtual void AddHeartbeatInterval(const std::string& scope,
                                    int interval_ms) = 0;
  virtual void RemoveHeartbeatInterval(const std::string& scope) = 0;
};

}  // namespace gcm

#endif  // COMPONENTS_GCM_DRIVER_GCM_CLIENT_H_