IAutoProxy.idl

/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.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 Adblock Plus.
 *
 * The Initial Developer of the Original Code is
 * Wladimir Palant.
 * Portions created by the Initial Developer are Copyright (C) 2006-2008
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * ***** END LICENSE BLOCK ***** */

#include "nsISupports.idl"

[scriptable, uuid(62B7B3B8-028D-11DE-BC3C-3E8D56D89593)]
interface IAutoProxySubscription: nsISupports
{
  /**
   * Subscription identifier, this is its URL unless the attribute external is set
   */
  readonly attribute AString url;

  /**
   * true for special "subscriptions" representing segments of the user patterns
   * list (e.g. ~wl~ contains whitelisting patterns)
   */
  readonly attribute boolean special;

  /**
   * Subscription's title
   */
  readonly attribute AUTF8String title;

  /**
   * Defines whether the subscription is downloaded automatically
   */
  readonly attribute boolean autoDownload;

  /**
   * Defines whether the subscription's patterns are disabled
   */
  readonly attribute boolean disabled;

  /**
   * Defines whether the subscription is managed externally rather than
   * downloaded by the built-in synchronizer
   */
  readonly attribute boolean external;

  /**
   * Time of the last download attempt in seconds since 1 January 1970 00:00:00
   */
  readonly attribute unsigned long lastDownload;

  /**
   * Code for the result of the last download attempt (one of "synchronize_ok",
   * "synchronize_invalid_url", "synchronize_connection_error", "synchronize_invalid_data")
   */
  readonly attribute AString downloadStatus;

  /**
   * Value of the Last-Modified header for the last download
   */
  readonly attribute AString lastModified;

  /**
   * Expiration time of the subscription (value of the Expires header but no more than two weeks
   * after the download) for the last download in seconds since 1 January 1970 00:00:00
   */
  readonly attribute unsigned long expires;

  /**
   * Retrieves a list of subscription's patterns
   */
  void getPatterns(out unsigned long length,
                   [retval, array, size_is(length)] out wstring patterns);
};

[scriptable, uuid(70EAF9EA-028D-11DE-B53C-A18D56D89593)]
interface IAutoProxy : nsISupports
{
  /**
   * Number of subscriptions in the list
   */
  readonly attribute PRInt32 subscriptionCount;

  /**
   * Retrieves a subscription by its identifier.
   *
   * @param id        subscription identifier
   */
  IAutoProxySubscription getSubscription(in AString id);

  /**
   * Retrieves a subscription by its position in the list.
   *
   * @param index     index of the subscription in the list
   */
  IAutoProxySubscription getSubscriptionAt(in PRInt32 index);

  /**
   * Adds an external subscription or updates subscription's patterns if it
   * already exists. It will fail to update the subscription if it exists
   * but doesn't have the external attribute set.
   *
   * @param id        subscription identifier
   * @param title     subscription title
   * @param patterns  array containing subscription's patterns
   * @param length    length of patterns array
   * @return          true if the subscription was updated or false if the
   *                  update failed
   */
  boolean updateExternalSubscription(in AString id, in AUTF8String title,
                                     [array, size_is(length), const] in wstring patterns,
                                     in unsigned long length);

  /**
   * Removes an external subscription.
   *
   * @param id        subscription identifier
   * @return          true if the subscription was removed or false if no
   *                  external subscription with the given identifier was found
   */
  boolean removeExternalSubscription(in AString id);

  /**
   * Adds user-defined patterns to the filter list.
   *
   * @param patterns  array of patterns to be added
   * @param length    length of the patterns array
   */
  void addPatterns([array, size_is(length)] in wstring patterns, in unsigned long length);

  /**
   * Removes user-defined patterns from the filter list.
   *
   * @param patterns  array of patterns to be removed
   * @param length    length of the patterns array
   */
  void removePatterns([array, size_is(length)] in wstring patterns, in unsigned long length);

  /**
   * Returns the installed version of AutoProxy.
   */
  AString getInstalledVersion();

  /**
   * Returns source code revision this Adblock Plus build was created from (if available)
   */
  AString getInstalledBuild();
};