src/chrome/browser/history/visit_database.h

   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_HISTORY_VISIT_DATABASE_H_
   6 #define CHROME_BROWSER_HISTORY_VISIT_DATABASE_H_
   7
   8 #include <vector>
   9
  10 #include "components/history/core/browser/history_types.h"
  11
  12 namespace sql {
  13 class Connection;
  14 class Statement;
  15 }
  16
  17 namespace history {
  18
  19 class VisitFilter;
  20
  21 // A visit database is one which stores visits for URLs, that is, times and
  22 // linking information. A visit database must also be a URLDatabase, as this
  23 // modifies tables used by URLs directly and could be thought of as inheriting
  24 // from URLDatabase. However, this inheritance is not explicit as things would
  25 // get too complicated and have multiple inheritance.
  26 class VisitDatabase {
  27  public:
  28   // Must call InitVisitTable() before using to make sure the database is
  29   // initialized.
  30   VisitDatabase();
  31   virtual ~VisitDatabase();
  32
  33   // Deletes the visit table. Used for rapidly clearing all visits. In this
  34   // case, InitVisitTable would be called immediately afterward to re-create it.
  35   // Returns true on success.
  36   bool DropVisitTable();
  37
  38   // Adds a line to the visit database with the given information, returning
  39   // the added row ID on success, 0 on failure. The given visit is updated with
  40   // the new row ID on success. In addition, adds its source into visit_source
  41   // table.
  42   VisitID AddVisit(VisitRow* visit, VisitSource source);
  43
  44   // Deletes the given visit from the database. If a visit with the given ID
  45   // doesn't exist, it will not do anything.
  46   void DeleteVisit(const VisitRow& visit);
  47
  48   // Query a VisitInfo giving an visit id, filling the given VisitRow.
  49   // Returns true on success.
  50   bool GetRowForVisit(VisitID visit_id, VisitRow* out_visit);
  51
  52   // Updates an existing row. The new information is set on the row, using the
  53   // VisitID as the key. The visit must exist. Returns true on success.
  54   bool UpdateVisitRow(const VisitRow& visit);
  55
  56   // Fills in the given vector with all of the visits for the given page ID,
  57   // sorted in ascending order of date. Returns true on success (although there
  58   // may still be no matches).
  59   bool GetVisitsForURL(URLID url_id, VisitVector* visits);
  60
  61   // Fills in the given vector with the visits for the given page ID which
  62   // should be user-visible, which excludes things like redirects and subframes,
  63   // and match the set of options passed, sorted in ascending order of date.
  64   //
  65   // Returns true if there are more results available, i.e. if the number of
  66   // results was restricted by |options.max_count|.
  67   bool GetVisibleVisitsForURL(URLID url_id,
  68                               const QueryOptions& options,
  69                               VisitVector* visits);
  70
  71   // Fills the vector with all visits with times in the given list.
  72   //
  73   // The results will be in no particular order.  Also, no duplicate
  74   // detection is performed, so if |times| has duplicate times,
  75   // |visits| may have duplicate visits.
  76   bool GetVisitsForTimes(const std::vector<base::Time>& times,
  77                          VisitVector* visits);
  78
  79   // Fills all visits in the time range [begin, end) to the given vector. Either
  80   // time can be is_null(), in which case the times in that direction are
  81   // unbounded.
  82   //
  83   // If |max_results| is non-zero, up to that many results will be returned. If
  84   // there are more results than that, the oldest ones will be returned. (This
  85   // is used for history expiration.)
  86   //
  87   // The results will be in increasing order of date.
  88   bool GetAllVisitsInRange(base::Time begin_time, base::Time end_time,
  89                            int max_results, VisitVector* visits);
  90
  91   // Fills all visits with specified transition in the time range [begin, end)
  92   // to the given vector. Either time can be is_null(), in which case the times
  93   // in that direction are unbounded.
  94   //
  95   // If |max_results| is non-zero, up to that many results will be returned. If
  96   // there are more results than that, the oldest ones will be returned. (This
  97   // is used for history expiration.)
  98   //
  99   // The results will be in increasing order of date.
 100   bool GetVisitsInRangeForTransition(base::Time begin_time,
 101                                      base::Time end_time,
 102                                      int max_results,
 103                                      ui::PageTransition transition,
 104                                      VisitVector* visits);
 105
 106   // Fills all visits in the given time range into the given vector that should
 107   // be user-visible, which excludes things like redirects and subframes. The
 108   // begin time is inclusive, the end time is exclusive. Either time can be
 109   // is_null(), in which case the times in that direction are unbounded.
 110   //
 111   // Up to |max_count| visits will be returned. If there are more visits than
 112   // that, the most recent |max_count| will be returned. If 0, all visits in the
 113   // range will be computed.
 114   //
 115   // Only one visit for each URL will be returned, and it will be the most
 116   // recent one in the time range.
 117   //
 118   // Returns true if there are more results available, i.e. if the number of
 119   // results was restricted by |options.max_count|.
 120   bool GetVisibleVisitsInRange(const QueryOptions& options,
 121                                VisitVector* visits);
 122
 123   // Fills all visits in the given time ranges into the given vector that are
 124   // visits made directly by the user (typed or bookmarked visits only). The
 125   // begin time is inclusive, the end time is exclusive.
 126   //
 127   // Up to |max_count| visits will be returned. If there are more visits than
 128   // that, the most recent |max_count| will be returned. If 0, all visits in the
 129   // range will be computed.
 130   void GetDirectVisitsDuringTimes(const VisitFilter& time_filter,
 131                                    int max_count,
 132                                    VisitVector* visits);
 133
 134   // Returns the visit ID for the most recent visit of the given URL ID, or 0
 135   // if there is no visit for the URL.
 136   //
 137   // If non-NULL, the given visit row will be filled with the information of
 138   // the found visit. When no visit is found, the row will be unchanged.
 139   VisitID GetMostRecentVisitForURL(URLID url_id,
 140                                    VisitRow* visit_row);
 141
 142   // Returns the |max_results| most recent visit sessions for |url_id|.
 143   //
 144   // Returns false if there's a failure preparing the statement. True
 145   // otherwise. (No results are indicated with an empty |visits|
 146   // vector.)
 147   bool GetMostRecentVisitsForURL(URLID url_id,
 148                                  int max_results,
 149                                  VisitVector* visits);
 150
 151   // Finds a redirect coming from the given |from_visit|. If a redirect is
 152   // found, it fills the visit ID and URL into the out variables and returns
 153   // true. If there is no redirect from the given visit, returns false.
 154   //
 155   // If there is more than one redirect, this will compute a random one. But
 156   // duplicates should be very rare, and we don't actually care which one we
 157   // get in most cases. These will occur when the user goes back and gets
 158   // redirected again.
 159   //
 160   // to_visit and to_url can be NULL in which case they are ignored.
 161   bool GetRedirectFromVisit(VisitID from_visit,
 162                             VisitID* to_visit,
 163                             GURL* to_url);
 164
 165   // Similar to the above function except finds a redirect going to a given
 166   // |to_visit|.
 167   bool GetRedirectToVisit(VisitID to_visit,
 168                           VisitID* from_visit,
 169                           GURL* from_url);
 170
 171   // Gets the number of user-visible visits to all URLs on the same
 172   // scheme/host/port as |url|, as well as the time of the earliest visit.
 173   // "User-visible" is defined as in GetVisibleVisitsInRange() above, i.e.
 174   // excluding redirects and subframes.
 175   // This function is only valid for HTTP and HTTPS URLs; all other schemes
 176   // cause the function to return false.
 177   bool GetVisibleVisitCountToHost(const GURL& url,
 178                                   int* count,
 179                                   base::Time* first_visit);
 180
 181   // Get the time of the first item in our database.
 182   bool GetStartDate(base::Time* first_visit);
 183
 184   // Get the source information about the given visits.
 185   void GetVisitsSource(const VisitVector& visits,
 186                        VisitSourceMap* sources);
 187
 188   // Obtains BriefVisitInfo for the specified number of most recent visits
 189   // from the visit database.
 190   void GetBriefVisitInfoOfMostRecentVisits(
 191       int max_visits,
 192       std::vector<BriefVisitInfo>* result_vector);
 193
 194  protected:
 195   // Returns the database for the functions in this interface.
 196   virtual sql::Connection& GetDB() = 0;
 197
 198   // Called by the derived classes on initialization to make sure the tables
 199   // and indices are properly set up. Must be called before anything else.
 200   bool InitVisitTable();
 201
 202   // Convenience to fill a VisitRow. Assumes the visit values are bound starting
 203   // at index 0.
 204   static void FillVisitRow(sql::Statement& statement, VisitRow* visit);
 205
 206   // Convenience to fill a VisitVector. Assumes that statement.step()
 207   // hasn't happened yet.
 208   static bool FillVisitVector(sql::Statement& statement, VisitVector* visits);
 209
 210   // Convenience to fill a VisitVector while respecting the set of options.
 211   // |statement| should order the query decending by visit_time to ensure
 212   // correct duplicate management behavior. Assumes that statement.step()
 213   // hasn't happened yet.
 214   static bool FillVisitVectorWithOptions(sql::Statement& statement,
 215                                          const QueryOptions& options,
 216                                          VisitVector* visits);
 217
 218   // Called by the derived classes to migrate the older visits table which
 219   // don't have visit_duration column yet.
 220   bool MigrateVisitsWithoutDuration();
 221
 222  private:
 223
 224   DISALLOW_COPY_AND_ASSIGN(VisitDatabase);
 225 };
 226
 227 // Rows, in order, of the visit table.
 228 #define HISTORY_VISIT_ROW_FIELDS \
 229     " id,url,visit_time,from_visit,transition,segment_id,visit_duration "
 230
 231 }  // namespace history
 232
 233 #endif  // CHROME_BROWSER_HISTORY_VISIT_DATABASE_H_