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