Add ContentSuggestionsService

components/ntp_snippets/content_suggestions_provider.h

+// Copyright 2016 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_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_
+#define COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_
+
+#include <string>
+#include <vector>
+
+#include "base/callback_forward.h"
+#include "components/ntp_snippets/content_suggestion.h"
+#include "components/ntp_snippets/content_suggestions_state.h"
+
+namespace gfx {
+class Image;
+}
+
+namespace ntp_snippets {
+
+// Provides content suggestions from one particular source.
+// A provider can provide suggestions for multiple ContentSuggestionCategories,
+// but for every category that it provides, it will be the only provider in the
+// system which provides suggestions for that category.
+// A provider can be a keyed service, in which case it should notify the
+// ContentSuggestionsService through the observer before it shuts down.
+class ContentSuggestionsProvider {
+ public:
+  using ImageFetchedCallback =
+      base::Callback<void(const std::string& suggestion_id, const gfx::Image&)>;
+
+  // The observer of a provider is notified when new data is available.
+  class Observer {
+   public:
+    // Called when the available content changed.
+    // If a provider provides suggestions of multiple categories, it must call
+    // this callback for every category individually. The |suggestions|
+    // parameter should always contain the full list of currently available
+    // suggestions of that category, i.e., passing an empty list will remove
+    // all suggestions of the given category for the provider. Note that to
+    // clear them from the UI immediately, the provider needs to change the
+    // state of the respective category.
+    // The list must not contain ContentSuggestions assigned to a category other
+    // than the passed |changed_category|.
+    virtual void OnNewSuggestions(
+        ContentSuggestionCategory changed_category,
+        std::vector<ContentSuggestion> suggestions) = 0;
+
+    // Called when the state of a category changed.
+    // Whenever the state changes to an unavailable state, all suggestions in
+    // that category must immediately be removed from all caches and from the
+    // UI.
+    virtual void OnCategoryStateChanged(
+        ContentSuggestionCategory changed_category,
+        ContentSuggestionsState new_state) = 0;
+
+    // Called when the provider needs to shut down and will not deliver any
+    // suggestions anymore. This unregisters the provider, removes the observer
+    // and deactivates all provided categories.
+    virtual void OnProviderShutdown(ContentSuggestionsProvider* provider) = 0;
+  };
+
+  // Sets an observer which is notified about changes to the available
+  // suggestions, or removes it by passing a nullptr.
+  virtual void SetObserver(Observer* observer) = 0;

[Philipp Keck, 2016/07/05 16:53:34]

Couldn't this be implemented here in this class, along with an "Observer*" field
that every implementation needs anyway?

+
+  // Determines the state of the given |category|, see
+  // ContentSuggestionState.
+  virtual ContentSuggestionsState GetCategoryState(
+      ContentSuggestionCategory category) = 0;
+
+  // Discards the suggestion with the given ID. A provider needs to ensure that
+  // a once-discarded suggestion is never delivered again (through the
+  // Observer). The provider must not call Observer::OnSuggestionsChanged if the
+  // removal of the discarded suggestion is the only change.
+  // Note that the |suggestion_id| to the provider here is the same as the
+  // |original_id| that was passed to the |ContentSuggestion| constructor.
+  virtual void DiscardSuggestion(const std::string& suggestion_id) = 0;
+
+  // Fetches the image for the suggestion with the given ID and returns it
+  // through the callback. This fetch may occur locally or from the internet.
+  // Note that the |suggestion_id| to the provider here is the same as the
+  // |original_id| that was passed to the |ContentSuggestion| constructor.
+  virtual void FetchSuggestionImage(const std::string& suggestion_id,
+                                    const ImageFetchedCallback& callback) = 0;
+
+  // Used only for debugging purposes. Clears all caches so that the next
+  // fetch starts from scratch.
+  virtual void ClearCachedSuggestionsForDebugging() = 0;
+
+  // Used only for debugging purposes. Clears the cache of discarded
+  // suggestions, if present, so that no suggestions are suppressed. This does
+  // not necessarily make previously discarded suggestions reappear, as they may
+  // have been permanently deleted, depending on the provider implementation.
+  virtual void ClearDiscardedSuggestionsForDebugging() = 0;
+
+  // Creates a unique ID. The given |within_category_id| must be unique among
+  // all suggestion IDs from this provider for the given |category|. This method
+  // combines it with the |category| to form an ID that is unique
+  // application-wide, because this provider is the only one that provides
+  // suggestions for that category.
+  static std::string MakeUniqueID(ContentSuggestionCategory category,
+                                  const std::string& within_category_id);
+
+  const std::vector<ContentSuggestionCategory> provided_categories() const {
+    return provided_categories_;
+  }
+
+ protected:
+  ContentSuggestionsProvider(
+      const std::vector<ContentSuggestionCategory>& provided_categories);
+  virtual ~ContentSuggestionsProvider();
+
+ private:
+  const std::vector<ContentSuggestionCategory> provided_categories_;
+};
+
+}  // namespace ntp_snippets
+
+#endif  // COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_