The Tor Browser: xpcom/base/nsIWeakReference.idl@6474c204b198

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

     1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-

     2  *

     3  * This Source Code Form is subject to the terms of the Mozilla Public

     4  * License, v. 2.0. If a copy of the MPL was not distributed with this

     5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

     7 #include "nsISupports.idl"

    10 /**

    11  * An instance of |nsIWeakReference| is a proxy object that cooperates with

    12  * its referent to give clients a non-owning, non-dangling reference.  Clients

    13  * own the proxy, and should generally manage it with an |nsCOMPtr| (see the

    14  * type |nsWeakPtr| for a |typedef| name that stands out) as they would any

    15  * other XPCOM object.  The |QueryReferent| member function provides a

    16  * (hopefully short-lived) owning reference on demand, through which clients

    17  * can get useful access to the referent, while it still exists.

    18  *

    19  * @version 1.0

    20  * @see nsISupportsWeakReference

    21  * @see nsWeakReference

    22  * @see nsWeakPtr

    23  */

    24 [scriptable, uuid(9188bc85-f92e-11d2-81ef-0060083a0bcf)]

    25 interface nsIWeakReference : nsISupports

    26   {

    27     /**

    28      * |QueryReferent| queries the referent, if it exists, and like |QueryInterface|, produces

    29      * an owning reference to the desired interface.  It is designed to look and act exactly

    30      * like (a proxied) |QueryInterface|.  Don't hold on to the produced interface permanently;

    31      * that would defeat the purpose of using a non-owning |nsIWeakReference| in the first place.

    32      */

    33     void QueryReferent( in nsIIDRef uuid, [iid_is(uuid), retval] out nsQIResult result );

    34   };

    37 /**

    38  * |nsISupportsWeakReference| is a factory interface which produces appropriate

    39  * instances of |nsIWeakReference|.  Weak references in this scheme can only be

    40  * produced for objects that implement this interface.

    41  *

    42  * @version 1.0

    43  * @see nsIWeakReference

    44  * @see nsSupportsWeakReference

    45  */

    46 [scriptable, uuid(9188bc86-f92e-11d2-81ef-0060083a0bcf)]

    47 interface nsISupportsWeakReference : nsISupports

    48   {

    49     /**

    50      * |GetWeakReference| produces an appropriate instance of |nsIWeakReference|.

    51      * As with all good XPCOM `getters', you own the resulting interface and should

    52      * manage it with an |nsCOMPtr|.

    53      *

    54      * @see nsIWeakReference

    55      * @see nsWeakPtr

    56      * @see nsCOMPtr

    57      */

    58     nsIWeakReference GetWeakReference();

    59   };

    62 %{C++

    63 #ifdef MOZILLA_INTERNAL_API

    64 #include "nsIWeakReferenceUtils.h"

    65 #endif

    66 %}

The Tor Browser / file revision