toolkit/components/antitracking/nsIURLQueryStrippingListService.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 /**
   8  * Observer for query stripping list updates.
   9  */
  10 [scriptable, uuid(ef56ae12-b1bb-43e6-b1d8-16459cb98dfd)]
  11 interface nsIURLQueryStrippingListObserver : nsISupports
  12 {
  13   /**
  14    * Called by nsIQueryStrippingListService when the list of query stripping
  15    * changes and when the observer is first registered. Note that the lists
  16    * could have duplicate entries because we would combine the lists from the
  17    * pref and remote settings.
  18    *
  19    * @param aStripList
  20    *        A space-separated list of query parameters that will be stripped.
  21    * @param aAllowList
  22    *        A comma-separated list of hosts (eTLD+1) that are exempt from query
  23    *        stripping.
  24    */
  25   void onQueryStrippingListUpdate(in AString aStripList, in ACString aAllowList);
  26
  27   /**
  28    * Called by nsIQueryStrippingListService when the list of query stripping
  29    * parameters for strip-on-share feature is updated and when the observer is first registered.
  30    *
  31    * @param aStripRules
  32    *        An Array of stringified strip rules.
  33    *        A stringified rule has the form of:
  34    *        "'queryParams': ['param1', 'param2', ...], 'topLevelSites': ['www.site.com', 'www.site.de', ...]"
  35    */
  36   [implicit_jscontext]
  37   void onStripOnShareUpdate(in Array<AString> aStripRules);
  38 };
  39
  40 /**
  41  * A service that monitors updates to the query stripping list from sources such
  42  * as a local pref and remote settings updates.
  43  */
  44 [scriptable, uuid(afff16f0-3fd2-4153-9ccd-c6d9abd879e4)]
  45 interface nsIURLQueryStrippingListService : nsISupports
  46 {
  47   /**
  48    * Register a new observer to query stripping list updates. When the observer
  49    * is registered it is called immediately once. Afterwards it will be called
  50    * whenever the specified pref changes or when remote settings for
  51    * partitioning updates.
  52    *
  53    * @param aObserver
  54    *        An nsIURLQueryStrippingListObserver object or function that
  55    *        will receive updates to the strip list and the allow list. Will be
  56    *        called immediately with the current list value.
  57    */
  58   void registerAndRunObserver(in nsIURLQueryStrippingListObserver aObserver);
  59
  60
  61   /**
  62    * Register a new observer to strip-on-share stripping list updates
  63    * (this is the strip-on-share list combined with the QPS list).
  64    * When the observer is registered it is called immediately once. Afterwards it will be called
  65    * when there is an remote settings update to the QPS strip list.
  66    *
  67    * @param aObserver
  68    *        An nsIURLQueryStrippingListObserver object or function that
  69    *        will receive updates to the strip list and the allow list. Will be
  70    *        called immediately with the current list value.
  71    */
  72   void registerAndRunObserverStripOnShare(in nsIURLQueryStrippingListObserver aObserver);
  73
  74   /**
  75    * Unregister an observer.
  76    *
  77    * @param aObserver
  78    *        The nsIURLQueryStrippingListObserver object to unregister.
  79    */
  80   void unregisterObserver(in nsIURLQueryStrippingListObserver aObserver);
  81
  82   /**
  83    * Unregister an observer for strip-on-share.
  84    *
  85    * @param aObserver
  86    *        The nsIURLQueryStrippingListObserver object to unregister.
  87    */
  88   void unregisterStripOnShareObserver(in nsIURLQueryStrippingListObserver aObserver);
  89
  90   /**
  91    * Clear all Lists.
  92    *
  93    * Note that this is for testing purpose.
  94    */
  95   void clearLists();
  96
  97   /**
  98    * Test-only method used to wait for the list service to initialize fully.
  99    * Resolves once the service has reached a fully disabled (false) or fully
 100    * enabled state (true).
 101    * May also be called when the service is already fully initialized or
 102    * disabled, in this case it will resolve immediately.
 103    */
 104   Promise testWaitForInit();
 105
 106
 107   /**
 108    * Add new lists with different params
 109    *
 110    * Note that this is for testing purpose.
 111    */
 112   Promise testSetList(in jsval testFile);
 113
 114
 115   /**
 116    * Check if Strip on Share observers are unregistered
 117    *
 118    * Note that this is for testing purpose.
 119    */
 120   boolean testHasStripOnShareObservers();
 121
 122   /**
 123    * Check if QPS observers are unregistered
 124    *
 125    * Note that this is for testing purpose.
 126    */
 127   boolean testHasQPSObservers();
 128 };