instance_id.h 7.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182
  1. // Copyright 2015 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. #ifndef COMPONENTS_GCM_DRIVER_INSTANCE_ID_INSTANCE_ID_H_
  5. #define COMPONENTS_GCM_DRIVER_INSTANCE_ID_INSTANCE_ID_H_
  6. #include <memory>
  7. #include <set>
  8. #include <string>
  9. #include "base/callback.h"
  10. #include "base/memory/raw_ptr.h"
  11. #include "base/memory/weak_ptr.h"
  12. #include "base/time/time.h"
  13. namespace gcm {
  14. class GCMDriver;
  15. } // namespace gcm
  16. namespace instance_id {
  17. extern const char kGCMScope[];
  18. // Encapsulates Instance ID functionalities that need to be implemented for
  19. // different platforms. One instance is created per application. Life of
  20. // Instance ID is managed by the InstanceIDDriver.
  21. //
  22. // Create instances of this class by calling |InstanceIDDriver::GetInstanceID|.
  23. class InstanceID {
  24. public:
  25. // Used in UMA. Can add enum values, but never renumber or delete and reuse.
  26. enum Result : uint8_t {
  27. // Successful operation.
  28. SUCCESS = 0,
  29. // Invalid parameter.
  30. INVALID_PARAMETER = 1,
  31. // Instance ID is disabled.
  32. DISABLED = 2,
  33. // Previous asynchronous operation is still pending to finish.
  34. ASYNC_OPERATION_PENDING = 3,
  35. // Network socket error.
  36. NETWORK_ERROR = 4,
  37. // Problem at the server.
  38. SERVER_ERROR = 5,
  39. // 6 is omitted, in case we ever merge this enum with GCMClient::Result.
  40. // Other errors.
  41. UNKNOWN_ERROR = 7,
  42. // Used for UMA. Keep kMaxValue up to date and sync with histograms.xml.
  43. kMaxValue = UNKNOWN_ERROR
  44. };
  45. // Flags to be used to create a token. These might be platform specific.
  46. // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.components.gcm_driver
  47. // GENERATED_JAVA_CLASS_NAME_OVERRIDE: InstanceIDFlags
  48. enum class Flags {
  49. // Whether delivery of received messages should be deferred until there is a
  50. // visible activity. Only applicable for Android.
  51. kIsLazy = 1 << 0,
  52. // Whether delivery of received messages should bypass the background task
  53. // scheduler. Only applicable for high priority messages on Android.
  54. kBypassScheduler = 1 << 1,
  55. };
  56. // Asynchronous callbacks. Must not synchronously delete |this| (using
  57. // InstanceIDDriver::RemoveInstanceID).
  58. using GetIDCallback = base::OnceCallback<void(const std::string& id)>;
  59. using GetCreationTimeCallback =
  60. base::OnceCallback<void(const base::Time& creation_time)>;
  61. using GetTokenCallback =
  62. base::OnceCallback<void(const std::string& token, Result result)>;
  63. using ValidateTokenCallback = base::OnceCallback<void(bool is_valid)>;
  64. using GetEncryptionInfoCallback =
  65. base::OnceCallback<void(std::string p256dh, std::string auth_secret)>;
  66. using DeleteTokenCallback = base::OnceCallback<void(Result result)>;
  67. using DeleteIDCallback = base::OnceCallback<void(Result result)>;
  68. static const int kInstanceIDByteLength = 8;
  69. // Creator. Should only be used by InstanceIDDriver::GetInstanceID.
  70. // |app_id|: identifies the application that uses the Instance ID.
  71. // |handler|: provides the GCM functionality needed to support Instance ID.
  72. // Must outlive this class. On Android, this can be null instead.
  73. static std::unique_ptr<InstanceID> CreateInternal(const std::string& app_id,
  74. gcm::GCMDriver* gcm_driver);
  75. InstanceID(const InstanceID&) = delete;
  76. InstanceID& operator=(const InstanceID&) = delete;
  77. virtual ~InstanceID();
  78. // Returns the Instance ID.
  79. virtual void GetID(GetIDCallback callback) = 0;
  80. // Returns the time when the Instance ID has been generated.
  81. virtual void GetCreationTime(GetCreationTimeCallback callback) = 0;
  82. // Retrieves a token that allows the authorized entity to access the service
  83. // defined as "scope". This may cause network requests but the result is
  84. // cached on disk for up to a week. Token validity will be checked
  85. // automatically. Thus you should not store tokens for long periods yourself,
  86. // instead call this function each time it's needed.
  87. //
  88. // To receive messages, register an |AppIdHandler| on |gcm_driver()|.
  89. //
  90. // |authorized_entity|: identifies the entity that is authorized to access
  91. // resources associated with this Instance ID. It can be
  92. // another Instance ID or a numeric project ID.
  93. // |scope|: identifies authorized actions that the authorized entity can take.
  94. // E.g. for sending GCM messages, "GCM" scope should be used.
  95. // |time_to_live|: TTL of retrieved token, unlimited if zero value passed.
  96. // |flags|: Flags used to create this token.
  97. // |callback|: to be called once the asynchronous operation is done.
  98. virtual void GetToken(const std::string& authorized_entity,
  99. const std::string& scope,
  100. base::TimeDelta time_to_live,
  101. std::set<Flags> flags,
  102. GetTokenCallback callback) = 0;
  103. // Checks that the provided |token| matches the stored token for (|app_id()|,
  104. // |authorized_entity|, |scope|). If you follow the guidance for |GetToken|,
  105. // and call that function each time you need the token, then you will not
  106. // need to use this function.
  107. virtual void ValidateToken(const std::string& authorized_entity,
  108. const std::string& scope,
  109. const std::string& token,
  110. ValidateTokenCallback callback) = 0;
  111. // Get the public encryption key and authentication secret associated with a
  112. // GCM-scoped token. If encryption info is not yet associated, it will be
  113. // created.
  114. // |authorized_entity|: the authorized entity passed when obtaining the token.
  115. // |callback|: to be called once the asynchronous operation is done.
  116. virtual void GetEncryptionInfo(const std::string& authorized_entity,
  117. GetEncryptionInfoCallback callback);
  118. // Revokes a granted token.
  119. // |authorized_entity|: the authorized entity passed when obtaining the token.
  120. // |scope|: the scope that was passed when obtaining the token.
  121. // |callback|: to be called once the asynchronous operation is done.
  122. virtual void DeleteToken(const std::string& authorized_entity,
  123. const std::string& scope,
  124. DeleteTokenCallback callback);
  125. // Resets the app instance identifier and revokes all tokens associated with
  126. // it.
  127. // |callback|: to be called once the asynchronous operation is done.
  128. void DeleteID(DeleteIDCallback callback);
  129. std::string app_id() const { return app_id_; }
  130. gcm::GCMDriver* gcm_driver() { return gcm_driver_; }
  131. protected:
  132. InstanceID(const std::string& app_id, gcm::GCMDriver* gcm_driver);
  133. // Platform-specific implementations.
  134. virtual void DeleteTokenImpl(const std::string& authorized_entity,
  135. const std::string& scope,
  136. DeleteTokenCallback callback) = 0;
  137. virtual void DeleteIDImpl(DeleteIDCallback callback) = 0;
  138. void NotifyTokenRefresh(bool update_id);
  139. private:
  140. void DidDelete(const std::string& authorized_entity,
  141. base::OnceCallback<void(Result result)> callback,
  142. Result result);
  143. // Owned by GCMProfileServiceFactory, which is a dependency of
  144. // InstanceIDProfileServiceFactory, which owns this.
  145. raw_ptr<gcm::GCMDriver> gcm_driver_;
  146. std::string app_id_;
  147. base::WeakPtrFactory<InstanceID> weak_ptr_factory_{this};
  148. };
  149. } // namespace instance_id
  150. #endif // COMPONENTS_GCM_DRIVER_INSTANCE_ID_INSTANCE_ID_H_