gecko-dev/toolkit/components/url-classifier/nsIUrlClassifierUtils.idl

/* 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"
/**
 * Some utility methods used by the url classifier.
 */

interface nsIURI;

/**
 * Interface for parseFindFullHashResponseV4 callback
 *
 * @param aCompleteHash A 32-byte complete hash string.
 * @param aTableNames The table names that this complete hash is associated with.
 *                    Since the server responded with a threat type, multiple
 *                    list names can be returned. The caller is reponsible
 *                    for filtering out the unrequested table names.
 *                    See |convertThreatTypeToListNames| for the format.
 * @param aMinWaitDuration See "FindFullHashesResponse" in safebrowsing.proto.
 * @param aNegCacheDuration See "FindFullHashesResponse" in safebrowsing.proto.
 * @param aPerHashCacheDuration See "FindFullHashesResponse" in safebrowsing.proto.
 *
 */
[scriptable, function, uuid(fbb9684a-a0aa-11e6-88b0-08606e456b8a)]
interface nsIUrlClassifierParseFindFullHashCallback : nsISupports {
  void onCompleteHashFound(in ACString aCompleteHash,
                           in ACString aTableNames,
                           in unsigned long aMinWaitDuration,
                           in unsigned long aNegCacheDuration,
                           in unsigned long aPerHashCacheDuration);
};

[scriptable, uuid(e4f0e59c-b922-48b0-a7b6-1735c1f96fed)]
interface nsIUrlClassifierUtils : nsISupports
{
  /**
   * Get the lookup string for a given URI.  This normalizes the hostname,
   * url-decodes the string, and strips off the protocol.
   *
   * @param uri URI to get the lookup key for.
   *
   * @returns String containing the canonicalized URI.
   */
  ACString getKeyForURI(in nsIURI uri);

  /**
   * Get the provider by table name.
   *
   * @param tableName The table name that we want to lookup
   *
   * @returns the provider name that the given table belongs.
   */
  ACString getProvider(in ACString tableName);

  /**
   * Get the provider used for Telemetry.
   * Because recording Telemetry will leak user-controlled strings,
   * only built-in providers should be recorded.
   *
   * @param tableName The table name that we want to lookup
   *
   * @returns the filtered provider for telemetry.
   *
   */
  ACString getTelemetryProvider(in ACString tableName);

  /**
   * Get the protocol version for the given provider.
   *
   * @param provider String the provider name. e.g. "google"
   *
   * @returns String to indicate the protocol version. e.g. "2.2"
   */
  ACString getProtocolVersion(in ACString provider);

  /**
   * Convert threat type to list name.
   *
   * @param Integer to indicate threat type.
   *
   * @returns The list names separated by ','. For example,
   *          'goog-phish-proto,test-phish-proto'.
   */
  ACString convertThreatTypeToListNames(in uint32_t threatType);

  /**
   * Convert list name to threat type.
   *
   * @param The list name.
   *
   * @returns The threat type in integer.
   */
  uint32_t convertListNameToThreatType(in ACString listName);

  /**
   * Make update request for given lists and their states.
   *
   * @param aListNames An array of list name represented in string.
   * @param aState An array of states (encoded in base64 format) for each list.
   * @param aCount The array length of aList and aState.
   *
   * @returns A base64url encoded string.
   */
  ACString makeUpdateRequestV4([array, size_is(aCount)] in string aListNames,
                               [array, size_is(aCount)] in string aStatesBase64,
                               in uint32_t aCount);

    /**
   * Make "find full hash" request by for the given prefixes.
   *
   * @param aListNames An array of list names represented in string.
   * @param aListStatesBase64 An array of list states represented in base64.
   * @param aPrefixes An array of prefixes for which we'd like to find full hashes..
   * @param aListCount The array length of aListNames
   * @param aPrefixCount The array length of aPrefixes
   *
   * @returns A base64url encoded string.
   */
  ACString makeFindFullHashRequestV4([array, size_is(aListCount)] in string aListNames,
                                     [array, size_is(aListCount)] in string aListStatesBase64,
                                     [array, size_is(aPrefixCount)] in string aPrefixes,
                                     in uint32_t aListCount,
                                     in uint32_t aPrefixCount);

  /**
   * Parse V4 FindFullHash response.
   *
   * @param aResponse Byte stream from the server.
   * @param aCallback The callback function on each complete hash parsed.
   *                  Can be called multiple times in one parsing.
   */
  void parseFindFullHashResponseV4(in ACString aResponse,
                                   in nsIUrlClassifierParseFindFullHashCallback aCallback);
};