toolkit/components/url-classifier/public/nsIUrlClassifierDBService.idl

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is Url Classifier code
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Google Inc.
  18  * Portions created by the Initial Developer are Copyright (C) 2006
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Tony Chang <tony@ponderer.org> (original author)
  23  *   Brett Wilson <brettw@gmail.com>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsISupports.idl"
  40
  41 %{C++
  42 #include "nsTArray.h"
  43 class nsUrlClassifierLookupResult;
  44 %}
  45 [ptr] native ResultArray(nsTArray<nsUrlClassifierLookupResult>);
  46
  47 interface nsIUrlClassifierHashCompleter;
  48
  49 // Interface for JS function callbacks
  50 [scriptable, function, uuid(4ca27b6b-a674-4b3d-ab30-d21e2da2dffb)]
  51 interface nsIUrlClassifierCallback : nsISupports {
  52   void handleEvent(in ACString value);
  53 };
  54
  55 /**
  56  * The nsIUrlClassifierUpdateObserver interface is implemented by
  57  * clients streaming updates to the url-classifier (usually
  58  * nsUrlClassifierStreamUpdater.
  59  */
  60 [scriptable, uuid(bbb33c65-e783-476c-8db0-6ddb91826c07)]
  61 interface nsIUrlClassifierUpdateObserver : nsISupports {
  62   /**
  63    * The update requested a new URL whose contents should be downloaded
  64    * and sent to the classifier as a new stream.
  65    *
  66    * @param url The url that was requested.
  67    * @param table The table name that this URL's contents will be associated
  68    *              with.  This should be passed back to beginStream().
  69    * @param serverMAC The server-supplied MAC of the data at this URL.  This
  70    *                  should be passed back to beginStream().
  71    */
  72   void updateUrlRequested(in ACString url,
  73                           in ACString table,
  74                           in ACString serverMAC);
  75
  76   /**
  77    * The server has requested that the client get a new client key for
  78    * MAC requests.
  79    */
  80   void rekeyRequested();
  81
  82   /**
  83    * A stream update has completed.
  84    *
  85    * @param status The state of the update process.
  86    * @param delay The amount of time the updater should wait to fetch the
  87    *              next URL in ms.
  88    */
  89   void streamFinished(in nsresult status, in unsigned long delay);
  90
  91   /* The update has encountered an error and should be cancelled */
  92   void updateError(in nsresult error);
  93
  94   /**
  95    * The update has completed successfully.
  96    *
  97    * @param requestedTimeout The number of seconds that the caller should
  98    *                         wait before trying to update again.
  99    **/
 100   void updateSuccess(in unsigned long requestedTimeout);
 101 };
 102
 103 /**
 104  * This is a proxy class that is instantiated and called from the JS thread.
 105  * It provides async methods for querying and updating the database.  As the
 106  * methods complete, they call the callback function.
 107  */
 108 [scriptable, uuid(7aae3f3a-527d-488b-a448-45dca6db0e80)]
 109 interface nsIUrlClassifierDBService : nsISupports
 110 {
 111   /**
 112    * Looks up a key in the database.
 113    *
 114    * @param key: The URL to search for.  This URL will be canonicalized
 115    *        by the service.
 116    * @param c: The callback will be called with a comma-separated list
 117    *        of tables to which the key belongs.
 118    */
 119   void lookup(in ACString spec,
 120               in nsIUrlClassifierCallback c);
 121
 122   /**
 123    * Lists the tables along with which chunks are available in each table.
 124    * This list is in the format of the request body:
 125    *   tablename;chunkdata\n
 126    *   tablename2;chunkdata2\n
 127    *
 128    * For example:
 129    *   goog-phish-regexp;a:10,14,30-40s:56,67
 130    *   goog-white-regexp;a:1-3,5
 131    */
 132   void getTables(in nsIUrlClassifierCallback c);
 133
 134   /**
 135    * Set the nsIUrlClassifierCompleter object for a given table.  This
 136    * object will be used to request complete versions of partial
 137    * hashes.
 138    */
 139   void setHashCompleter(in ACString tableName,
 140                         in nsIUrlClassifierHashCompleter completer);
 141
 142   ////////////////////////////////////////////////////////////////////////////
 143   // Incremental update methods.
 144   //
 145   // An update to the database has the following steps:
 146   //
 147   // 1) The update process is started with beginUpdate().  The client
 148   //    passes an nsIUrlClassifierUpdateObserver object which will be
 149   //    notified as the update is processed by the dbservice.
 150   // 2) The client sends an initial update stream to the dbservice,
 151   //    using beginStream/updateStream/finishStream.
 152   // 3) While reading this initial update stream, the dbservice may
 153   //    request additional streams from the client as requested by the
 154   //    update stream.
 155   // 4) For each additional update stream, the client feeds the
 156   //    contents to the dbservice using beginStream/updateStream/endStream.
 157   // 5) Once all streams have been processed, the client calls
 158   //    finishUpdate.  When the dbservice has finished processing
 159   //    all streams, it will notify the observer that the update process
 160   //    is complete.
 161
 162   /**
 163    * Begin an update process.  Will throw NS_ERROR_NOT_AVAILABLE if there
 164    * is already an update in progress.
 165    *
 166    * @param updater The update observer tied to this update.
 167    * @param tables A comma-separated list of tables included in this update.
 168    * @param clientKey The client key for calculating an update's MAC,
 169    *        or empty to ignore MAC.
 170    */
 171   void beginUpdate(in nsIUrlClassifierUpdateObserver updater,
 172                    in ACString tables,
 173                    in ACString clientKey);
 174
 175   /**
 176    * Begin a stream update.  This should be called once per url being
 177    * fetched.
 178    *
 179    * @param table The table the contents of this stream will be associated
 180    *              with, or empty for the initial stream.
 181    * @param serverMAC The MAC specified by the update server for this stream.
 182    *                  If the server has not specified a MAC (which is the case
 183    *                  for the initial stream), this will be empty.
 184    */
 185   void beginStream(in ACString table,
 186                    in ACString serverMAC);
 187
 188   /**
 189    * Update the table incrementally.
 190    */
 191   void updateStream(in ACString updateChunk);
 192
 193   // It would be nice to have an updateFromStream method to round out the
 194   // interface, but it's tricky because of XPCOM proxies.
 195
 196   /**
 197    * Finish an individual stream update.  Must be called for every
 198    * beginStream() call, before the next beginStream() or finishUpdate().
 199    *
 200    * The update observer's streamFinished will be called once the
 201    * stream has been processed.
 202    */
 203   void finishStream();
 204
 205   /**
 206    * Finish an incremental update.  This will attempt to commit any
 207    * pending changes and resets the update interface.
 208    *
 209    * The update observer's updateSucceeded or updateError methods
 210    * will be called when the update has been processed.
 211    */
 212   void finishUpdate();
 213
 214   /**
 215    * Cancel an incremental update.  This rolls back any pending changes.
 216    * and resets the update interface.
 217    *
 218    * The update observer's updateError method will be called when the
 219    * update has been rolled back.
 220    */
 221   void cancelUpdate();
 222
 223   /**
 224    * Reset the url-classifier database.  This call will delete the existing
 225    * database, emptying all tables.  Mostly intended for use in unit tests.
 226    */
 227   void resetDatabase();
 228 };
 229
 230 /**
 231  * Interface for the actual worker thread.  Implementations of this need not
 232  * be thread aware and just work on the database.
 233  */
 234 [scriptable, uuid(2af84c09-269e-4fc2-b28f-af56717db118)]
 235 interface nsIUrlClassifierDBServiceWorker : nsIUrlClassifierDBService
 236 {
 237   // Provide a way to forcibly close the db connection.
 238   void closeDb();
 239
 240   // Cache the results of a hash completion.
 241   [noscript]void cacheCompletions(in ResultArray entries);
 242 };
 243
 244 /**
 245  * This is an internal helper interface for communication between the
 246  * main thread and the dbservice worker thread.  It is called for each
 247  * lookup to provide a set of possible results, which the main thread
 248  * may need to expand using an nsIUrlClassifierCompleter.
 249  */
 250 [uuid(f1dc83c6-ad43-4f0f-a809-fd43de7de8a4)]
 251 interface nsIUrlClassifierLookupCallback : nsISupports
 252 {
 253   /**
 254    * The lookup process is complete.
 255    *
 256    * @param results
 257    *        If this parameter is null, there were no results found.
 258    *        If not, it contains an array of nsUrlClassifierEntry objects
 259    *        with possible matches.  The callee is responsible for freeing
 260    *        this array.
 261    */
 262   void lookupComplete(in ResultArray results);
 263 };