1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/url-classifier/nsIUrlClassifierDBService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,217 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +%{C++
1.11 +#include "Entries.h"
1.12 +#include "LookupCache.h"
1.13 +class nsUrlClassifierLookupResult;
1.14 +%}
1.15 +[ptr] native ResultArray(nsTArray<mozilla::safebrowsing::LookupResult>);
1.16 +[ptr] native CacheCompletionArray(nsTArray<mozilla::safebrowsing::CacheResult>);
1.17 +[ptr] native PrefixArray(mozilla::safebrowsing::PrefixArray);
1.18 +
1.19 +interface nsIUrlClassifierHashCompleter;
1.20 +interface nsIPrincipal;
1.21 +
1.22 +// Interface for JS function callbacks
1.23 +[scriptable, function, uuid(4ca27b6b-a674-4b3d-ab30-d21e2da2dffb)]
1.24 +interface nsIUrlClassifierCallback : nsISupports {
1.25 + void handleEvent(in ACString value);
1.26 +};
1.27 +
1.28 +/**
1.29 + * The nsIUrlClassifierUpdateObserver interface is implemented by
1.30 + * clients streaming updates to the url-classifier (usually
1.31 + * nsUrlClassifierStreamUpdater.
1.32 + */
1.33 +[scriptable, uuid(9fa11561-5816-4e1b-bcc9-b629ca05cce6)]
1.34 +interface nsIUrlClassifierUpdateObserver : nsISupports {
1.35 + /**
1.36 + * The update requested a new URL whose contents should be downloaded
1.37 + * and sent to the classifier as a new stream.
1.38 + *
1.39 + * @param url The url that was requested.
1.40 + * @param table The table name that this URL's contents will be associated
1.41 + * with. This should be passed back to beginStream().
1.42 + */
1.43 + void updateUrlRequested(in ACString url,
1.44 + in ACString table);
1.45 +
1.46 + /**
1.47 + * A stream update has completed.
1.48 + *
1.49 + * @param status The state of the update process.
1.50 + * @param delay The amount of time the updater should wait to fetch the
1.51 + * next URL in ms.
1.52 + */
1.53 + void streamFinished(in nsresult status, in unsigned long delay);
1.54 +
1.55 + /* The update has encountered an error and should be cancelled */
1.56 + void updateError(in nsresult error);
1.57 +
1.58 + /**
1.59 + * The update has completed successfully.
1.60 + *
1.61 + * @param requestedTimeout The number of seconds that the caller should
1.62 + * wait before trying to update again.
1.63 + **/
1.64 + void updateSuccess(in unsigned long requestedTimeout);
1.65 +};
1.66 +
1.67 +/**
1.68 + * This is a proxy class that is instantiated and called from the JS thread.
1.69 + * It provides async methods for querying and updating the database. As the
1.70 + * methods complete, they call the callback function.
1.71 + */
1.72 +[scriptable, uuid(3f9e61e5-01bd-45d0-8dd2-f1abcd20dbb7)]
1.73 +interface nsIUrlClassifierDBService : nsISupports
1.74 +{
1.75 + /**
1.76 + * Looks up a URI in the specified tables.
1.77 + *
1.78 + * @param principal: The principal containing the URI to search.
1.79 + * @param c: The callback will be called with a comma-separated list
1.80 + * of tables to which the key belongs.
1.81 + */
1.82 + void lookup(in nsIPrincipal principal,
1.83 + in ACString tables,
1.84 + in nsIUrlClassifierCallback c);
1.85 +
1.86 + /**
1.87 + * Lists the tables along with which chunks are available in each table.
1.88 + * This list is in the format of the request body:
1.89 + * tablename;chunkdata\n
1.90 + * tablename2;chunkdata2\n
1.91 + *
1.92 + * For example:
1.93 + * goog-phish-regexp;a:10,14,30-40s:56,67
1.94 + * goog-white-regexp;a:1-3,5
1.95 + */
1.96 + void getTables(in nsIUrlClassifierCallback c);
1.97 +
1.98 + /**
1.99 + * Set the nsIUrlClassifierCompleter object for a given table. This
1.100 + * object will be used to request complete versions of partial
1.101 + * hashes.
1.102 + */
1.103 + void setHashCompleter(in ACString tableName,
1.104 + in nsIUrlClassifierHashCompleter completer);
1.105 +
1.106 + ////////////////////////////////////////////////////////////////////////////
1.107 + // Incremental update methods.
1.108 + //
1.109 + // An update to the database has the following steps:
1.110 + //
1.111 + // 1) The update process is started with beginUpdate(). The client
1.112 + // passes an nsIUrlClassifierUpdateObserver object which will be
1.113 + // notified as the update is processed by the dbservice.
1.114 + // 2) The client sends an initial update stream to the dbservice,
1.115 + // using beginStream/updateStream/finishStream.
1.116 + // 3) While reading this initial update stream, the dbservice may
1.117 + // request additional streams from the client as requested by the
1.118 + // update stream.
1.119 + // 4) For each additional update stream, the client feeds the
1.120 + // contents to the dbservice using beginStream/updateStream/endStream.
1.121 + // 5) Once all streams have been processed, the client calls
1.122 + // finishUpdate. When the dbservice has finished processing
1.123 + // all streams, it will notify the observer that the update process
1.124 + // is complete.
1.125 +
1.126 + /**
1.127 + * Begin an update process. Will throw NS_ERROR_NOT_AVAILABLE if there
1.128 + * is already an update in progress.
1.129 + *
1.130 + * @param updater The update observer tied to this update.
1.131 + * @param tables A comma-separated list of tables included in this update.
1.132 + */
1.133 + void beginUpdate(in nsIUrlClassifierUpdateObserver updater,
1.134 + in ACString tables);
1.135 +
1.136 + /**
1.137 + * Begin a stream update. This should be called once per url being
1.138 + * fetched.
1.139 + *
1.140 + * @param table The table the contents of this stream will be associated
1.141 + * with, or empty for the initial stream.
1.142 + */
1.143 + void beginStream(in ACString table);
1.144 +
1.145 + /**
1.146 + * Update the table incrementally.
1.147 + */
1.148 + void updateStream(in ACString updateChunk);
1.149 +
1.150 + // It would be nice to have an updateFromStream method to round out the
1.151 + // interface, but it's tricky because of XPCOM proxies.
1.152 +
1.153 + /**
1.154 + * Finish an individual stream update. Must be called for every
1.155 + * beginStream() call, before the next beginStream() or finishUpdate().
1.156 + *
1.157 + * The update observer's streamFinished will be called once the
1.158 + * stream has been processed.
1.159 + */
1.160 + void finishStream();
1.161 +
1.162 + /**
1.163 + * Finish an incremental update. This will attempt to commit any
1.164 + * pending changes and resets the update interface.
1.165 + *
1.166 + * The update observer's updateSucceeded or updateError methods
1.167 + * will be called when the update has been processed.
1.168 + */
1.169 + void finishUpdate();
1.170 +
1.171 + /**
1.172 + * Cancel an incremental update. This rolls back any pending changes.
1.173 + * and resets the update interface.
1.174 + *
1.175 + * The update observer's updateError method will be called when the
1.176 + * update has been rolled back.
1.177 + */
1.178 + void cancelUpdate();
1.179 +
1.180 + /**
1.181 + * Reset the url-classifier database. This call will delete the existing
1.182 + * database, emptying all tables. Mostly intended for use in unit tests.
1.183 + */
1.184 + void resetDatabase();
1.185 +};
1.186 +
1.187 +/**
1.188 + * Interface for the actual worker thread. Implementations of this need not
1.189 + * be thread aware and just work on the database.
1.190 + */
1.191 +[scriptable, uuid(abcd7978-c304-4a7d-a44c-33c2ed5441e7)]
1.192 +interface nsIUrlClassifierDBServiceWorker : nsIUrlClassifierDBService
1.193 +{
1.194 + // Provide a way to forcibly close the db connection.
1.195 + void closeDb();
1.196 +
1.197 + [noscript]void cacheCompletions(in CacheCompletionArray completions);
1.198 + [noscript]void cacheMisses(in PrefixArray misses);
1.199 +};
1.200 +
1.201 +/**
1.202 + * This is an internal helper interface for communication between the
1.203 + * main thread and the dbservice worker thread. It is called for each
1.204 + * lookup to provide a set of possible results, which the main thread
1.205 + * may need to expand using an nsIUrlClassifierCompleter.
1.206 + */
1.207 +[uuid(b903dc8f-dff1-42fe-894b-36e7a59bb801)]
1.208 +interface nsIUrlClassifierLookupCallback : nsISupports
1.209 +{
1.210 + /**
1.211 + * The lookup process is complete.
1.212 + *
1.213 + * @param results
1.214 + * If this parameter is null, there were no results found.
1.215 + * If not, it contains an array of nsUrlClassifierEntry objects
1.216 + * with possible matches. The callee is responsible for freeing
1.217 + * this array.
1.218 + */
1.219 + void lookupComplete(in ResultArray results);
1.220 +};
