1// Copyright (c) 2009 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_HISTORY_VISIT_DATABASE_H_
6#define CHROME_BROWSER_HISTORY_VISIT_DATABASE_H_
7#pragma once
8
9#include "chrome/browser/history/history_types.h"
10
11namespace sql {
12class Connection;
13class Statement;
14}
15
16namespace history {
17
18// A visit database is one which stores visits for URLs, that is, times and
19// linking information. A visit database must also be a URLDatabase, as this
20// modifies tables used by URLs directly and could be thought of as inheriting
21// from URLDatabase. However, this inheritance is not explicit as things would
22// get too complicated and have multiple inheritance.
23class VisitDatabase {
24 public:
25  // Must call InitVisitTable() before using to make sure the database is
26  // initialized.
27  VisitDatabase();
28  virtual ~VisitDatabase();
29
30  // Deletes the visit table. Used for rapidly clearing all visits. In this
31  // case, InitVisitTable would be called immediately afterward to re-create it.
32  // Returns true on success.
33  bool DropVisitTable();
34
35  // Adds a line to the visit database with the given information, returning
36  // the added row ID on success, 0 on failure. The given visit is updated with
37  // the new row ID on success. In addition, adds its source into visit_source
38  // table.
39  VisitID AddVisit(VisitRow* visit, VisitSource source);
40
41  // Deletes the given visit from the database. If a visit with the given ID
42  // doesn't exist, it will not do anything.
43  void DeleteVisit(const VisitRow& visit);
44
45  // Query a VisitInfo giving an visit id, filling the given VisitRow.
46  // Returns true on success.
47  bool GetRowForVisit(VisitID visit_id, VisitRow* out_visit);
48
49  // Updates an existing row. The new information is set on the row, using the
50  // VisitID as the key. The visit must exist. Returns true on success.
51  bool UpdateVisitRow(const VisitRow& visit);
52
53  // Fills in the given vector with all of the visits for the given page ID,
54  // sorted in ascending order of date. Returns true on success (although there
55  // may still be no matches).
56  bool GetVisitsForURL(URLID url_id, VisitVector* visits);
57
58  // Fills all visits in the time range [begin, end) to the given vector. Either
59  // time can be is_null(), in which case the times in that direction are
60  // unbounded.
61  //
62  // If |max_results| is non-zero, up to that many results will be returned. If
63  // there are more results than that, the oldest ones will be returned. (This
64  // is used for history expiration.)
65  //
66  // The results will be in increasing order of date.
67  void GetAllVisitsInRange(base::Time begin_time, base::Time end_time,
68                           int max_results, VisitVector* visits);
69
70  // Fills all visits with specified transition in the time range [begin, end)
71  // to the given vector. Either time can be is_null(), in which case the times
72  // in that direction are unbounded.
73  //
74  // If |max_results| is non-zero, up to that many results will be returned. If
75  // there are more results than that, the oldest ones will be returned. (This
76  // is used for history expiration.)
77  //
78  // The results will be in increasing order of date.
79  void GetVisitsInRangeForTransition(base::Time begin_time,
80                                     base::Time end_time,
81                                     int max_results,
82                                     PageTransition::Type transition,
83                                     VisitVector* visits);
84
85  // Fills all visits in the given time range into the given vector that should
86  // be user-visible, which excludes things like redirects and subframes. The
87  // begin time is inclusive, the end time is exclusive. Either time can be
88  // is_null(), in which case the times in that direction are unbounded.
89  //
90  // Up to |max_count| visits will be returned. If there are more visits than
91  // that, the most recent |max_count| will be returned. If 0, all visits in the
92  // range will be computed.
93  //
94  // Only one visit for each URL will be returned, and it will be the most
95  // recent one in the time range.
96  void GetVisibleVisitsInRange(base::Time begin_time, base::Time end_time,
97                               int max_count,
98                               VisitVector* visits);
99
100  // Returns the visit ID for the most recent visit of the given URL ID, or 0
101  // if there is no visit for the URL.
102  //
103  // If non-NULL, the given visit row will be filled with the information of
104  // the found visit. When no visit is found, the row will be unchanged.
105  VisitID GetMostRecentVisitForURL(URLID url_id,
106                                   VisitRow* visit_row);
107
108  // Returns the |max_results| most recent visit sessions for |url_id|.
109  //
110  // Returns false if there's a failure preparing the statement. True
111  // otherwise. (No results are indicated with an empty |visits|
112  // vector.)
113  bool GetMostRecentVisitsForURL(URLID url_id,
114                                 int max_results,
115                                 VisitVector* visits);
116
117  // Finds a redirect coming from the given |from_visit|. If a redirect is
118  // found, it fills the visit ID and URL into the out variables and returns
119  // true. If there is no redirect from the given visit, returns false.
120  //
121  // If there is more than one redirect, this will compute a random one. But
122  // duplicates should be very rare, and we don't actually care which one we
123  // get in most cases. These will occur when the user goes back and gets
124  // redirected again.
125  //
126  // to_visit and to_url can be NULL in which case they are ignored.
127  bool GetRedirectFromVisit(VisitID from_visit,
128                            VisitID* to_visit,
129                            GURL* to_url);
130
131  // Similar to the above function except finds a redirect going to a given
132  // |to_visit|.
133  bool GetRedirectToVisit(VisitID to_visit,
134                          VisitID* from_visit,
135                          GURL* from_url);
136
137  // Returns the number of visits to all urls on the scheme/host/post
138  // identified by url. This is only valid for http and https urls (all other
139  // schemes are ignored and false is returned).
140  // count is set to the number of visits, first_visit is set to the first time
141  // the host was visited. Returns true on success.
142  bool GetVisitCountToHost(const GURL& url, int* count,
143                           base::Time* first_visit);
144
145  // Get the time of the first item in our database.
146  bool GetStartDate(base::Time* first_visit);
147
148  // Get the source information about the given visits.
149  void GetVisitsSource(const VisitVector& visits,
150                       VisitSourceMap* sources);
151
152 protected:
153  // Returns the database for the functions in this interface.
154  virtual sql::Connection& GetDB() = 0;
155
156  // Called by the derived classes on initialization to make sure the tables
157  // and indices are properly set up. Must be called before anything else.
158  bool InitVisitTable();
159
160  // Convenience to fill a VisitRow. Assumes the visit values are bound starting
161  // at index 0.
162  static void FillVisitRow(sql::Statement& statement, VisitRow* visit);
163
164  // Convenience to fill a VisitVector. Assumes that statement.step()
165  // hasn't happened yet.
166  static void FillVisitVector(sql::Statement& statement, VisitVector* visits);
167
168 private:
169  DISALLOW_COPY_AND_ASSIGN(VisitDatabase);
170};
171
172}  // history
173
174#endif  // CHROME_BROWSER_HISTORY_VISIT_DATABASE_H_
175