content_suggestions_provider.h 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175
  1. // Copyright 2016 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_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_
  5. #define COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_
  6. #include <set>
  7. #include <string>
  8. #include <vector>
  9. #include "base/callback_forward.h"
  10. #include "base/memory/raw_ptr.h"
  11. #include "components/ntp_snippets/callbacks.h"
  12. #include "components/ntp_snippets/category.h"
  13. #include "components/ntp_snippets/category_info.h"
  14. #include "components/ntp_snippets/category_status.h"
  15. #include "components/ntp_snippets/content_suggestion.h"
  16. #include "components/ntp_snippets/status.h"
  17. namespace ntp_snippets {
  18. // Provides content suggestions from one particular source.
  19. // A provider can provide suggestions for multiple ContentSuggestionCategories,
  20. // but for every category that it provides, it will be the only provider in the
  21. // system which provides suggestions for that category.
  22. // Providers are created by the ContentSuggestionsServiceFactory and owned and
  23. // shut down by the ContentSuggestionsService.
  24. class ContentSuggestionsProvider {
  25. public:
  26. // The observer of a provider is notified when new data is available.
  27. class Observer {
  28. public:
  29. // Called when the available content changed.
  30. // If a provider provides suggestions for multiple categories, this callback
  31. // is called once per category. The |suggestions| parameter always contains
  32. // the full list of currently available suggestions for that category, i.e.,
  33. // an empty list will remove all suggestions from the given category. Note
  34. // that to clear them from the UI immediately, the provider needs to change
  35. // the status of the respective category. If the given |category| is not
  36. // known yet, the calling |provider| will be registered as its provider.
  37. virtual void OnNewSuggestions(
  38. ContentSuggestionsProvider* provider,
  39. Category category,
  40. std::vector<ContentSuggestion> suggestions) = 0;
  41. // Called when the status of a category changed, including when it is added.
  42. // If |new_status| is NOT_PROVIDED, the calling provider must be the one
  43. // that currently provides the |category|, and the category is unregistered
  44. // without clearing the UI.
  45. // If |new_status| is any other value, it must match the value that is
  46. // currently returned from the provider's |GetCategoryStatus(category)|. In
  47. // case the given |category| is not known yet, the calling |provider| will
  48. // be registered as its provider. Whenever the status changes to an
  49. // unavailable status, all suggestions in that category must immediately be
  50. // removed from all caches and from the UI, but the provider remains
  51. // registered.
  52. virtual void OnCategoryStatusChanged(ContentSuggestionsProvider* provider,
  53. Category category,
  54. CategoryStatus new_status) = 0;
  55. // Called when a suggestion has been invalidated. It will not be provided
  56. // through |OnNewSuggestions| anymore, is not supported by
  57. // |FetchSuggestionImage| or |DismissSuggestion| anymore, and should
  58. // immediately be cleared from the UI and caches. This happens, for example,
  59. // when the content that the suggestion refers to is gone.
  60. // Note that this event may be fired even if the corresponding category is
  61. // not currently AVAILABLE, because open UIs may still be showing the
  62. // suggestion that is to be removed. This event may also be fired for
  63. // |suggestion_id|s that never existed and should be ignored in that case.
  64. virtual void OnSuggestionInvalidated(
  65. ContentSuggestionsProvider* provider,
  66. const ContentSuggestion::ID& suggestion_id) = 0;
  67. };
  68. virtual ~ContentSuggestionsProvider();
  69. // Determines the status of the given |category|, see CategoryStatus.
  70. virtual CategoryStatus GetCategoryStatus(Category category) = 0;
  71. // Returns the meta information for the given |category|.
  72. virtual CategoryInfo GetCategoryInfo(Category category) = 0;
  73. // Dismisses the suggestion with the given ID. A provider needs to ensure that
  74. // a once-dismissed suggestion is never delivered again (through the
  75. // Observer). The provider must not call Observer::OnNewSuggestions if the
  76. // removal of the dismissed suggestion is the only change.
  77. virtual void DismissSuggestion(
  78. const ContentSuggestion::ID& suggestion_id) = 0;
  79. // Fetches the image for the suggestion with the given ID and returns it
  80. // through the callback. This fetch may occur locally or from the internet.
  81. // If that suggestion doesn't exist, doesn't have an image or if the fetch
  82. // fails, the callback gets a null image. The callback will not be called
  83. // synchronously.
  84. virtual void FetchSuggestionImage(const ContentSuggestion::ID& suggestion_id,
  85. ImageFetchedCallback callback) = 0;
  86. // Fetches the image data for the suggestion with the given ID and returns it
  87. // through the callback. This fetch may occur locally or from the internet.
  88. // If that suggestion doesn't exist, doesn't have an image or if the fetch
  89. // fails, the callback gets empty data. The callback will not be called
  90. // synchronously.
  91. virtual void FetchSuggestionImageData(
  92. const ContentSuggestion::ID& suggestion_id,
  93. ImageDataFetchedCallback callback) = 0;
  94. // Fetches more suggestions for the given category. The new suggestions
  95. // will not include any suggestion of the |known_suggestion_ids| sets.
  96. // As a result of this call, the provider:
  97. // - should call the |callback| with these additional suggestions (exactly
  98. // once as the front-end might wait for its completion);
  99. // - should *not* notify its Observer by OnNewSuggestions() with these
  100. // additional suggestions.
  101. virtual void Fetch(const Category& category,
  102. const std::set<std::string>& known_suggestion_ids,
  103. FetchDoneCallback callback) = 0;
  104. // Reloads suggestions from all categories. If the suggestions change, the
  105. // observer must be notified via OnNewSuggestions();
  106. // TODO(jkcal): make pure virtual (involves touching all providers) or remove
  107. // by resolving the pull/push dichotomy.
  108. virtual void ReloadSuggestions() {}
  109. // Removes history from the specified time range where the URL matches the
  110. // |filter|. The data removed depends on the provider. Note that the
  111. // data outside the time range may be deleted, for example suggestions, which
  112. // are based on history from that time range. Providers should immediately
  113. // clear any data related to history from the specified time range where the
  114. // URL matches the |filter|.
  115. virtual void ClearHistory(
  116. base::Time begin,
  117. base::Time end,
  118. const base::RepeatingCallback<bool(const GURL& url)>& filter) = 0;
  119. // Clears suggestions for any non-history related reason (e.g., sign-in status
  120. // change, etc.) so that the next fetch starts from scratch.
  121. virtual void ClearCachedSuggestions() = 0;
  122. // Called when the sign in state has changed. Should be used instead of
  123. // directly registering with the SignInManager so that the
  124. // ContentSuggestionService can control the order of the updates between
  125. // the providers and the observers. |has_signed_in| is true if the state
  126. // change was due to the user signin in and false if the state change was due
  127. // to the user signing out.
  128. virtual void OnSignInStateChanged(bool has_signed_in) {}
  129. // Used only for debugging purposes. Retrieves suggestions for the given
  130. // |category| that have previously been dismissed and are still stored in the
  131. // provider. If the provider doesn't store dismissed suggestions for the given
  132. // |category|, it always calls the callback with an empty vector. The callback
  133. // may be called synchronously.
  134. virtual void GetDismissedSuggestionsForDebugging(
  135. Category category,
  136. DismissedSuggestionsCallback callback) = 0;
  137. // Used only for debugging purposes. Clears the cache of dismissed
  138. // suggestions for the given |category|, if present, so that no suggestions
  139. // are suppressed. This does not necessarily make previously dismissed
  140. // suggestions reappear, as they may have been permanently deleted, depending
  141. // on the provider implementation.
  142. virtual void ClearDismissedSuggestionsForDebugging(Category category) = 0;
  143. protected:
  144. ContentSuggestionsProvider(Observer* observer);
  145. Observer* observer() const { return observer_; }
  146. private:
  147. raw_ptr<Observer> observer_;
  148. };
  149. } // namespace ntp_snippets
  150. #endif // COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_