chrome/browser/extensions/api/declarative_content/content_predicate_evaluator.h

   1 // Copyright 2015 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_EXTENSIONS_API_DECLARATIVE_CONTENT_CONTENT_PREDICATE_EVALUATOR_H_
   6 #define CHROME_BROWSER_EXTENSIONS_API_DECLARATIVE_CONTENT_CONTENT_PREDICATE_EVALUATOR_H_
   7
   8 #include <map>
   9 #include <vector>
  10
  11 #include "base/macros.h"
  12 #include "chrome/browser/extensions/api/declarative_content/content_predicate.h"
  13
  14 namespace content {
  15 class BrowserContext;
  16 struct FrameNavigateParams;
  17 struct LoadCommittedDetails;
  18 class WebContents;
  19 }  // namespace content
  20
  21 namespace extensions {
  22
  23 class Extension;
  24
  25 // Creates and manages instances of an associated ContentPredicate subclass and
  26 // tracks the url and browser context state required to evaluate the predicates.
  27 //
  28 // A ContentPredicateEvaluator corresponds to a single attribute name across all
  29 // chrome.declarativeContent.PageStateMatchers provided in all rules in the
  30 // Declarative Content API. For example, given the rules:
  31 //
  32 // var rule1 = {
  33 //   conditions: [
  34 //     new chrome.declarativeContent.PageStateMatcher({
  35 //       pageUrl: { hostEquals: 'www.google.com', schemes: ['https'] },
  36 //       css: ['input[type=\'password\']']
  37 //     })
  38 //   ],
  39 //   actions: [ new chrome.declarativeContent.ShowPageAction() ]
  40 // };
  41 //
  42 // var rule2 = {
  43 //   conditions: [
  44 //     new chrome.declarativeContent.PageStateMatcher({
  45 //       pageUrl: { hostEquals: 'www.example.com' },
  46 //       css: ['a', 'image']
  47 //     })
  48 //   ],
  49 //   actions: [ new chrome.declarativeContent.ShowPageAction() ]
  50 // };
  51 //
  52 // The subclass of ContentPredicateEvaluator whose
  53 // GetPredicateApiAttributeName() function returns "pageUrl" is responsible for
  54 // creating and managing the predicates
  55 // { hostEquals: 'www.google.com', schemes: ['https'] } and
  56 // { hostEquals: 'www.example.com' }.
  57 //
  58 // The subclass of ContentPredicateEvaluator whose
  59 // GetPredicateApiAttributeName() function returns "css" is responsible for
  60 // creating and managing the predicates ['input[type=\'password\']'] and
  61 // ['a', 'image'].
  62 class ContentPredicateEvaluator : public ContentPredicateFactory {
  63  public:
  64   class Delegate;
  65
  66   ~ContentPredicateEvaluator() override;
  67
  68   // Returns the attribute name in the API for this evaluator's predicates.
  69   virtual std::string GetPredicateApiAttributeName() const = 0;
  70
  71   // Notifies the evaluator that the grouped predicates should be tracked. This
  72   // function must always be called after creating a set of predicates. If the
  73   // predicates should be tracked, |predicates| must contain all the created
  74   // predicates. Otherwise, it will be called with an empty map and the created
  75   // predicates should not be tracked.
  76   virtual void TrackPredicates(
  77       const std::map<const void*,
  78                      std::vector<const ContentPredicate*>>& predicates) = 0;
  79
  80   // Notifies the evaluator that it should stop tracking the predicates
  81   // associated with |predicate_groups|.
  82   virtual void StopTrackingPredicates(
  83       const std::vector<const void*>& predicate_groups) = 0;
  84
  85   // Requests that predicates be tracked for |contents|.
  86   virtual void TrackForWebContents(content::WebContents* contents) = 0;
  87
  88   // Handles navigation of |contents|. We depend on the caller to notify us of
  89   // this event rather than having each evaluator listen to it, so that the
  90   // caller can coordinate evaluation with all the evaluators that respond to
  91   // it. If an evaluator listened and requested rule evaluation before another
  92   // evaluator received the notification, the first evaluator's predicates would
  93   // be evaluated based on the new URL while the other evaluator's conditions
  94   // would still be evaluated based on the previous URL.
  95   virtual void OnWebContentsNavigation(
  96       content::WebContents* contents,
  97       const content::LoadCommittedDetails& details,
  98       const content::FrameNavigateParams& params) = 0;
  99
 100   // Returns true if |predicate| evaluates to true on the state associated with
 101   // |tab|. It must be the case that predicate->GetEvaluator() == this object,
 102   // |predicate| was previously passed to TrackPredicates(), and
 103   // StopTrackingPredicates has not yet been called with the group containing
 104   // |predicate|.
 105   virtual bool EvaluatePredicate(const ContentPredicate* predicate,
 106                                  content::WebContents* tab) const = 0;
 107
 108  protected:
 109   ContentPredicateEvaluator();
 110
 111  private:
 112   DISALLOW_COPY_AND_ASSIGN(ContentPredicateEvaluator);
 113 };
 114
 115 // Allows an evaluator to notify that predicate evaluation state has been
 116 // updated, and determine whether it should manage predicates for a context.
 117 class ContentPredicateEvaluator::Delegate {
 118  public:
 119   // Notifies that predicate evaluation state has been updated for
 120   // |contents|. This must be called whenever the URL or page state changes,
 121   // even if the value of the predicate evaluation itself doesn't change.
 122   // TODO(wittman): rename to something like NotifyPredicateStateUpdated.
 123   virtual void RequestEvaluation(content::WebContents* contents) = 0;
 124
 125   // Returns true if the evaluator should manage condition state for
 126   // |context|.  TODO(wittman): rename to something like
 127   // ShouldManagePredicatesForBrowserContext.
 128   virtual bool ShouldManageConditionsForBrowserContext(
 129       content::BrowserContext* context) = 0;
 130
 131  protected:
 132   Delegate();
 133   virtual ~Delegate();
 134
 135  private:
 136   DISALLOW_COPY_AND_ASSIGN(Delegate);
 137 };
 138
 139 }  // namespace extensions
 140
 141 #endif  // CHROME_BROWSER_EXTENSIONS_API_DECLARATIVE_CONTENT_CONTENT_PREDICATE_EVALUATOR_H_