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_category.h"
+#include "components/ntp_snippets/content_suggestions_category_status.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|

[Marc Treib, 2016/07/07 09:37:50]

nit: I'd phrase this as describing the interface, i.e. something like "If a
provider ..., this gets called..."

[Philipp Keck, 2016/07/07 12:22:29]

Done.

+    // parameter should always contain the full list of currently available

[Marc Treib, 2016/07/07 09:37:50]

Similar here: s/should always contain/always contains

[Philipp Keck, 2016/07/07 12:22:29]

Done.

+    // 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
+    // status of the respective category.
+    // The list must not contain ContentSuggestions assigned to a category other

[Marc Treib, 2016/07/07 09:37:50]

Since ContentSuggestions don't contain a category anymore, this comment isn't
needed anymore.

[Philipp Keck, 2016/07/07 12:22:29]

Done.

+    // than the passed |changed_category|. IDs for the ContentSuggestions should
+    // be generated with |MakeUniqueID(..)| below.
+    virtual void OnNewSuggestions(
+        ContentSuggestionsCategory changed_category,
+        std::vector<ContentSuggestion> suggestions) = 0;
+
+    // Called when the status of a category changed.
+    // Whenever the status changes to an unavailable status, all suggestions in
+    // that category must immediately be removed from all caches and from the
+    // UI.
+    virtual void OnCategoryStatusChanged(
+        ContentSuggestionsCategory changed_category,
+        ContentSuggestionsCategoryStatus new_status) = 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;
+
+  // Determines the status of the given |category|, see
+  // ContentSuggestionsCategoryStatus.
+  virtual ContentSuggestionsCategoryStatus GetCategoryStatus(
+      ContentSuggestionsCategory 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.

[Marc Treib, 2016/07/07 09:37:50]

I think this comment is outdated?

[Philipp Keck, 2016/07/07 12:22:29]

Done.

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

[Marc Treib, 2016/07/07 09:37:50]

Also here

[Philipp Keck, 2016/07/07 12:22:29]

Done.

+  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;
+
+  const std::vector<ContentSuggestionsCategory> provided_categories() const {

[Marc Treib, 2016/07/07 09:37:50]

ref?

[Philipp Keck, 2016/07/07 12:22:29]

Done.

+    return provided_categories_;
+  }
+
+ protected:
+  ContentSuggestionsProvider(
+      const std::vector<ContentSuggestionsCategory>& provided_categories);
+  virtual ~ContentSuggestionsProvider();
+
+  // 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(ContentSuggestionsCategory category,
+                                  const std::string& within_category_id);
+
+ private:
+  const std::vector<ContentSuggestionsCategory> provided_categories_;
+};
+
+}  // namespace ntp_snippets
+
+#endif  // COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_