Make ContentSuggestionsService recognize new/removed categories

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>
 
@@ skipping 21 matching lines @@
 
   // 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 for multiple categories, this callback
     // is called once per category. The |suggestions| parameter always contains
     // the full list of currently available suggestions for that category, i.e.,
     // an empty list will remove all suggestions from the given category. Note
     // that to clear them from the UI immediately, the provider needs to change
-    // the status of the respective category.
+    // the status of the respective category. If the given |category| is not
+    // known yet, the calling |provider| will be registered as its provider.

[Marc Treib, 2016/08/01 17:30:35]

Wait, can this actually happen? Wouldn't OnCategoryStatusChanged always be
called first?

[Philipp Keck, 2016/08/02 08:15:46]

We currently don't require it. A provider could call OnNewSuggestions for a new
category and the service would ask GetCategoryStatus for the status, so no need
for the changed event.

It works the way it is, but we could also require that OnCategoryStatusChanged
needs to be called first.
That's another issue which disappears once we only have one method for both.

     // IDs for the ContentSuggestions should be generated with
     // |MakeUniqueID(..)| below.
     virtual void OnNewSuggestions(
-        Category changed_category,
+        ContentSuggestionsProvider* provider,
+        Category category,
         std::vector<ContentSuggestion> suggestions) = 0;
 
     // Called when the status of a category changed.
-    // |new_status| must be the value that is currently returned from the
-    // provider's |GetCategoryStatus(category)| below.
-    // 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(Category changed_category,
+    // If |new_status| is NOT_PROVIDED, the calling provider must be the one
+    // that currently provides the |category|, and the category is unregistered
+    // without clearing the UI. The |category| must also be removed from
+    // |GetProvidedCategories()|.
+    // If |new_status| is any other value, it must match the value that is
+    // currently returned from the provider's |GetCategoryStatus(category)|. In
+    // case the given |category| is not known yet, the calling |provider| will
+    // be registered as its provider. Whenever the status changes to an
+    // unavailable status, all suggestions in that category must immediately be
+    // removed from all caches and from the UI, but the provider remains
+    // registered.
+    virtual void OnCategoryStatusChanged(ContentSuggestionsProvider* provider,
+                                         Category category,
                                          CategoryStatus new_status) = 0;
 
     // Called when the provider needs to shut down and will not deliver any
     // suggestions anymore.
     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. The provider does not take
   // ownership of the observer and the observer must outlive this provider.
   virtual void SetObserver(Observer* observer) = 0;
 
   // Returns the categories provided by this provider.
-  // TODO(pke): "The value returned by this getter must not change unless
-  // OnXxx is called on the observer."
+  // When the set of provided categories changes, the Observer is notified
+  // through |OnNewSuggestions| or |OnCategoryStatusChanged| for added
+  // categories, and through |OnCategoryStatusChanged| with parameter
+  // NOT_PROVIDED for removed categories.
   virtual std::vector<Category> GetProvidedCategories() = 0;
 
   // Determines the status of the given |category|, see CategoryStatus.
   virtual CategoryStatus GetCategoryStatus(Category category) = 0;
 
   // Dismisses the suggestion with the given ID. A provider needs to ensure that
   // a once-dismissed suggestion is never delivered again (through the
   // Observer). The provider must not call Observer::OnSuggestionsChanged if the
   // removal of the dismissed suggestion is the only change.
   virtual void DismissSuggestion(const std::string& suggestion_id) = 0;
@@ skipping 32 matching lines @@
 
   CategoryFactory* category_factory() const { return category_factory_; }
 
  private:
   CategoryFactory* category_factory_;
 };
 
 }  // namespace ntp_snippets
 
 #endif  // COMPONENTS_NTP_SNIPPETS_CONTENT_SUGGESTIONS_PROVIDER_H_