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 14class AutocompleteInput; 15 16typedef 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. 123class 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