diff -r 000000000000 -r 6474c204b198 toolkit/components/url-classifier/nsIUrlClassifierDBService.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/toolkit/components/url-classifier/nsIUrlClassifierDBService.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,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); +[ptr] native CacheCompletionArray(nsTArray); +[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); +};