gecko-dev/dom/plugins/base/nsIPluginHost.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* 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 "nspluginroot.idl"
#include "nsISupports.idl"
#include "nsIPluginTag.idl"

%{C++
#define MOZ_PLUGIN_HOST_CONTRACTID \
  "@mozilla.org/plugin/host;1"
%}

[scriptable, function, uuid(9c311778-7c2c-4ad8-b439-b8a2786a20dd)]
interface nsIClearSiteDataCallback : nsISupports
{
    /**
     * callback with the result from a call to clearSiteData
     */
    void callback(in nsresult rv);
};

[scriptable, uuid(f938f5ba-7093-42cd-a559-af8039d99204)]
interface nsIPluginHost : nsISupports
{
  /**
   * Causes the plugins directory to be searched again for new plugin
   * libraries.
   */
  void reloadPlugins();

  Array<nsIPluginTag> getPluginTags();

  /*
   * Flags for use with clearSiteData.
   *
   * FLAG_CLEAR_ALL: clear all data associated with a site.
   * FLAG_CLEAR_CACHE: clear cached data that can be retrieved again without
   *                   loss of functionality. To be used out of concern for
   *                   space and not necessarily privacy.
   */
  const uint32_t FLAG_CLEAR_ALL = 0;
  const uint32_t FLAG_CLEAR_CACHE = 1;

  /*
   * For use with Get*ForType functions
   */
  const uint32_t EXCLUDE_NONE     = 0;
  const uint32_t EXCLUDE_DISABLED = 1 << 0;
  const uint32_t EXCLUDE_FAKE     = 1 << 1;

  /*
   * Clear site data for a given plugin.
   *
   * @param plugin: the plugin to clear data for, such as one returned by
   *                nsIPluginHost.getPluginTags.
   * @param domain: the domain to clear data for. If this argument is null,
   *                clear data for all domains. Otherwise, it must be a domain
   *                only (not a complete URI or IRI). The base domain for the
   *                given site will be determined; any data for the base domain
   *                or its subdomains will be cleared.
   * @param flags: a flag value defined above.
   * @param maxAge: the maximum age in seconds of data to clear, inclusive. If
   *                maxAge is 0, no data is cleared; if it is -1, all data is
   *                cleared.
   *
   * @throws NS_ERROR_INVALID_ARG if the domain argument is malformed.
   * @throws NS_ERROR_PLUGIN_TIME_RANGE_NOT_SUPPORTED if maxAge is a value other
   *         than -1 and the plugin does not support clearing by timerange in
   *         general or for that particular site and/or flag combination.
   */
  void clearSiteData(in nsIPluginTag plugin, in AUTF8String domain,
                     in uint64_t flags, in int64_t maxAge,
                     in nsIClearSiteDataCallback callback);

  /*
   * Determine if a plugin has stored data for a given site.
   *
   * @param plugin: the plugin to query, such as one returned by
   *                nsIPluginHost.getPluginTags.
   * @param domain: the domain to test. If this argument is null, test if data
   *                is stored for any site. The base domain for the given domain
   *                will be determined; if any data for the base domain or its
   *                subdomains is found, return true.
   */
  boolean siteHasData(in nsIPluginTag plugin, in AUTF8String domain);

  /**
   * Get the "permission string" for the plugin.  This is a string that can be
   * passed to the permission manager to see whether the plugin is allowed to
   * run, for example.  This will typically be based on the plugin's "nice name"
   * and its blocklist state.
   *
   * @mimeType The MIME type we're interested in.
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   */
  ACString getPermissionStringForType(in AUTF8String mimeType,
                                      [optional] in uint32_t excludeFlags);

  /**
   * Get the "permission string" for the plugin.  This is a string that can be
   * passed to the permission manager to see whether the plugin is allowed to
   * run, for example.  This will typically be based on the plugin's "nice name"
   * and its blocklist state.
   *
   * @tag The tage we're interested in
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   */
  ACString getPermissionStringForTag(in nsIPluginTag tag,
                                     [optional] in uint32_t excludeFlags);

  /**
   * Get the nsIPluginTag for this MIME type. This method works with both
   * enabled and disabled/blocklisted plugins, but an enabled plugin will
   * always be returned if available.
   *
   * A fake plugin tag, if one exists and is available, will be returned in
   * preference to NPAPI plugin tags unless excluded by the excludeFlags.
   *
   * @mimeType The MIME type we're interested in.
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   *
   * @throws NS_ERROR_NOT_AVAILABLE if no plugin is available for this MIME
   *         type.
   */
  nsIPluginTag getPluginTagForType(in AUTF8String mimeType,
                                   [optional] in uint32_t excludeFlags);

  /**
   * Get the nsIPluginTag enabled state for this MIME type.  See
   * nsIPluginTag.enabledState.
   *
   * @mimeType The MIME type we're interested in.
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   */
  unsigned long getStateForType(in AUTF8String mimeType,
                                [optional] in uint32_t excludeFlags);

  /**
   * Get the blocklist state for a MIME type.  See nsIPluginTag.blocklistState.
   *
   * @mimeType The MIME type we're interested in.
   * @excludeFlags Set of the EXCLUDE_* flags above, defaulting to EXCLUDE_NONE.
   */
  uint32_t getBlocklistStateForType(in AUTF8String aMimeType,
                                    [optional] in uint32_t excludeFlags);

  /**
   * Create a fake plugin tag, register it, and return it.  The argument is a
   * FakePluginTagInit dictionary.  See documentation in
   * FakePluginTagInit.webidl for what it should look like.  Will throw
   * NS_ERROR_UNEXPECTED if there is already a fake plugin registered with the
   * given handler URI.
   */
  [implicit_jscontext]
  nsIFakePluginTag registerFakePlugin(in jsval initDictionary);

  /**
   * Create a fake plugin tag without registering it.
   *
   * Only for use in tests.
   */
  [implicit_jscontext]
  nsIFakePluginTag createFakePlugin(in jsval initDictionary);

  /**
   * Get a reference to an existing fake plugin tag for the given MIME type, if
   * any.  Can return null.
   */
  nsIFakePluginTag getFakePlugin(in AUTF8String mimeType);

  /**
   * Unregister a fake plugin.  The argument can be the .handlerURI.spec of an
   * existing nsIFakePluginTag, or just a known handler URI string that was
   * passed in the FakePluginTagInit when registering.
   */
  void unregisterFakePlugin(in AUTF8String handlerURI);
};