modules/plugin/base/public/nsIPluginManager.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 /**
  39  * nsIPluginManager
  40  *
  41  * @status DEPRECATED
  42  *
  43  * Originally published XPCOM Plugin API is now deprecated
  44  * Developers are welcome to use NPAPI, please refer to:
  45  * http://mozilla.org/projects/plugins/
  46  */
  47
  48 #include "nsISupports.idl"
  49 #include "nspluginroot.idl"
  50
  51 %{C++
  52 #include "nsplugindefs.h"
  53 %}
  54
  55 // CLSID for the browser's global plugin manager object.
  56 %{C++
  57 #define NS_PLUGINMANAGER_CID                         \
  58 { /* ce768990-5a4e-11d2-8164-006008119d7a */         \
  59     0xce768990,                                      \
  60     0x5a4e,                                          \
  61     0x11d2,                                          \
  62     {0x81, 0x64, 0x00, 0x60, 0x08, 0x11, 0x9d, 0x7a} \
  63 }
  64 %}
  65
  66 interface nsIPluginStreamListener;
  67
  68 [scriptable, uuid(da58ad80-4eb6-11d2-8164-006008119d7a)]
  69
  70 /*
  71  * The nsIPluginManager interface defines the minimum set of functionality that
  72  * the browser will support if it allows plugins. Plugins can call QueryInterface
  73  * to determine if a plugin manager implements more specific APIs or other
  74  * browser interfaces for the plugin to use (e.g. nsINetworkManager).
  75  */
  76
  77 interface nsIPluginManager : nsISupports
  78 {
  79     /**
  80      * Returns the value of a variable associated with the plugin manager.
  81      *
  82      * (Corresponds to NPN_GetValue.)
  83      *
  84      * @param variable - the plugin manager variable to get
  85      * @param value - the address of where to store the resulting value
  86      * @result - NS_OK if this operation was successful
  87      */
  88    [noscript] void GetValue(in nsPluginManagerVariable variable, in nativeVoid value);
  89
  90     /**
  91      * Causes the plugins directory to be searched again for new plugin
  92      * libraries.
  93      *
  94      * (Corresponds to NPN_ReloadPlugins.)
  95      *
  96      * @param reloadPages - indicates whether currently visible pages should
  97      * also be reloaded
  98      */
  99     void reloadPlugins(in boolean reloadPages);
 100
 101     /**
 102      * Returns the user agent string for the browser.
 103      *
 104      * (Corresponds to NPN_UserAgent.)
 105      *
 106      * @param resultingAgentString - the resulting user agent string
 107      */
 108      [noscript] void UserAgent(in nativeChar resultingAgentString);
 109
 110     /**
 111      * Fetches a URL.
 112      *
 113      * (Corresponds to NPN_GetURL and NPN_GetURLNotify.)
 114      *
 115      * @param pluginInst - the plugin making the request. If NULL, the URL
 116      *   is fetched in the background.
 117      * @param url - the URL to fetch
 118      * @param target - the target window into which to load the URL, or NULL if
 119      *   the data should be returned to the plugin via streamListener.
 120      * @param streamListener - a stream listener to be used to return data to
 121      *   the plugin. May be NULL if target is not NULL.
 122      * @param altHost - an IP-address string that will be used instead of the
 123      *   host specified in the URL. This is used to prevent DNS-spoofing
 124      *   attacks. Can be defaulted to NULL meaning use the host in the URL.
 125      * @param referrer - the referring URL (may be NULL)
 126      * @param forceJSEnabled - forces JavaScript to be enabled for 'javascript:'
 127      *   URLs, even if the user currently has JavaScript disabled (usually
 128      *   specify PR_FALSE)
 129      * @result - NS_OK if this operation was successful
 130      */
 131 %{C++
 132     NS_IMETHOD
 133     GetURL(nsISupports* pluginInst,
 134            const char* url,
 135            const char* target = NULL,
 136            nsIPluginStreamListener* streamListener = NULL,
 137            const char* altHost = NULL,
 138            const char* referrer = NULL,
 139            PRBool forceJSEnabled = PR_FALSE) = 0;
 140 %}
 141
 142     /**
 143      * Posts to a URL with post data and/or post headers.
 144      *
 145      * (Corresponds to NPN_PostURL and NPN_PostURLNotify.)
 146      *
 147      * @param pluginInst - the plugin making the request. If NULL, the URL
 148      *   is fetched in the background.
 149      * @param url - the URL to fetch
 150      * @param postDataLength - the length of postData (if non-NULL)
 151      * @param postData - the data to POST. NULL specifies that there is not post
 152      *   data
 153      * @param isFile - whether the postData specifies the name of a file to
 154      *   post instead of data. The file will be deleted afterwards.
 155      * @param target - the target window into which to load the URL, or NULL if
 156      *   the data should be returned to the plugin via streamListener.
 157      * @param streamListener - a stream listener to be used to return data to
 158      *   the plugin. May be NULL if target is not NULL.
 159      * @param altHost - an IP-address string that will be used instead of the
 160      *   host specified in the URL. This is used to prevent DNS-spoofing
 161      *   attacks. Can be defaulted to NULL meaning use the host in the URL.
 162      * @param referrer - the referring URL (may be NULL)
 163      * @param forceJSEnabled - forces JavaScript to be enabled for 'javascript:'
 164      *   URLs, even if the user currently has JavaScript disabled (usually
 165      *   specify PR_FALSE)
 166      * @param postHeadersLength - the length of postHeaders (if non-NULL)
 167      * @param postHeaders - the headers to POST. Must be in the form of
 168      * "HeaderName: HeaderValue\r\n".  Each header, including the last,
 169      * must be followed by "\r\n".  NULL specifies that there are no
 170      * post headers
 171      * @result - NS_OK if this operation was successful
 172      */
 173 %{C++
 174     NS_IMETHOD
 175     PostURL(nsISupports* pluginInst,
 176             const char* url,
 177             PRUint32 postDataLen,
 178             const char* postData,
 179             PRBool isFile = PR_FALSE,
 180             const char* target = NULL,
 181             nsIPluginStreamListener* streamListener = NULL,
 182             const char* altHost = NULL,
 183             const char* referrer = NULL,
 184             PRBool forceJSEnabled = PR_FALSE,
 185             PRUint32 postHeadersLength = 0,
 186             const char* postHeaders = NULL) = 0;
 187 %}
 188
 189     /**
 190      * Persistently register a plugin with the plugin
 191      * manager. aMimeTypes, aMimeDescriptions, and aFileExtensions are
 192      * parallel arrays that contain information about the MIME types
 193      * that the plugin supports.
 194      *
 195      * @param aCID - the plugin's CID
 196      * @param aPluginName - the plugin's name
 197      * @param aDescription - a description of the plugin
 198      * @param aMimeTypes - an array of MIME types that the plugin
 199      *   is prepared to handle
 200      * @param aMimeDescriptions - an array of descriptions for the
 201      *   MIME types that the plugin can handle.
 202      * @param aFileExtensions - an array of file extensions for
 203      *   the MIME types that the plugin can handle.
 204      * @param aCount - the number of elements in the aMimeTypes,
 205      *   aMimeDescriptions, and aFileExtensions arrays.
 206      * @result - NS_OK if the operation was successful.
 207      */
 208      [noscript] void RegisterPlugin(in REFNSIID    aCID,
 209                                     in string      aPluginName,
 210                                     in string      aDescription,
 211                                     in nativeChar  aMimeTypes,
 212                                     in nativeChar  aMimeDescriptions,
 213                                     in nativeChar  aFileExtensions,
 214                                     in  long       aCount);
 215
 216     /**
 217      * Unregister a plugin from the plugin manager
 218      *
 219      * @param aCID the CID of the plugin to unregister.
 220      * @result - NS_OK if the operation was successful.
 221      */
 222      [noscript] void UnregisterPlugin(in REFNSIID aCID);
 223
 224 %{C++
 225     /**
 226      * Fetches a URL, with Headers
 227      * @see GetURL.  Identical except for additional params headers and
 228      * headersLen
 229      * @param getHeadersLength - the length of getHeaders (if non-NULL)
 230      * @param getHeaders - the headers to GET. Must be in the form of
 231      * "HeaderName: HeaderValue\r\n".  Each header, including the last,
 232      * must be followed by "\r\n".  NULL specifies that there are no
 233      * get headers
 234      * @result - NS_OK if this operation was successful
 235      */
 236     NS_IMETHOD
 237     GetURLWithHeaders(nsISupports* pluginInst,
 238                       const char* url,
 239                       const char* target = NULL,
 240                       nsIPluginStreamListener* streamListener = NULL,
 241                       const char* altHost = NULL,
 242                       const char* referrer = NULL,
 243                       PRBool forceJSEnabled = PR_FALSE,
 244                       PRUint32 getHeadersLength = 0,
 245                       const char* getHeaders = NULL) = 0;
 246 %}
 247 };