/* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is Url Classifier code * * The Initial Developer of the Original Code is * Google Inc. * Portions created by the Initial Developer are Copyright (C) 2006 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Tony Chang (original author) * Brett Wilson * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" %{C++ #include "nsTArray.h" class nsUrlClassifierLookupResult; %} [ptr] native ResultArray(nsTArray); interface nsIUrlClassifierHashCompleter; // 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(bb0528b3-71e2-4795-8732-d60a4476e6df)] 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. */ void updateUrlRequested(in ACString url, in ACString table); /** * A stream update has completed. * * @param status The state of the update process. */ void streamFinished(in nsresult status); /* 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(bcc32b18-78be-49f6-a895-a1a341a9e94b)] interface nsIUrlClassifierDBService : nsISupports { /** * Looks up a key in the database. * * @param key: The URL to search for. This URL will be canonicalized * by the service. * @param c: The callback will be called with a comma-separated list * of tables to which the key belongs. */ void lookup(in ACString spec, 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. */ void beginUpdate(in nsIUrlClassifierUpdateObserver updater); /** * 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(76d923e5-bbde-4292-ae35-16a67d04d524)] interface nsIUrlClassifierDBServiceWorker : nsIUrlClassifierDBService { // Provide a way to forcibly close the db connection. void closeDb(); // Cache the results of a hash completion. [noscript]void cacheCompletions(in ResultArray entries); }; /** * 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(f1dc83c6-ad43-4f0f-a809-fd43de7de8a4)] 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); };