modules/plugin/base/public/nsIPluginInstance.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  * nsIPluginInstance
  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 "nsIPluginStreamListener.idl"
  50
  51 %{C++
  52 #include "nsplugindefs.h"
  53 %}
  54
  55 interface nsIPluginInstancePeer;
  56
  57 /**
  58  * The nsIPluginInstance interface is the minimum interface plugin developers
  59  * need to support in order to implement a plugin instance. The plugin manager
  60  * may QueryInterface for more specific types, e.g. nsILiveConnectPluginInstance.
  61  *
  62  * (Corresponds to NPP object.)
  63  *
  64  * The old NPP_Destroy call has been factored into two plugin instance
  65  * methods:
  66  *
  67  * Stop -- called when the plugin instance is to be stopped (e.g. by
  68  * displaying another plugin manager window, causing the page containing
  69  * the plugin to become removed from the display).
  70  *
  71  * Destroy -- called once, before the plugin instance peer is to be
  72  * destroyed. This method is used to destroy the plugin instance.
  73  */
  74 [uuid(ebe00f40-0199-11d2-815b-006008119d7a)]
  75 interface nsIPluginInstance : nsISupports
  76 {
  77     /**
  78      * Initializes a newly created plugin instance, passing to it the
  79      * plugin instance peer which it should use for all communication
  80      * back to the browser.
  81      *
  82      * @param aPeer - the corresponding plugin instance peer
  83      * @result      - NS_OK if this operation was successful
  84      */
  85     void initialize(in nsIPluginInstancePeer aPeer);
  86
  87     /**
  88      * Returns a reference back to the plugin instance peer. This method is
  89      * used whenever the browser needs to obtain the peer back from a plugin
  90      * instance. The implementation of this method should be sure to increment
  91      * the reference count on the peer by calling AddRef.
  92      *
  93      * @param aPeer - the resulting plugin instance peer
  94      * @result      - NS_OK if this operation was successful
  95      */
  96     readonly attribute nsIPluginInstancePeer peer;
  97
  98     /**
  99      * Called to instruct the plugin instance to start. This will be
 100      * called after the plugin is first created and initialized, and
 101      * may be called after the plugin is stopped (via the Stop method)
 102      * if the plugin instance is returned to in the browser window's
 103      * history.
 104      *
 105      * @result - NS_OK if this operation was successful
 106      */
 107     void start();
 108
 109     /**
 110      * Called to instruct the plugin instance to stop, thereby
 111      * suspending its state.  This method will be called whenever the
 112      * browser window goes on to display another page and the page
 113      * containing the plugin goes into the window's history list.
 114      *
 115      * @result - NS_OK if this operation was successful
 116      */
 117     void stop();
 118
 119     /**
 120      * Called to instruct the plugin instance to destroy itself. This
 121      * is called when it become no longer possible to return to the
 122      * plugin instance, either because the browser window's history
 123      * list of pages is being trimmed, or because the window
 124      * containing this page in the history is being closed.
 125      *
 126      * @result - NS_OK if this operation was successful
 127      */
 128     void destroy();
 129
 130     /**
 131      * Called when the window containing the plugin instance changes.
 132      *
 133      * (Corresponds to NPP_SetWindow.)
 134      *
 135      * @param aWindow - the plugin window structure
 136      * @result        - NS_OK if this operation was successful
 137      */
 138     void setWindow(in nsPluginWindowPtr aWindow);
 139
 140     /**
 141      * Called to tell the plugin that the initial src/data stream is
 142          * ready.  Expects the plugin to return a nsIPluginStreamListener.
 143      *
 144      * (Corresponds to NPP_NewStream.)
 145      *
 146      * @param aListener - listener the browser will use to give the plugin the data
 147      * @result          - NS_OK if this operation was successful
 148      */
 149     void newStream(out nsIPluginStreamListener aListener);
 150
 151     /**
 152      * Called to instruct the plugin instance to print itself to a printer.
 153      *
 154      * (Corresponds to NPP_Print.)
 155      *
 156      * @param aPlatformPrint - platform-specific printing information
 157      * @result               - NS_OK if this operation was successful
 158      */
 159     void print(in nsPluginPrintPtr aPlatformPrint);
 160
 161     /**
 162      * Returns the value of a variable associated with the plugin instance.
 163      *
 164      * @param aVariable - the plugin instance variable to get
 165      * @param aValue    - the address of where to store the resulting value
 166      * @result          - NS_OK if this operation was successful
 167      */
 168     void getValue(in nsPluginInstanceVariable aVariable, in voidPtr aValue);
 169
 170     /**
 171      * Handles an event. An nsIEventHandler can also get registered with with
 172      * nsIPluginManager2::RegisterWindow and will be called whenever an event
 173      * comes in for that window.
 174      *
 175      * Note that for Unix and Mac the nsPluginEvent structure is different
 176      * from the old NPEvent structure -- it's no longer the native event
 177      * record, but is instead a struct. This was done for future extensibility,
 178      * and so that the Mac could receive the window argument too. For Windows
 179      * and OS2, it's always been a struct, so there's no change for them.
 180      *
 181      * (Corresponds to NPP_HandleEvent.)
 182      *
 183      * @param aEvent   - the event to be handled
 184      * @param aHandled - set to PR_TRUE if event was handled
 185      * @result - NS_OK if this operation was successful
 186      */
 187     void handleEvent(in nsPluginEventPtr aEvent, out boolean aHandled);
 188 };