1 // Copyright 2014 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 5 #ifndef COMPONENTS_OMNIBOX_AUTOCOMPLETE_PROVIDER_H_ 6 #define COMPONENTS_OMNIBOX_AUTOCOMPLETE_PROVIDER_H_ 7 8 #include "base/basictypes.h" 9 #include "base/memory/ref_counted.h" 10 #include "base/strings/string16.h" 11 #include "components/metrics/proto/omnibox_event.pb.h" 12 #include "components/omnibox/autocomplete_match.h" 13 14 class AutocompleteInput; 15 16 typedef std::vector<metrics::OmniboxEventProto_ProviderInfo> ProvidersInfo; 17 18 // The AutocompleteProviders each return different kinds of matches, 19 // such as history or search matches. These matches are given 20 // "relevance" scores. Higher scores are better matches than lower 21 // scores. The relevance scores and classes providing the respective 22 // matches are as listed below. 23 // 24 // IMPORTANT CAVEAT: The tables below are NOT COMPLETE. Developers 25 // often forget to keep these tables in sync with the code when they 26 // change scoring algorithms or add new providers. For example, 27 // neither the HistoryQuickProvider (which is a provider that appears 28 // often) nor the ShortcutsProvider are listed here. For the best 29 // idea of how scoring works and what providers are affecting which 30 // queries, play with chrome://omnibox/ for a while. While the tables 31 // below may have some utility, nothing compares with first-hand 32 // investigation and experience. 33 // 34 // UNKNOWN input type: 35 // --------------------------------------------------------------------|----- 36 // Keyword (non-substituting or in keyword UI mode, exact match) | 1500 37 // HistoryURL (good exact or inline autocomplete matches, some inexact)| 1410++ 38 // HistoryURL (intranet url never visited match, some inexact matches) | 1400++ 39 // Search Primary Provider (past query in history within 2 days) | 1399** 40 // Search Primary Provider (what you typed) | 1300 41 // HistoryURL (what you typed, some inexact matches) | 1200++ 42 // Keyword (substituting, exact match) | 1100 43 // Search Primary Provider (past query in history older than 2 days) | 1050-- 44 // HistoryURL (some inexact matches) | 900++ 45 // BookmarkProvider (prefix match in bookmark title) | 900+- 46 // Built-in | 860++ 47 // Search Primary Provider (navigational suggestion) | 800++ 48 // Search Primary Provider (suggestion) | 600++ 49 // Keyword (inexact match) | 450 50 // Search Secondary Provider (what you typed) | 250 51 // Search Secondary Provider (past query in history) | 200-- 52 // Search Secondary Provider (navigational suggestion) | 150++ 53 // Search Secondary Provider (suggestion) | 100++ 54 // 55 // URL input type: 56 // --------------------------------------------------------------------|----- 57 // Keyword (non-substituting or in keyword UI mode, exact match) | 1500 58 // HistoryURL (good exact or inline autocomplete matches, some inexact)| 1410++ 59 // HistoryURL (intranet url never visited match, some inexact matches) | 1400++ 60 // HistoryURL (what you typed, some inexact matches) | 1200++ 61 // Keyword (substituting, exact match) | 1100 62 // HistoryURL (some inexact matches) | 900++ 63 // Built-in | 860++ 64 // Search Primary Provider (what you typed) | 850 65 // Search Primary Provider (navigational suggestion) | 800++ 66 // Search Primary Provider (past query in history) | 750-- 67 // Keyword (inexact match) | 700 68 // Search Primary Provider (suggestion) | 300++ 69 // Search Secondary Provider (what you typed) | 250 70 // Search Secondary Provider (past query in history) | 200-- 71 // Search Secondary Provider (navigational suggestion) | 150++ 72 // Search Secondary Provider (suggestion) | 100++ 73 // 74 // QUERY input type: 75 // --------------------------------------------------------------------|----- 76 // Search Primary or Secondary (past query in history within 2 days) | 1599** 77 // Keyword (non-substituting or in keyword UI mode, exact match) | 1500 78 // Keyword (substituting, exact match) | 1450 79 // Search Primary Provider (past query in history within 2 days) | 1399** 80 // Search Primary Provider (what you typed) | 1300 81 // Search Primary Provider (past query in history older than 2 days) | 1050-- 82 // HistoryURL (inexact match) | 900++ 83 // BookmarkProvider (prefix match in bookmark title) | 900+- 84 // Search Primary Provider (navigational suggestion) | 800++ 85 // Search Primary Provider (suggestion) | 600++ 86 // Keyword (inexact match) | 450 87 // Search Secondary Provider (what you typed) | 250 88 // Search Secondary Provider (past query in history) | 200-- 89 // Search Secondary Provider (navigational suggestion) | 150++ 90 // Search Secondary Provider (suggestion) | 100++ 91 // 92 // FORCED_QUERY input type: 93 // --------------------------------------------------------------------|----- 94 // Search Primary Provider (past query in history within 2 days) | 1399** 95 // Search Primary Provider (what you typed) | 1300 96 // Search Primary Provider (past query in history older than 2 days) | 1050-- 97 // Search Primary Provider (navigational suggestion) | 800++ 98 // Search Primary Provider (suggestion) | 600++ 99 // 100 // (A search keyword is a keyword with a replacement string; a bookmark keyword 101 // is a keyword with no replacement string, that is, a shortcut for a URL.) 102 // 103 // There are two possible providers for search suggestions. If the user has 104 // typed a keyword, then the primary provider is the keyword provider and the 105 // secondary provider is the default provider. If the user has not typed a 106 // keyword, then the primary provider corresponds to the default provider. 107 // 108 // Search providers may supply relevance values along with their results to be 109 // used in place of client-side calculated values. 110 // 111 // The value column gives the ranking returned from the various providers. 112 // ++: a series of matches with relevance from n up to (n + max_matches). 113 // --: relevance score falls off over time (discounted 50 points @ 15 minutes, 114 // 450 points @ two weeks) 115 // **: relevance score falls off over two days (discounted 99 points after two 116 // days). 117 // +-: A base score that the provider will adjust upward or downward based on 118 // provider-specific metrics. 119 // 120 // A single result provider for the autocomplete system. Given user input, the 121 // provider decides what (if any) matches to return, their relevance, and their 122 // classifications. 123 class AutocompleteProvider 124 : public base::RefCountedThreadSafe<AutocompleteProvider> { 125 public: 126 // Different AutocompleteProvider implementations. 127 enum Type { 128 TYPE_BOOKMARK = 1 << 0, 129 TYPE_BUILTIN = 1 << 1, 130 TYPE_HISTORY_QUICK = 1 << 2, 131 TYPE_HISTORY_URL = 1 << 3, 132 TYPE_KEYWORD = 1 << 4, 133 TYPE_SEARCH = 1 << 5, 134 TYPE_SHORTCUTS = 1 << 6, 135 TYPE_ZERO_SUGGEST = 1 << 7, 136 }; 137 138 explicit AutocompleteProvider(Type type); 139 140 // Returns a string describing a particular AutocompleteProvider type. 141 static const char* TypeToString(Type type); 142 143 // Called to start an autocomplete query. The provider is responsible for 144 // tracking its matches for this query and whether it is done processing the 145 // query. When new matches are available or the provider finishes, it 146 // calls the controller's OnProviderUpdate() method. The controller can then 147 // get the new matches using the provider's accessors. 148 // Exception: Matches available immediately after starting the query (that 149 // is, synchronously) do not cause any notifications to be sent. The 150 // controller is expected to check for these without prompting (since 151 // otherwise, starting each provider running would result in a flurry of 152 // notifications). 153 // 154 // Once Stop() has been called, no more notifications should be sent. 155 // 156 // |minimal_changes| is an optimization that lets the provider do less work 157 // when the |input|'s text hasn't changed. See the body of 158 // OmniboxPopupModel::StartAutocomplete(). 159 virtual void Start(const AutocompleteInput& input, bool minimal_changes) = 0; 160 161 // Called when a provider must not make any more callbacks for the current 162 // query. This will be called regardless of whether the provider is already 163 // done. If the provider caches any results, it should clear the cache based 164 // on the value of |clear_cached_results|. 165 virtual void Stop(bool clear_cached_results); 166 167 // Returns the enum equivalent to the name of this provider. 168 // TODO(derat): Make metrics use AutocompleteProvider::Type directly, or at 169 // least move this method to the metrics directory. 170 metrics::OmniboxEventProto_ProviderType AsOmniboxEventProviderType() const; 171 172 // Called to delete a match and the backing data that produced it. This 173 // match should not appear again in this or future queries. This can only be 174 // called for matches the provider marks as deletable. This should only be 175 // called when no query is running. 176 // NOTE: Do NOT call OnProviderUpdate() in this method, it is the 177 // responsibility of the caller to do so after calling us. 178 virtual void DeleteMatch(const AutocompleteMatch& match); 179 180 // Called when an omnibox event log entry is generated. This gives 181 // a provider the opportunity to add diagnostic information to the 182 // logs. A provider is expected to append a single entry of whatever 183 // information it wants to |provider_info|. 184 virtual void AddProviderInfo(ProvidersInfo* provider_info) const; 185 186 // Called when a new omnibox session starts or the current session ends. 187 // This gives the opportunity to reset the internal state, if any, associated 188 // with the previous session. 189 virtual void ResetSession(); 190 191 // Returns the set of matches for the current query. 192 const ACMatches& matches() const { return matches_; } 193 194 // Returns whether the provider is done processing the query. 195 bool done() const { return done_; } 196 197 // Returns this provider's type. 198 Type type() const { return type_; } 199 200 // Returns a string describing this provider's type. 201 const char* GetName() const; 202 203 // A suggested upper bound for how many matches a provider should return. 204 // TODO(pkasting): http://b/1111299 , http://b/933133 This should go away once 205 // we have good relevance heuristics; the controller should handle all 206 // culling. 207 static const size_t kMaxMatches; 208 209 protected: 210 friend class base::RefCountedThreadSafe<AutocompleteProvider>; 211 FRIEND_TEST_ALL_PREFIXES(BookmarkProviderTest, InlineAutocompletion); 212 213 typedef std::pair<bool, base::string16> FixupReturn; 214 215 virtual ~AutocompleteProvider(); 216 217 // Fixes up user URL input to make it more possible to match against. Among 218 // many other things, this takes care of the following: 219 // * Prepending file:// to file URLs 220 // * Converting drive letters in file URLs to uppercase 221 // * Converting case-insensitive parts of URLs (like the scheme and domain) 222 // to lowercase 223 // * Convert spaces to %20s 224 // Note that we don't do this in AutocompleteInput's constructor, because if 225 // e.g. we convert a Unicode hostname to punycode, other providers will show 226 // output that surprises the user ("Search Google for xn--6ca.com"). 227 // Returns a bool indicating whether fixup succeeded, as well as the fixed-up 228 // input text. The returned string will be the same as the input string if 229 // fixup failed; this lets callers who don't care about failure simply use the 230 // string unconditionally. 231 static FixupReturn FixupUserInput(const AutocompleteInput& input); 232 233 // Trims "http:" and up to two subsequent slashes from |url|. Returns the 234 // number of characters that were trimmed. 235 // NOTE: For a view-source: URL, this will trim from after "view-source:" and 236 // return 0. 237 static size_t TrimHttpPrefix(base::string16* url); 238 239 ACMatches matches_; 240 bool done_; 241 242 Type type_; 243 244 private: 245 DISALLOW_COPY_AND_ASSIGN(AutocompleteProvider); 246 }; 247 248 #endif // COMPONENTS_OMNIBOX_AUTOCOMPLETE_PROVIDER_H_ 249
