xpcom/proxy/public/nsIProxyObjectManager.idl

   1 /* -*- Mode: C++; tab-width: 2; 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  *   Doug Turner <dougt@netscape.com> (Original Author)
  24  *   Dan Mosedale <dmose@netscape.com>
  25  *   Darin Fisher <darin@meer.net>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either of the GNU General Public License Version 2 or later (the "GPL"),
  29  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #include "nsISupports.idl"
  42
  43 interface nsIEventTarget;
  44
  45 /**
  46  * An interface for the proxy object manager.
  47  *
  48  * See http://www.mozilla.org/projects/xpcom/Proxies.html
  49  */
  50 [scriptable, uuid(ee8ce1e3-0319-4bd9-8f70-7258b21c7733)]
  51 interface nsIProxyObjectManager : nsISupports
  52 {
  53     /**
  54      * Construct a proxy object that invokes methods on the real object
  55      * synchronously (i.e., the calling thread is blocked until the real method
  56      * call returns).  This flag causes methods invoked on the proxy object to
  57      * emmulate a real method call.
  58      *
  59      * For C++ callers, NS_PROXY_SYNC is a synonym for this flag.
  60      */
  61     const long INVOKE_SYNC = 0x0001;
  62
  63     /**
  64      * Construct a proxy object that invokes methods on the real object
  65      * asynchronously (i.e., the calling thread does not wait for the real
  66      * method call to occur).
  67      *
  68      * WARNING: do not pass pointers into the stack when using this flag.
  69      *
  70      * For C++ callers, NS_PROXY_ASYNC is a synonym for this flag.
  71      */
  72     const long INVOKE_ASYNC = 0x0002;
  73
  74     /**
  75      * Always create the proxy object even if for same thread as current thread.
  76      *
  77      * For C++ callers, NS_PROXY_ALWAYS is a synonym for this flag.
  78      */
  79     const long FORCE_PROXY_CREATION = 0x0004;
  80
  81     /**
  82      * Create a proxy for the given object.  The proxy implements the specified
  83      * interface, but when its methods are invoked, it causes the corresponding
  84      * method on the actual object to be called via the designated event
  85      * target.  Typically, the event target identifies a thread where the
  86      * method call should occur.
  87      *
  88      * @param target
  89      *   If target is null, then the current thread is used as the target.
  90      *   Otherwise, target identifies the nsIEventTarget from which proxy
  91      *   method calls should be executed.
  92      * @param iid
  93      *   Identifies the interface being proxied.  The given object must QI to
  94      *   this type.
  95      * @param object
  96      *   The object being proxied.
  97      * @param proxyType
  98      *   Specifies the type of proxy to construct.  Either INVOKE_SYNC or
  99      *   INVOKE_ASYNC must be specified.  FORCE_PROXY_CREATION may be bit-wise
 100      *   OR'd with either of those flags.
 101      * @param result
 102      *   This param holds the resulting proxy object upon successful return.
 103      */
 104     void getProxyForObject(in nsIEventTarget target,
 105                            in nsIIDRef iid,
 106                            in nsISupports object,
 107                            in PRInt32 proxyType,
 108                            [iid_is(iid),retval] out nsQIResult result);
 109 };
 110
 111
 112 %{C++
 113 /**
 114  * convenience macros
 115  */
 116 #define NS_PROXY_SYNC    nsIProxyObjectManager::INVOKE_SYNC
 117 #define NS_PROXY_ASYNC   nsIProxyObjectManager::INVOKE_ASYNC
 118 #define NS_PROXY_ALWAYS  nsIProxyObjectManager::FORCE_PROXY_CREATION
 119
 120 /**
 121  * Pass this value as the target to {NS_}GetProxyForObject to specify the current
 122  * thread as the target for the proxy object.
 123  */
 124 #define NS_PROXY_TO_CURRENT_THREAD  ((nsIEventTarget *) 0)
 125
 126 /**
 127  * Pass this value as the target to NS_GetProxyForObject to specify the main
 128  * thread as the target for the proxy object.
 129  */
 130 #define NS_PROXY_TO_MAIN_THREAD  ((nsIEventTarget *) 1)
 131
 132 #ifdef MOZILLA_INTERNAL_API
 133 /**
 134  * Helper function for code that already has a link-time dependency on the
 135  * internal API (MOZILLA_INTERNAL_API) and needs to get proxies in a bunch of
 136  * different places.  This way, the caller isn't forced to get the proxy object
 137  * manager themselves every single time, thus making the calling code more
 138  * readable.  The parameters are the same as for GetProxyForObject.
 139  */
 140 extern NS_COM nsresult
 141 NS_GetProxyForObject(nsIEventTarget *target, REFNSIID iid, nsISupports* object,
 142                      PRInt32 proxyType, void** result);
 143 #endif
 144 %}