PageRenderTime 210ms CodeModel.GetById 203ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/gecko_api/include/nsISupportsUtils.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 206 lines | 71 code | 26 blank | 109 comment | 3 complexity | 582ddf987451352329be03526a64d284 MD5 | raw file
  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 instantiating a new object that implements nsISupports.
 66 * Note that you can only use this if you adhere to the no arguments
 67 * constructor com policy (which you really should!).
 68 * @param _result Where the new instance pointer is stored
 69 * @param _type The type of object to call "new" with.
 70 */
 71#define NS_NEWXPCOM(_result,_type)                                            \
 72  PR_BEGIN_MACRO                                                              \
 73    _result = new _type();                                                    \
 74  PR_END_MACRO
 75
 76/**
 77 * Macro for deleting an object that implements nsISupports.
 78 * @param _ptr The object to delete.
 79 */
 80#define NS_DELETEXPCOM(_ptr)                                                  \
 81  PR_BEGIN_MACRO                                                              \
 82    delete (_ptr);                                                            \
 83  PR_END_MACRO
 84
 85/**
 86 * Macro for adding a reference to an interface.
 87 * @param _ptr The interface pointer.
 88 */
 89#define NS_ADDREF(_ptr) \
 90  (_ptr)->AddRef()
 91
 92/**
 93 * Macro for adding a reference to this. This macro should be used
 94 * because NS_ADDREF (when tracing) may require an ambiguous cast
 95 * from the pointers primary type to nsISupports. This macro sidesteps
 96 * that entire problem.
 97 */
 98#define NS_ADDREF_THIS() \
 99  AddRef()
100
101
102extern "C++" {
103// ...because some one is accidentally including this file inside
104// an |extern "C"|
105
106
107// Making this a |inline| |template| allows |expr| to be evaluated only once,
108// yet still denies you the ability to |AddRef()| an |nsCOMPtr|.
109template <class T>
110inline
111nsrefcnt
112ns_if_addref( T expr )
113{
114    return expr ? expr->AddRef() : 0;
115}
116
117} /* extern "C++" */
118
119/**
120 * Macro for adding a reference to an interface that checks for NULL.
121 * @param _expr The interface pointer.
122 */
123#define NS_IF_ADDREF(_expr) ns_if_addref(_expr)
124
125/*
126 * Given these declarations, it explicitly OK and efficient to end a `getter' with:
127 *
128 *    NS_IF_ADDREF(*result = mThing);
129 *
130 * even if |mThing| is an |nsCOMPtr|.  If |mThing| is an |nsCOMPtr|, however, it is still
131 * _illegal_ to say |NS_IF_ADDREF(mThing)|.
132 */
133
134/**
135 * Macro for releasing a reference to an interface.
136 * @param _ptr The interface pointer.
137 */
138#define NS_RELEASE(_ptr)                                                      \
139  PR_BEGIN_MACRO                                                              \
140    (_ptr)->Release();                                                        \
141    (_ptr) = 0;                                                               \
142  PR_END_MACRO
143
144/**
145 * Macro for releasing a reference to an interface.
146 * @param _ptr The interface pointer.
147 */
148#define NS_RELEASE_THIS() \
149    Release()
150
151/**
152 * Macro for releasing a reference to an interface, except that this
153 * macro preserves the return value from the underlying Release call.
154 * The interface pointer argument will only be NULLed if the reference count
155 * goes to zero.
156 *
157 * @param _ptr The interface pointer.
158 */
159#define NS_RELEASE2(_ptr,_rv)                                                 \
160  PR_BEGIN_MACRO                                                              \
161    _rv = (_ptr)->Release();                                                  \
162    if (0 == (_rv)) (_ptr) = 0;                                               \
163  PR_END_MACRO
164
165/**
166 * Macro for releasing a reference to an interface that checks for NULL;
167 * @param _ptr The interface pointer.
168 */
169#define NS_IF_RELEASE(_ptr)                                                   \
170  PR_BEGIN_MACRO                                                              \
171    if (_ptr) {                                                               \
172      (_ptr)->Release();                                                      \
173      (_ptr) = 0;                                                             \
174    }                                                                         \
175  PR_END_MACRO
176
177/*
178 * Often you have to cast an implementation pointer, e.g., |this|, to an
179 * |nsISupports*|, but because you have multiple inheritance, a simple cast
180 * is ambiguous.  One could simply say, e.g., (given a base |nsIBase|),
181 * |static_cast<nsIBase*>(this)|; but that disguises the fact that what
182 * you are really doing is disambiguating the |nsISupports|.  You could make
183 * that more obvious with a double cast, e.g., |static_cast<nsISupports*>
184                                                           (* static_cast<nsIBase*>(this))|, but that is bulky and harder to read...
185 *
186 * The following macro is clean, short, and obvious.  In the example above,
187 * you would use it like this: |NS_ISUPPORTS_CAST(nsIBase*, this)|.
188 */
189
190#define NS_ISUPPORTS_CAST(__unambiguousBase, __expr) \
191  static_cast<nsISupports*>(static_cast<__unambiguousBase>(__expr))
192
193// a type-safe shortcut for calling the |QueryInterface()| member function
194template <class T, class DestinationType>
195inline
196nsresult
197CallQueryInterface( T* aSource, DestinationType** aDestination )
198{
199    NS_PRECONDITION(aSource, "null parameter");
200    NS_PRECONDITION(aDestination, "null parameter");
201    
202    return aSource->QueryInterface(NS_GET_TEMPLATE_IID(DestinationType),
203                                   reinterpret_cast<void**>(aDestination));
204}
205
206#endif /* __nsISupportsUtils_h */