DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (777e60ca8853)

VCS Links

Line Code
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 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
/* 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"

%{C++
#include "Entries.h"
#include "LookupCache.h"
class nsUrlClassifierLookupResult;
%}
[ptr] native ResultArray(nsTArray<mozilla::safebrowsing::LookupResult>);
[ptr] native CacheCompletionArray(nsTArray<mozilla::safebrowsing::CacheResult>);
[ptr] native PrefixArray(mozilla::safebrowsing::PrefixArray);

interface nsIUrlClassifierHashCompleter;
interface nsIPrincipal;

// Interface for JS function callbacks
[scriptable, function, uuid(4ca27b6b-a674-4b3d-ab30-d21e2da2dffb)]
interface nsIUrlClassifierCallback : nsISupports {
  void handleEvent(in ACString value);
};

/**
 * The nsIUrlClassifierUpdateObserver interface is implemented by
 * clients streaming updates to the url-classifier (usually
 * nsUrlClassifierStreamUpdater.
 */
[scriptable, uuid(9fa11561-5816-4e1b-bcc9-b629ca05cce6)]
interface nsIUrlClassifierUpdateObserver : nsISupports {
  /**
   * The update requested a new URL whose contents should be downloaded
   * and sent to the classifier as a new stream.
   *
   * @param url The url that was requested.
   * @param table The table name that this URL's contents will be associated
   *              with.  This should be passed back to beginStream().
   */
  void updateUrlRequested(in ACString url,
                          in ACString table);

  /**
   * A stream update has completed.
   *
   * @param status The state of the update process.
   * @param delay The amount of time the updater should wait to fetch the
   *              next URL in ms.
   */
  void streamFinished(in nsresult status, in unsigned long delay);

  /* The update has encountered an error and should be cancelled */
  void updateError(in nsresult error);

  /**
   * The update has completed successfully.
   *
   * @param requestedTimeout The number of seconds that the caller should
   *                         wait before trying to update again.
   **/
  void updateSuccess(in unsigned long requestedTimeout);
};

/**
 * This is a proxy class that is instantiated and called from the JS thread.
 * It provides async methods for querying and updating the database.  As the
 * methods complete, they call the callback function.
 */
[scriptable, uuid(3f9e61e5-01bd-45d0-8dd2-f1abcd20dbb7)]
interface nsIUrlClassifierDBService : nsISupports
{
  /**
   * Looks up a URI in the specified tables.
   *
   * @param principal: The principal containing the URI to search.
   * @param c: The callback will be called with a comma-separated list
   *        of tables to which the key belongs.
   */
  void lookup(in nsIPrincipal principal,
              in ACString tables,
              in nsIUrlClassifierCallback c);

  /**
   * Lists the tables along with which chunks are available in each table.
   * This list is in the format of the request body:
   *   tablename;chunkdata\n
   *   tablename2;chunkdata2\n
   *
   * For example:
   *   goog-phish-regexp;a:10,14,30-40s:56,67
   *   goog-white-regexp;a:1-3,5
   */
  void getTables(in nsIUrlClassifierCallback c);

  /**
   * Set the nsIUrlClassifierCompleter object for a given table.  This
   * object will be used to request complete versions of partial
   * hashes.
   */
  void setHashCompleter(in ACString tableName,
                        in nsIUrlClassifierHashCompleter completer);

  ////////////////////////////////////////////////////////////////////////////
  // Incremental update methods.
  //
  // An update to the database has the following steps:
  //
  // 1) The update process is started with beginUpdate().  The client
  //    passes an nsIUrlClassifierUpdateObserver object which will be
  //    notified as the update is processed by the dbservice.
  // 2) The client sends an initial update stream to the dbservice,
  //    using beginStream/updateStream/finishStream.
  // 3) While reading this initial update stream, the dbservice may
  //    request additional streams from the client as requested by the
  //    update stream.
  // 4) For each additional update stream, the client feeds the
  //    contents to the dbservice using beginStream/updateStream/endStream.
  // 5) Once all streams have been processed, the client calls
  //    finishUpdate.  When the dbservice has finished processing
  //    all streams, it will notify the observer that the update process
  //    is complete.

  /**
   * Begin an update process.  Will throw NS_ERROR_NOT_AVAILABLE if there
   * is already an update in progress.
   *
   * @param updater The update observer tied to this update.
   * @param tables A comma-separated list of tables included in this update.
   */
  void beginUpdate(in nsIUrlClassifierUpdateObserver updater,
                   in ACString tables);

  /**
   * Begin a stream update.  This should be called once per url being
   * fetched.
   *
   * @param table The table the contents of this stream will be associated
   *              with, or empty for the initial stream.
   */
  void beginStream(in ACString table);

  /**
   * Update the table incrementally.
   */
  void updateStream(in ACString updateChunk);

  // It would be nice to have an updateFromStream method to round out the
  // interface, but it's tricky because of XPCOM proxies.

  /**
   * Finish an individual stream update.  Must be called for every
   * beginStream() call, before the next beginStream() or finishUpdate().
   *
   * The update observer's streamFinished will be called once the
   * stream has been processed.
   */
  void finishStream();

  /**
   * Finish an incremental update.  This will attempt to commit any
   * pending changes and resets the update interface.
   *
   * The update observer's updateSucceeded or updateError methods
   * will be called when the update has been processed.
   */
  void finishUpdate();

  /**
   * Cancel an incremental update.  This rolls back any pending changes.
   * and resets the update interface.
   *
   * The update observer's updateError method will be called when the
   * update has been rolled back.
   */
  void cancelUpdate();

  /**
   * Reset the url-classifier database.  This call will delete the existing
   * database, emptying all tables.  Mostly intended for use in unit tests.
   */
  void resetDatabase();
};

/**
 * Interface for the actual worker thread.  Implementations of this need not
 * be thread aware and just work on the database.
 */
[scriptable, uuid(abcd7978-c304-4a7d-a44c-33c2ed5441e7)]
interface nsIUrlClassifierDBServiceWorker : nsIUrlClassifierDBService
{
  // Provide a way to forcibly close the db connection.
  void closeDb();

  [noscript]void cacheCompletions(in CacheCompletionArray completions);
  [noscript]void cacheMisses(in PrefixArray misses);
};

/**
 * This is an internal helper interface for communication between the
 * main thread and the dbservice worker thread.  It is called for each
 * lookup to provide a set of possible results, which the main thread
 * may need to expand using an nsIUrlClassifierCompleter.
 */
[uuid(b903dc8f-dff1-42fe-894b-36e7a59bb801)]
interface nsIUrlClassifierLookupCallback : nsISupports
{
  /**
   * The lookup process is complete.
   *
   * @param results
   *        If this parameter is null, there were no results found.
   *        If not, it contains an array of nsUrlClassifierEntry objects
   *        with possible matches.  The callee is responsible for freeing
   *        this array.
   */
  void lookupComplete(in ResultArray results);
};