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.
5 #ifndef CHROME_BROWSER_HISTORY_HISTORY_TYPES_H_
6 #define CHROME_BROWSER_HISTORY_HISTORY_TYPES_H_
14 #include "base/basictypes.h"
15 #include "base/containers/stack_container.h"
16 #include "base/memory/ref_counted_memory.h"
17 #include "base/memory/scoped_vector.h"
18 #include "base/strings/string16.h"
19 #include "base/time/time.h"
20 #include "chrome/browser/history/snippet.h"
21 #include "chrome/browser/search_engines/template_url_id.h"
22 #include "chrome/common/favicon/favicon_types.h"
23 #include "chrome/common/ref_counted_util.h"
24 #include "chrome/common/thumbnail_score.h"
25 #include "content/public/common/page_transition_types.h"
26 #include "ui/gfx/image/image.h"
27 #include "ui/gfx/size.h"
34 // Forward declaration for friend statements.
38 // Structure to hold redirect lists for URLs. For a redirect chain
39 // A -> B -> C, and entry in the map would look like "A => {B -> C}".
40 typedef std::map<GURL, scoped_refptr<RefCountedVector<GURL> > > RedirectMap;
42 // Container for a list of URLs.
43 typedef std::vector<GURL> RedirectList;
45 typedef int64 FaviconBitmapID; // Identifier for a bitmap in a favicon.
46 typedef int64 SegmentID; // URL segments for the most visited view.
47 typedef int64 IconMappingID; // For page url and icon mapping.
49 // URLRow ---------------------------------------------------------------------
53 // Holds all information globally associated with one URL (one row in the
56 // This keeps track of dirty bits, which are currently unused:
58 // TODO(brettw) the dirty bits are broken in a number of respects. First, the
59 // database will want to update them on a const object, so they need to be
62 // Second, there is a problem copying. If you make a copy of this structure
63 // (as we allow since we put this into vectors in various places) then the
64 // dirty bits will not be in sync for these copies.
69 explicit URLRow(const GURL& url);
71 // We need to be able to set the id of a URLRow that's being passed through
72 // an IPC message. This constructor should probably not be used otherwise.
73 URLRow(const GURL& url, URLID id);
76 URLRow& operator=(const URLRow& other);
78 URLID id() const { return id_; }
80 // Sets the id of the row. The id should only be manually set when a row has
81 // been retrieved from the history database or other dataset based on criteria
82 // other than its id (i.e. by URL) and when the id has not yet been set in the
84 void set_id(URLID id) { id_ = id; }
86 const GURL& url() const { return url_; }
88 const base::string16& title() const {
91 void set_title(const base::string16& title) {
92 // The title is frequently set to the same thing, so we don't bother
93 // updating unless the string has changed.
94 if (title != title_) {
99 // The number of times this URL has been visited. This will often match the
100 // number of entries in the visit table for this URL, but won't always. It's
101 // really designed for autocomplete ranking, so some "useless" transitions
102 // from the visit table aren't counted in this tally.
103 int visit_count() const {
106 void set_visit_count(int visit_count) {
107 visit_count_ = visit_count;
110 // Number of times the URL was typed in the Omnibox. This "should" match
111 // the number of TYPED transitions in the visit table. It's used primarily
112 // for faster autocomplete ranking. If you need to know the actual number of
113 // TYPED transitions, you should query the visit table since there could be
114 // something out of sync.
115 int typed_count() const {
118 void set_typed_count(int typed_count) {
119 typed_count_ = typed_count;
122 base::Time last_visit() const {
125 void set_last_visit(base::Time last_visit) {
126 last_visit_ = last_visit;
129 // If this is set, we won't autocomplete this URL.
130 bool hidden() const {
133 void set_hidden(bool hidden) {
137 // Helper functor that determines if an URLRow refers to a given URL.
140 explicit URLRowHasURL(const GURL& url) : url_(url) {}
142 bool operator()(const URLRow& row) {
143 return row.url() == url_;
151 // Swaps the contents of this URLRow with another, which allows it to be
152 // destructively copied without memory allocations.
153 void Swap(URLRow* other);
156 // This class writes directly into this structure and clears our dirty bits
157 // when reading out of the DB.
158 friend class URLDatabase;
159 friend class HistoryBackend;
161 // Initializes all values that need initialization to their defaults.
162 // This excludes objects which autoinitialize such as strings.
165 // The row ID of this URL from the history database. This is immutable except
166 // when retrieving the row from the database or when determining if the URL
167 // referenced by the URLRow already exists in the database.
170 // The URL of this row. Immutable except for the database which sets it
171 // when it pulls them out. If clients want to change it, they must use
172 // the constructor to make a new one.
175 base::string16 title_;
177 // Total number of times this URL has been visited.
180 // Number of times this URL has been manually entered in the URL bar.
183 // The date of the last visit of this URL, which saves us from having to
184 // loop up in the visit table for things like autocomplete and expiration.
185 base::Time last_visit_;
187 // Indicates this entry should now be shown in typical UI or queries, this
188 // is usually for subframes.
191 // We support the implicit copy constuctor and operator=.
193 typedef std::vector<URLRow> URLRows;
195 // The enumeration of all possible sources of visits is listed below.
196 // The source will be propagated along with a URL or a visit item
197 // and eventually be stored in the history database,
198 // visit_source table specifically.
199 // Different from page transition types, they describe the origins of visits.
200 // (Warning): Please don't change any existing values while it is ok to add
201 // new values when needed.
203 SOURCE_SYNCED = 0, // Synchronized from somewhere else.
204 SOURCE_BROWSED = 1, // User browsed.
205 SOURCE_EXTENSION = 2, // Added by an extension.
206 SOURCE_FIREFOX_IMPORTED = 3,
207 SOURCE_IE_IMPORTED = 4,
208 SOURCE_SAFARI_IMPORTED = 5,
211 typedef int64 VisitID;
212 // Structure to hold the mapping between each visit's id and its source.
213 typedef std::map<VisitID, VisitSource> VisitSourceMap;
215 // VisitRow -------------------------------------------------------------------
217 // Holds all information associated with a specific visit. A visit holds time
218 // and referrer information for one time a URL is visited.
222 VisitRow(URLID arg_url_id,
223 base::Time arg_visit_time,
224 VisitID arg_referring_visit,
225 content::PageTransition arg_transition,
226 SegmentID arg_segment_id);
229 // ID of this row (visit ID, used a a referrer for other visits).
232 // Row ID into the URL table of the URL that this page is.
235 base::Time visit_time;
237 // Indicates another visit that was the referring page for this one.
238 // 0 indicates no referrer.
239 VisitID referring_visit;
241 // A combination of bits from PageTransition.
242 content::PageTransition transition;
244 // The segment id (see visitsegment_database.*).
245 // If 0, the segment id is null in the table.
246 SegmentID segment_id;
248 // Record how much time a user has this visit starting from the user
249 // opened this visit to the user closed or ended this visit.
250 // This includes both active and inactive time as long as
251 // the visit was present.
252 base::TimeDelta visit_duration;
254 // Compares two visits based on dates, for sorting.
255 bool operator<(const VisitRow& other) {
256 return visit_time < other.visit_time;
259 // We allow the implicit copy constuctor and operator=.
262 // We pass around vectors of visits a lot
263 typedef std::vector<VisitRow> VisitVector;
265 // The basic information associated with a visit (timestamp, type of visit),
266 // used by HistoryBackend::AddVisits() to create new visits for a URL.
267 typedef std::pair<base::Time, content::PageTransition> VisitInfo;
269 // PageVisit ------------------------------------------------------------------
271 // Represents a simplified version of a visit for external users. Normally,
272 // views are only interested in the time, and not the other information
273 // associated with a VisitRow.
276 base::Time visit_time;
279 // URLResult -------------------------------------------------------------------
281 class URLResult : public URLRow {
284 URLResult(const GURL& url, base::Time visit_time);
285 // Constructor that create a URLResult from the specified URL and title match
286 // positions from title_matches.
287 URLResult(const GURL& url, const Snippet::MatchPositions& title_matches);
288 explicit URLResult(const URLRow& url_row);
289 virtual ~URLResult();
291 base::Time visit_time() const { return visit_time_; }
292 void set_visit_time(base::Time visit_time) { visit_time_ = visit_time; }
294 const Snippet& snippet() const { return snippet_; }
296 bool blocked_visit() const { return blocked_visit_; }
297 void set_blocked_visit(bool blocked_visit) {
298 blocked_visit_ = blocked_visit;
301 // If this is a title match, title_match_positions contains an entry for
302 // every word in the title that matched one of the query parameters. Each
303 // entry contains the start and end of the match.
304 const Snippet::MatchPositions& title_match_positions() const {
305 return title_match_positions_;
308 void SwapResult(URLResult* other);
310 static bool CompareVisitTime(const URLResult& lhs, const URLResult& rhs);
313 friend class HistoryBackend;
315 // The time that this result corresponds to.
316 base::Time visit_time_;
318 // These values are typically set by HistoryBackend.
320 Snippet::MatchPositions title_match_positions_;
322 // Whether a managed user was blocked when attempting to visit this URL.
325 // We support the implicit copy constructor and operator=.
328 // QueryResults ----------------------------------------------------------------
330 // Encapsulates the results of a history query. It supports an ordered list of
331 // URLResult objects, plus an efficient way of looking up the index of each time
332 // a given URL appears in those results.
335 typedef std::vector<URLResult*> URLResultVector;
340 // Indicates the first time that the query includes results for (queries are
341 // clipped at the beginning, so it will always include to the end of the time
344 // If the number of results was clipped as a result of the max count, this
345 // will be the time of the first query returned. If there were fewer results
346 // than we were allowed to return, this represents the first date considered
347 // in the query (this will be before the first result if there was time
348 // queried with no results).
350 // TODO(brettw): bug 1203054: This field is not currently set properly! Do
351 // not use until the bug is fixed.
352 base::Time first_time_searched() const { return first_time_searched_; }
353 void set_first_time_searched(base::Time t) { first_time_searched_ = t; }
354 // Note: If you need end_time_searched, it can be added.
356 void set_reached_beginning(bool reached) { reached_beginning_ = reached; }
357 bool reached_beginning() { return reached_beginning_; }
359 size_t size() const { return results_.size(); }
360 bool empty() const { return results_.empty(); }
362 URLResult& back() { return *results_.back(); }
363 const URLResult& back() const { return *results_.back(); }
365 URLResult& operator[](size_t i) { return *results_[i]; }
366 const URLResult& operator[](size_t i) const { return *results_[i]; }
368 URLResultVector::const_iterator begin() const { return results_.begin(); }
369 URLResultVector::const_iterator end() const { return results_.end(); }
370 URLResultVector::const_reverse_iterator rbegin() const {
371 return results_.rbegin();
373 URLResultVector::const_reverse_iterator rend() const {
374 return results_.rend();
377 // Returns a pointer to the beginning of an array of all matching indices
378 // for entries with the given URL. The array will be |*num_matches| long.
379 // |num_matches| can be NULL if the caller is not interested in the number of
380 // results (commonly it will only be interested in the first one and can test
381 // the pointer for NULL).
383 // When there is no match, it will return NULL and |*num_matches| will be 0.
384 const size_t* MatchesForURL(const GURL& url, size_t* num_matches) const;
386 // Swaps the current result with another. This allows ownership to be
387 // efficiently transferred without copying.
388 void Swap(QueryResults* other);
390 // Adds the given result to the map, using swap() on the members to avoid
391 // copying (there are a lot of strings and vectors). This means the parameter
392 // object will be cleared after this call.
393 void AppendURLBySwapping(URLResult* result);
395 // Removes all instances of the given URL from the result set.
396 void DeleteURL(const GURL& url);
398 // Deletes the given range of items in the result set.
399 void DeleteRange(size_t begin, size_t end);
402 // Maps the given URL to a list of indices into results_ which identify each
403 // time an entry with that URL appears. Normally, each URL will have one or
404 // very few indices after it, so we optimize this to use statically allocated
405 // memory when possible.
406 typedef std::map<GURL, base::StackVector<size_t, 4> > URLToResultIndices;
408 // Inserts an entry into the |url_to_results_| map saying that the given URL
409 // is at the given index in the results_.
410 void AddURLUsageAtIndex(const GURL& url, size_t index);
412 // Adds |delta| to each index in url_to_results_ in the range [begin,end]
413 // (this is inclusive). This is used when inserting or deleting.
414 void AdjustResultMap(size_t begin, size_t end, ptrdiff_t delta);
416 base::Time first_time_searched_;
418 // Whether the query reaches the beginning of the database.
419 bool reached_beginning_;
421 // The ordered list of results. The pointers inside this are owned by this
422 // QueryResults object.
423 ScopedVector<URLResult> results_;
425 // Maps URLs to entries in results_.
426 URLToResultIndices url_to_results_;
428 DISALLOW_COPY_AND_ASSIGN(QueryResults);
431 // QueryOptions ----------------------------------------------------------------
433 struct QueryOptions {
436 // The time range to search for matches in. The beginning is inclusive and
437 // the ending is exclusive. Either one (or both) may be null.
439 // This will match only the one recent visit of a URL. For text search
440 // queries, if the URL was visited in the given time period, but has also
441 // been visited more recently than that, it will not be returned. When the
442 // text query is empty, this will return the most recent visit within the
444 base::Time begin_time;
447 // Sets the query time to the last |days_ago| days to the present time.
448 void SetRecentDayRange(int days_ago);
450 // The maximum number of results to return. The results will be sorted with
451 // the most recent first, so older results may not be returned if there is not
452 // enough room. When 0, this will return everything (the default).
455 enum DuplicateHandling {
456 // Omit visits for which there is a more recent visit to the same URL.
457 // Each URL in the results will appear only once.
458 REMOVE_ALL_DUPLICATES,
460 // Omit visits for which there is a more recent visit to the same URL on
461 // the same day. Each URL will appear no more than once per day, where the
462 // day is defined by the local timezone.
463 REMOVE_DUPLICATES_PER_DAY,
465 // Return all visits without deduping.
469 // Allows the caller to specify how duplicate URLs in the result set should
470 // be handled. The default is REMOVE_DUPLICATES.
471 DuplicateHandling duplicate_policy;
473 // Helpers to get the effective parameters values, since a value of 0 means
475 int EffectiveMaxCount() const;
476 int64 EffectiveBeginTime() const;
477 int64 EffectiveEndTime() const;
480 // KeywordSearchTermVisit -----------------------------------------------------
482 // KeywordSearchTermVisit is returned from GetMostRecentKeywordSearchTerms. It
483 // gives the time and search term of the keyword visit.
484 struct KeywordSearchTermVisit {
485 KeywordSearchTermVisit();
486 ~KeywordSearchTermVisit();
488 base::string16 term; // The search term that was used.
489 int visits; // The visit count.
490 base::Time time; // The time of the most recent visit.
493 // KeywordSearchTermRow --------------------------------------------------------
495 // Used for URLs that have a search term associated with them.
496 struct KeywordSearchTermRow {
497 KeywordSearchTermRow();
498 ~KeywordSearchTermRow();
500 TemplateURLID keyword_id; // ID of the keyword.
501 URLID url_id; // ID of the url.
502 base::string16 term; // The search term that was used.
505 // MostVisitedURL --------------------------------------------------------------
507 // Holds the per-URL information of the most visited query.
508 struct MostVisitedURL {
510 MostVisitedURL(const GURL& url, const base::string16& title);
511 MostVisitedURL(const GURL& url,
512 const base::string16& title,
513 const base::Time& last_forced_time);
517 base::string16 title;
519 // If this is a URL for which we want to force a thumbnail, records the last
520 // time it was forced so we can evict it when more recent URLs are requested.
521 // If it's not a forced thumbnail, keep a time of 0.
522 base::Time last_forced_time;
524 RedirectList redirects;
526 bool operator==(const MostVisitedURL& other) {
527 return url == other.url;
531 // FilteredURL -----------------------------------------------------------------
533 // Holds the per-URL information of the filterd url query.
535 struct ExtendedInfo {
537 // The absolute number of visits.
538 unsigned int total_visits;
539 // The number of visits, as seen by the Most Visited NTP pane.
541 // The total number of seconds that the page was open.
542 int64 duration_opened;
543 // The time when the page was last visited.
544 base::Time last_visit_time;
548 explicit FilteredURL(const PageUsageData& data);
552 base::string16 title;
554 ExtendedInfo extended_info;
557 // Navigation -----------------------------------------------------------------
559 // Marshalling structure for AddPage.
560 struct HistoryAddPageArgs {
561 // The default constructor is equivalent to:
563 // HistoryAddPageArgs(
564 // GURL(), base::Time(), NULL, 0, GURL(),
565 // history::RedirectList(), content::PAGE_TRANSITION_LINK,
566 // SOURCE_BROWSED, false)
567 HistoryAddPageArgs();
568 HistoryAddPageArgs(const GURL& url,
570 const void* id_scope,
572 const GURL& referrer,
573 const history::RedirectList& redirects,
574 content::PageTransition transition,
576 bool did_replace_entry);
577 ~HistoryAddPageArgs();
582 const void* id_scope;
586 history::RedirectList redirects;
587 content::PageTransition transition;
588 VisitSource visit_source;
589 bool did_replace_entry;
592 // TopSites -------------------------------------------------------------------
594 typedef std::vector<MostVisitedURL> MostVisitedURLList;
595 typedef std::vector<FilteredURL> FilteredURLList;
597 // Used by TopSites to store the thumbnails.
602 scoped_refptr<base::RefCountedMemory> thumbnail;
603 ThumbnailScore thumbnail_score;
605 // TODO(brettw): this will eventually store the favicon.
606 // scoped_refptr<base::RefCountedBytes> favicon;
609 struct MostVisitedURLWithRank {
614 typedef std::vector<MostVisitedURLWithRank> MostVisitedURLWithRankList;
616 struct TopSitesDelta {
620 MostVisitedURLList deleted;
621 MostVisitedURLWithRankList added;
622 MostVisitedURLWithRankList moved;
625 typedef std::map<GURL, scoped_refptr<base::RefCountedBytes> > URLToThumbnailMap;
627 // Used when migrating most visited thumbnails out of history and into topsites.
628 struct ThumbnailMigration {
629 ThumbnailMigration();
630 ~ThumbnailMigration();
632 MostVisitedURLList most_visited;
633 URLToThumbnailMap url_to_thumbnail_map;
636 typedef std::map<GURL, Images> URLToImagesMap;
638 class MostVisitedThumbnails
639 : public base::RefCountedThreadSafe<MostVisitedThumbnails> {
641 MostVisitedThumbnails();
643 MostVisitedURLList most_visited;
644 URLToImagesMap url_to_images_map;
647 friend class base::RefCountedThreadSafe<MostVisitedThumbnails>;
648 virtual ~MostVisitedThumbnails();
650 DISALLOW_COPY_AND_ASSIGN(MostVisitedThumbnails);
653 // Autocomplete thresholds -----------------------------------------------------
655 // Constants which specify, when considered altogether, 'significant'
656 // history items. These are used to filter out insignificant items
657 // for consideration as autocomplete candidates.
658 extern const int kLowQualityMatchTypedLimit;
659 extern const int kLowQualityMatchVisitLimit;
660 extern const int kLowQualityMatchAgeLimitInDays;
662 // Returns the date threshold for considering an history item as significant.
663 base::Time AutocompleteAgeThreshold();
665 // Return true if |row| qualifies as an autocomplete candidate. If |time_cache|
666 // is_null() then this function determines a new time threshold each time it is
667 // called. Since getting system time can be costly (such as for cases where
668 // this function will be called in a loop over many history items), you can
669 // provide a non-null |time_cache| by simply initializing |time_cache| with
670 // AutocompleteAgeThreshold() (or any other desired time in the past).
671 bool RowQualifiesAsSignificant(const URLRow& row, const base::Time& threshold);
673 // Favicons -------------------------------------------------------------------
675 // Used for the mapping between the page and icon.
680 // The unique id of the mapping.
681 IconMappingID mapping_id;
683 // The url of a web page.
686 // The unique id of the icon.
687 chrome::FaviconID icon_id;
689 // The url of the icon.
693 chrome::IconType icon_type;
696 // Defines a favicon bitmap and its associated pixel size.
697 struct FaviconBitmapIDSize {
698 FaviconBitmapIDSize();
699 ~FaviconBitmapIDSize();
701 // The unique id of the favicon bitmap.
702 FaviconBitmapID bitmap_id;
704 // The pixel dimensions of the associated bitmap.
705 gfx::Size pixel_size;
708 // Defines a favicon bitmap stored in the history backend.
709 struct FaviconBitmap {
713 // The unique id of the bitmap.
714 FaviconBitmapID bitmap_id;
716 // The id of the favicon to which the bitmap belongs to.
717 chrome::FaviconID icon_id;
719 // Time at which |bitmap_data| was last updated.
720 base::Time last_updated;
722 // The bits of the bitmap.
723 scoped_refptr<base::RefCountedMemory> bitmap_data;
725 // The pixel dimensions of bitmap_data.
726 gfx::Size pixel_size;
729 // Abbreviated information about a visit.
730 struct BriefVisitInfo {
733 content::PageTransition transition;
736 // An observer of VisitDatabase.
737 class VisitDatabaseObserver {
739 virtual ~VisitDatabaseObserver();
740 virtual void OnAddVisit(const BriefVisitInfo& info) = 0;
743 struct ExpireHistoryArgs {
745 ~ExpireHistoryArgs();
747 // Sets |begin_time| and |end_time| to the beginning and end of the day (in
748 // local time) on which |time| occurs.
749 void SetTimeRangeForOneDay(base::Time time);
752 base::Time begin_time;
756 } // namespace history
758 #endif // CHROME_BROWSER_HISTORY_HISTORY_TYPES_H_