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/. */ 6 7#include "nsISupports.idl" 8 9%{C++ 10#include "mozilla/MemoryReporting.h" 11%} 12 13/** 14 * An instance of |nsIWeakReference| is a proxy object that cooperates with 15 * its referent to give clients a non-owning, non-dangling reference. Clients 16 * own the proxy, and should generally manage it with an |nsCOMPtr| (see the 17 * type |nsWeakPtr| for a |typedef| name that stands out) as they would any 18 * other XPCOM object. The |QueryReferent| member function provides a 19 * (hopefully short-lived) owning reference on demand, through which clients 20 * can get useful access to the referent, while it still exists. 21 * 22 * @version 1.0 23 * @see nsISupportsWeakReference 24 * @see nsWeakReference 25 * @see nsWeakPtr 26 */ 27[scriptable, uuid(9188bc85-f92e-11d2-81ef-0060083a0bcf)] 28interface nsIWeakReference : nsISupports 29 { 30 /** 31 * |QueryReferent| queries the referent, if it exists, and like |QueryInterface|, produces 32 * an owning reference to the desired interface. It is designed to look and act exactly 33 * like (a proxied) |QueryInterface|. Don't hold on to the produced interface permanently; 34 * that would defeat the purpose of using a non-owning |nsIWeakReference| in the first place. 35 */ 36 void QueryReferent( in nsIIDRef uuid, [iid_is(uuid), retval] out nsQIResult result ); 37 38%{C++ 39 virtual size_t SizeOfOnlyThis(mozilla::MallocSizeOf aMallocSizeOf) const = 0; 40%} 41 }; 42 43 44/** 45 * |nsISupportsWeakReference| is a factory interface which produces appropriate 46 * instances of |nsIWeakReference|. Weak references in this scheme can only be 47 * produced for objects that implement this interface. 48 * 49 * @version 1.0 50 * @see nsIWeakReference 51 * @see nsSupportsWeakReference 52 */ 53[scriptable, uuid(9188bc86-f92e-11d2-81ef-0060083a0bcf)] 54interface nsISupportsWeakReference : nsISupports 55 { 56 /** 57 * |GetWeakReference| produces an appropriate instance of |nsIWeakReference|. 58 * As with all good XPCOM `getters', you own the resulting interface and should 59 * manage it with an |nsCOMPtr|. 60 * 61 * @see nsIWeakReference 62 * @see nsWeakPtr 63 * @see nsCOMPtr 64 */ 65 nsIWeakReference GetWeakReference(); 66 }; 67 68 69%{C++ 70#ifdef MOZILLA_INTERNAL_API 71#include "nsIWeakReferenceUtils.h" 72#endif 73%} 74 75