summaryrefslogtreecommitdiffstats
path: root/toolkit/components/cookiebanners/nsICookieBannerService.idl
blob: b58e72631046d1f0edd3e55c176f9cd1fef38ae9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsIClickRule.idl"
#include "nsICookieBannerRule.idl"
#include "nsICookieRule.idl"
#include "nsIURI.idl"
webidl BrowsingContext;

/**
 * Service singleton which owns the cookie banner feature.
 * This service owns the cookie banner handling rules.
 * It initializes both the component for importing rules
 * (nsICookieBannerListService) and injecting cookies (nsICookieInjector).
 */
[scriptable, uuid(eac9cdc4-ecee-49f2-91da-7627e15c1f3c)]
interface nsICookieBannerService : nsISupports {

  /**
   * Modes for cookie banner handling
   * MODE_DISABLED - No cookie banner handling, service disabled.
   * MODE_REJECT - Only handle banners where selecting "reject all" is possible.
   * MODE_REJECT_OR_ACCEPT - Prefer selecting "reject all", if not possible
   * fall back to "accept all".
   * MODE_UNSET - This represents the service mode is unset, the setting should
   * fall back to default setting. This is used for the per-domain preferences.
   */
  cenum Modes : 8 {
    MODE_DISABLED,
    MODE_REJECT,
    MODE_REJECT_OR_ACCEPT,
    MODE_UNSET,
  };

  /**
   * Whether the feature / service is enabled.
   */
  readonly attribute boolean isEnabled;

  /**
   * Getter for a list of all cookie banner rules. This includes both opt-in and opt-out rules.
   */
  readonly attribute Array<nsICookieBannerRule> rules;

  /**
   * Clears all imported rules. They will be imported again on startup and when
   * enabling the service. This is currently only used for testing.
   *
   * doImport - Whether to import initial rule list after reset. Passing false
   * will result in an empty rule list.
   */
  void resetRules([optional] in boolean doImport);

  /**
   * Look up all cookie rules for a given top-level URI. Depending on the MODE_
   * this will return none, only reject rules or accept rules if there is no
   * reject rule available.
   */
  Array<nsICookieRule> getCookiesForURI(in nsIURI aURI, in bool aIsPrivateBrowsing);

  /**
   * Look up the click rules for a given domain.
   */
  Array<nsIClickRule> getClickRulesForDomain(in ACString aDomain,
                                             in bool aIsTopLevel);

  /**
   * Insert a cookie banner rule for a domain. If there was previously a rule
   * stored with the same domain it will be overwritten.
   */
  void insertRule(in nsICookieBannerRule aRule);

  /**
   * Remove a cookie banner rule.
   */
  void removeRule(in nsICookieBannerRule aRule);

  /**
   * Computes whether we have a rule for the given browsing context or any of
   * its children. This takes the current cookie banner service mode into
   * consideration and whether the BC is in private browsing mode.
   *
   * This method only takes the global service mode into account. It will ignore
   * any per-site mode overrides. It is meant for callers to find out whether an
   * applicable rule exists, even if users have disabled the feature for the
   * given site.
   */
  boolean hasRuleForBrowsingContextTree(in BrowsingContext aBrowsingContext);

  /**
   * Get the domain preference of the given top-level URI. It will return the
   * service mode if there is a site preference for the given URI. Otherwise, it
   * will return MODE_UNSET.
   */
  nsICookieBannerService_Modes getDomainPref(in nsIURI aTopLevelURI,
                                             in boolean aIsPrivate);

  /**
   * Set the domain preference of the given top-level URI.
   */
  void setDomainPref(in nsIURI aTopLevelURI,
                     in nsICookieBannerService_Modes aMode,
                     in boolean aIsPrivate);

  /**
   * Set the domain preference of the given top-level URI. It will persist the
   * domain preference for private browsing.
   *
   * WARNING: setting permanent domain preference _will_ leak data in private
   * browsing. Only use if you understand the consequences and trade-offs. If
   * you are unsure, |setDomainPref| is very likely what you want to use
   * instead.
   */
  void setDomainPrefAndPersistInPrivateBrowsing(in nsIURI aTopLevelURI,
                                                in nsICookieBannerService_Modes aMode);

  /**
   * Remove the domain preference of the given top-level URI.
   */
  void removeDomainPref(in nsIURI aTopLevelURI, in boolean aIsPrivate);

  /**
   * Remove all domain preferences.
   */
  void removeAllDomainPrefs(in boolean aIsPrivate);

  /**
   * Return true if we should stop cookie banner clicking for the given site in
   * this session.
   */
  boolean shouldStopBannerClickingForSite(in ACString aSite,
                                          in bool aIsTopLevel,
                                          in bool aIsPrivate);

  /**
   * Mark that the cookie banner handling code was executed for the given site
   * for this session.
   */
  void markSiteExecuted(in ACString aSite,
                        in bool aIsTopLevel,
                        in bool aIsPrivate);

  /*
   * Remove the executed record for a given site under the private browsing
   * session or the normal session.
   */
  void removeExecutedRecordForSite(in ACString aSite, in bool aIsPrivate);

  /**
   * Remove all the record of sites where cookie banner handling has been
   * executed under the private browsing session or normal session.
   */
  void removeAllExecutedRecords(in bool aIsPrivate);

  /**
   * Clears the in-memory set that we use to maintain the domains that we have
   * reported telemetry. This function will clear the entry for the given
   * domain. If the domain was not given, it will clear all set.
   */
  void resetDomainTelemetryRecord([optional] in ACString aDomain);
};