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 : * Pierre Phaneuf <pp@ludusdesign.com>
24 : * Scott Collins <scc@ScottCollins.net>
25 : * Dan Mosedale <dmose@mozilla.org>
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 : #ifndef nsISupportsUtils_h__
42 : #define nsISupportsUtils_h__
43 :
44 : #ifndef nscore_h___
45 : #include "nscore.h"
46 : #endif
47 :
48 : #ifndef nsISupportsBase_h__
49 : #include "nsISupportsBase.h"
50 : #endif
51 :
52 : #ifndef nsError_h__
53 : #include "nsError.h"
54 : #endif
55 :
56 : #ifndef nsDebug_h___
57 : #include "nsDebug.h"
58 : #endif
59 :
60 : #ifndef nsISupportsImpl_h__
61 : #include "nsISupportsImpl.h"
62 : #endif
63 :
64 : /**
65 : * Macro for adding a reference to an interface.
66 : * @param _ptr The interface pointer.
67 : */
68 : #define NS_ADDREF(_ptr) \
69 : (_ptr)->AddRef()
70 :
71 : /**
72 : * Macro for adding a reference to this. This macro should be used
73 : * because NS_ADDREF (when tracing) may require an ambiguous cast
74 : * from the pointers primary type to nsISupports. This macro sidesteps
75 : * that entire problem.
76 : */
77 : #define NS_ADDREF_THIS() \
78 : AddRef()
79 :
80 :
81 : extern "C++" {
82 : // ...because some one is accidentally including this file inside
83 : // an |extern "C"|
84 :
85 :
86 : // Making this a |inline| |template| allows |expr| to be evaluated only once,
87 : // yet still denies you the ability to |AddRef()| an |nsCOMPtr|.
88 : template <class T>
89 : inline
90 : void
91 4731314 : ns_if_addref( T expr )
92 : {
93 4731314 : if (expr) {
94 2942755 : expr->AddRef();
95 : }
96 4731315 : }
97 :
98 : } /* extern "C++" */
99 :
100 : /**
101 : * Macro for adding a reference to an interface that checks for NULL.
102 : * @param _expr The interface pointer.
103 : */
104 : #define NS_IF_ADDREF(_expr) ns_if_addref(_expr)
105 :
106 : /*
107 : * Given these declarations, it explicitly OK and efficient to end a `getter' with:
108 : *
109 : * NS_IF_ADDREF(*result = mThing);
110 : *
111 : * even if |mThing| is an |nsCOMPtr|. If |mThing| is an |nsCOMPtr|, however, it is still
112 : * _illegal_ to say |NS_IF_ADDREF(mThing)|.
113 : */
114 :
115 : /**
116 : * Macro for releasing a reference to an interface.
117 : * @param _ptr The interface pointer.
118 : */
119 : #define NS_RELEASE(_ptr) \
120 : PR_BEGIN_MACRO \
121 : (_ptr)->Release(); \
122 : (_ptr) = 0; \
123 : PR_END_MACRO
124 :
125 : /**
126 : * Macro for releasing a reference to an interface.
127 : * @param _ptr The interface pointer.
128 : */
129 : #define NS_RELEASE_THIS() \
130 : Release()
131 :
132 : /**
133 : * Macro for releasing a reference to an interface, except that this
134 : * macro preserves the return value from the underlying Release call.
135 : * The interface pointer argument will only be NULLed if the reference count
136 : * goes to zero.
137 : *
138 : * @param _ptr The interface pointer.
139 : */
140 : #define NS_RELEASE2(_ptr,_rv) \
141 : PR_BEGIN_MACRO \
142 : _rv = (_ptr)->Release(); \
143 : if (0 == (_rv)) (_ptr) = 0; \
144 : PR_END_MACRO
145 :
146 : /**
147 : * Macro for releasing a reference to an interface that checks for NULL;
148 : * @param _ptr The interface pointer.
149 : */
150 : #define NS_IF_RELEASE(_ptr) \
151 : PR_BEGIN_MACRO \
152 : if (_ptr) { \
153 : (_ptr)->Release(); \
154 : (_ptr) = 0; \
155 : } \
156 : PR_END_MACRO
157 :
158 : /*
159 : * Often you have to cast an implementation pointer, e.g., |this|, to an
160 : * |nsISupports*|, but because you have multiple inheritance, a simple cast
161 : * is ambiguous. One could simply say, e.g., (given a base |nsIBase|),
162 : * |static_cast<nsIBase*>(this)|; but that disguises the fact that what
163 : * you are really doing is disambiguating the |nsISupports|. You could make
164 : * that more obvious with a double cast, e.g., |static_cast<nsISupports*>
165 : (* static_cast<nsIBase*>(this))|, but that is bulky and harder to read...
166 : *
167 : * The following macro is clean, short, and obvious. In the example above,
168 : * you would use it like this: |NS_ISUPPORTS_CAST(nsIBase*, this)|.
169 : */
170 :
171 : #define NS_ISUPPORTS_CAST(__unambiguousBase, __expr) \
172 : static_cast<nsISupports*>(static_cast<__unambiguousBase>(__expr))
173 :
174 : // a type-safe shortcut for calling the |QueryInterface()| member function
175 : template <class T, class DestinationType>
176 : inline
177 : nsresult
178 7074146 : CallQueryInterface( T* aSource, DestinationType** aDestination )
179 : {
180 7074146 : NS_PRECONDITION(aSource, "null parameter");
181 7074146 : NS_PRECONDITION(aDestination, "null parameter");
182 :
183 : return aSource->QueryInterface(NS_GET_TEMPLATE_IID(DestinationType),
184 7074146 : reinterpret_cast<void**>(aDestination));
185 : }
186 :
187 : #endif /* __nsISupportsUtils_h */
|