gecko/dom/plugins/base/nsIPluginHost.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.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 mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#include "nspluginroot.idl"
#include "nsISupports.idl"
#include "nsIPluginInstanceOwner.idl"
#include "nsIStreamListener.idl"
#include "nsIStringStream.idl"
#include "nsIPluginTag.idl"
#include "nsIFile.idl"

%{C++
#include "nsPluginNativeWindow.h"
#ifdef MOZILLA_INTERNAL_API
#include "nsString.h"
#include "nsNetUtil.h"
#endif
#include "prlink.h"  // for PRLibrary

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

interface nsIPlugin;
interface nsIURI;
interface nsIDOMPlugin;
interface nsIChannel;
interface nsIPluginStreamListener;

[ptr] native PRLibraryPtr(PRLibrary);
[ptr] native nsPluginNativeWindowPtr(nsPluginNativeWindow);

[scriptable, uuid(0BB66261-4114-4D73-8DFC-C3CA997E6817)]
interface nsIPluginHost : nsISupports
{
  [noscript] void init();

  [noscript] void destroy();

  [noscript] void loadPlugins();

  /**
   * Causes the plugins directory to be searched again for new plugin 
   * libraries.
   *
   * @param reloadPages - indicates whether currently visible pages should 
   * also be reloaded
   */
  void reloadPlugins(in boolean reloadPages);

  [noscript] nsIPlugin getPlugin(in string aMimeType);

  /**
   * Instantiate an embedded plugin for an existing channel. The caller is
   * responsible for opening the channel. It may or may not be already opened
   * when this function is called.
   */
  [noscript] nsIStreamListener instantiatePluginForChannel(in nsIChannel aChannel, in nsIPluginInstanceOwner aOwner);

  [noscript] void setUpPluginInstance(in string aMimeType, in nsIURI aURL, in nsIPluginInstanceOwner aOwner);

  // The return code is NS_OK if the plugin is enabled,
  // NS_ERROR_PLUGIN_DISABLED if the plugin is explicitly disabled, and
  // NS_ERROR_FAILURE if there is no plugin for this type.
  [noscript] void isPluginEnabledForType(in string aMimeType);

  // The return code is NS_OK if the plugin is enabled and NS_ERROR_FAILURE if
  // the plugin is explicitly disabled or there is no plugin.
  [noscript] void isPluginEnabledForExtension(in string aExtension, in constCharStarRef aMimeType);

  [noscript] readonly attribute unsigned long pluginCount;
  
  [noscript] void getPlugins(in unsigned long aPluginCount, out /*array*/ nsIDOMPlugin aPluginArray);

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

  [noscript] void stopPluginInstance(in nsIPluginInstance aInstance);

  [noscript] void handleBadPlugin(in PRLibraryPtr aLibrary, in nsIPluginInstance instance);
  
  /**
   * Fetches a URL.
   *
   * (Corresponds to NPN_GetURL and NPN_GetURLNotify.)
   *
   * @param pluginInst - the plugin making the request. If NULL, the URL
   *  is fetched in the background.
   * @param url - the URL to fetch
   * @param target - the target window into which to load the URL, or NULL if
   *  the data should be returned to the plugin via streamListener.
   * @param streamListener - a stream listener to be used to return data to
   *  the plugin. May be NULL if target is not NULL.
   * @param altHost - an IP-address string that will be used instead of the 
   *  host specified in the URL. This is used to prevent DNS-spoofing 
   *  attacks. Can be defaulted to NULL meaning use the host in the URL.
   * @param referrer - the referring URL (may be NULL)
   * @param forceJSEnabled - forces JavaScript to be enabled for 'javascript:'
   *  URLs, even if the user currently has JavaScript disabled (usually 
   *  specify PR_FALSE) 
   * @result - NS_OK if this operation was successful
   */
  [noscript] void getURL(in nsISupports pluginInt,
                         in string url,
                         in string target,
                         in nsIPluginStreamListener streamListener,
                         in string altHost,
                         in string referrer,
                         in boolean forceJSEnabled);

  /**
   * Posts to a URL with post data and/or post headers.
   *
   * (Corresponds to NPN_PostURL and NPN_PostURLNotify.)
   *
   * @param pluginInst - the plugin making the request. If NULL, the URL
   *  is fetched in the background.
   * @param url - the URL to fetch
   * @param postDataLength - the length of postData (if non-NULL)
   * @param postData - the data to POST. NULL specifies that there is not post
   *  data
   * @param isFile - whether the postData specifies the name of a file to 
   *  post instead of data. The file will be deleted afterwards.
   * @param target - the target window into which to load the URL, or NULL if
   *  the data should be returned to the plugin via streamListener.
   * @param streamListener - a stream listener to be used to return data to
   *  the plugin. May be NULL if target is not NULL.
   * @param altHost - an IP-address string that will be used instead of the 
   *  host specified in the URL. This is used to prevent DNS-spoofing 
   *  attacks. Can be defaulted to NULL meaning use the host in the URL.
   * @param referrer - the referring URL (may be NULL)
   * @param forceJSEnabled - forces JavaScript to be enabled for 'javascript:'
   *  URLs, even if the user currently has JavaScript disabled (usually 
   *  specify PR_FALSE) 
   * @param postHeadersLength - the length of postHeaders (if non-NULL)
   * @param postHeaders - the headers to POST. Must be in the form of
   * "HeaderName: HeaderValue\r\n".  Each header, including the last,
   * must be followed by "\r\n".  NULL specifies that there are no
   * post headers
   * @result - NS_OK if this operation was successful
   */
  [noscript] void postURL(in nsISupports pluginInst,
                          in string url,
                          in PRUint32 postDataLen,
                          in string postData,
                          in boolean isFile,
                          in string target,
                          in nsIPluginStreamListener streamListener,
                          in string altHost,
                          in string referrer,
                          in boolean forceJSEnabled,
                          in PRUint32 postHeadersLength,
                          in string postHeaders);

  /**
   * Returns the proxy info for a given URL. The caller is required to
   * free the resulting memory with nsIMalloc::Free. The result will be in the
   * following format
   * 
   *   i)   "DIRECT"  -- no proxy
   *   ii)  "PROXY xxx.xxx.xxx.xxx"   -- use proxy
   *   iii) "SOCKS xxx.xxx.xxx.xxx"  -- use SOCKS
   *   iv)  Mixed. e.g. "PROXY 111.111.111.111;PROXY 112.112.112.112",
   *                    "PROXY 111.111.111.111;SOCKS 112.112.112.112"....
   *
   * Which proxy/SOCKS to use is determined by the plugin.
   */
  [noscript] void findProxyForURL(in string aURL, out string aResult);

  [noscript] void UserAgent(in nativeChar resultingAgentString);

  /**
   * This method parses post buffer to find out case insensitive "Content-length" string
   * and CR or LF some where after that, then it assumes there is http headers in
   * the input buffer and continue to search for end of headers (CRLFCRLF or LFLF).
   * It will *always malloc()* output buffer (caller is responsible to free it) 
   * if input buffer starts with LF, which comes from 4.x spec 
   * http://developer.netscape.com/docs/manuals/communicator/plugin/pgfn2.htm#1007754
   * "If no custom headers are required, simply add a blank
   * line ('\n') to the beginning of the file or buffer.",
   * it skips that '\n' and considers rest of the input buffer as data.
   * If "Content-length" string and end of headers is found 
   *   it substitutes single LF with CRLF in the headers, so the end of headers
   *   always will be CRLFCRLF (single CR in headers, if any, remain untouched)
   * else
   *   it puts "Content-length: "+size_of_data+CRLFCRLF at the beginning of the output buffer
   * and memcpy data to the output buffer 
   *
   * On failure outPostData and outPostDataLen will be set in 0.  
   * @param aInPostData      - the post data
   * @param aInPostDataLen   - the length aInPostData
   * @param aOutPostData     - the buffer
   * @param aOutPostDataLen  - the length of aOutPostData
   */
  [noscript] void parsePostBufferToFixHeaders(in string aInPostData, 
                                              in unsigned long aInPostDataLen, 
                                              out string aOutPostData, 
                                              out unsigned long aOutPostDataLen);

  /**
   * To create temp file with Content len header in, it will use by http POST
   */
  [noscript] nsIFile createTempFileToPost(in string aPostDataURL);

  /**
   *  Creates a new plugin native window object
   */
  [noscript] void newPluginNativeWindow(out nsPluginNativeWindowPtr aPluginNativeWindow);

  /**
   *  Deletes plugin native window object created by NewPluginNativeWindow
   */
  [noscript] void deletePluginNativeWindow(in nsPluginNativeWindowPtr aPluginNativeWindow);

  /**
   * Instantiate a "dummy" java plugin if a java plugin that supports
   * NPRuntime is installed. This plugin is used for exposing
   * window.java and window.Packages. If the java plugin supports
   * NPRuntime and instantiation was successful, aOwners instance will
   * be non-null, if not, it will be null.
   */
  [noscript] void instantiateDummyJavaPlugin(in nsIPluginInstanceOwner aOwner);

  /**
   * Get the plugin name for the plugin instance.
   * @param aInstance the plugin instance object
   * @param aPluginName returns a pointer to a shared readonly string value,
   *        it's only valid for the lifetime of the plugin instance - you must
   *        copy the string value if you need it longer than that.
   */
  [noscript] void getPluginName(in nsIPluginInstance aInstance, [shared] out string aPluginName);

  /**
   * Get the plugin tag associated with a given plugin instance.
   * @param aInstance the plugin instance object
   * @return plugin tag object
   */
  [noscript] nsIPluginTag getPluginTagForInstance(in nsIPluginInstance aInstance);
  
  [noscript, notxpcom] void addIdleTimeTarget(in nsIPluginInstanceOwner objectFrame, in boolean isVisible);
  [noscript, notxpcom] void removeIdleTimeTarget(in nsIPluginInstanceOwner objectFrame);

  /*
   * 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 PRUint32 FLAG_CLEAR_ALL = 0;
  const PRUint32 FLAG_CLEAR_CACHE = 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 PRUint64 flags, in PRInt64 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);
};