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