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, uuid(57069ada-2845-46ef-b57f-233596d1c02c)]
interface nsIPluginPlayPreviewInfo : nsISupports
{
  readonly attribute AUTF8String mimeType;
  readonly attribute boolean     ignoreCTP;
  readonly attribute AUTF8String redirectURL;
  readonly attribute AUTF8String whitelist;

  /**
   * Checks if pageURI and objectURI matches once of the entries in
   * the whitelist. If whitelist is empty, returns true. 
   */
  boolean checkWhitelist(in AUTF8String pageURI, in AUTF8String objectURI);
};

[scriptable, uuid(d7d5b2e0-105b-4c9d-8558-b6b31f28b7df)]
interface nsIPluginHost : nsISupports
{
  /**
   * Causes the plugins directory to be searched again for new plugin 
   * libraries.
   */
  void reloadPlugins();

  void getPluginTags([optional] out unsigned long aPluginCount,
    [retval, array, size_is(aPluginCount)] out nsIPluginTag aResults);

  /*
   * 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;

  /*
   * 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);

  /*
   * 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);

  /**
   * Registers the play preview plugin mode for specific mime type
   *
   * @param mimeType: specifies plugin mime type.
   * @param ignoreCTP: if true, the play preview ignores CTP rules, e.g.
                       whitelisted websites, will not notify about plugin
                       presence in the address bar.
   * @param redirectURL: specifies url for the overlay iframe
   * @param whitelist: specifies plugin whitelist in form of comma separated
   *                   "[@page_url object_url|@page_url|object_url]" entries,
   *                    e.g. @http://example.org/* http://example.org/t.swf
   */
  void registerPlayPreviewMimeType(in AUTF8String mimeType,
                                   [optional] in boolean ignoreCTP,
                                   [optional] in AUTF8String redirectURL,
                                   [optional] in AUTF8String whitelist);

  void unregisterPlayPreviewMimeType(in AUTF8String mimeType);

  nsIPluginPlayPreviewInfo getPlayPreviewInfo(in AUTF8String mimeType);

  /**
   * 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.
   */
  ACString getPermissionStringForType(in AUTF8String mimeType,
                                      [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.
   *
   * @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.
   */
  unsigned long getStateForType(in AUTF8String mimeType,
                                [optional] in uint32_t excludeFlags);

  /**
   * Get the blocklist state for a MIME type.  See nsIPluginTag.blocklistState.
   */
  uint32_t getBlocklistStateForType(in AUTF8String aMimeType,
                                    [optional] in uint32_t excludeFlags);
};