michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #ifndef nsISupportsUtils_h__ michael@0: #define nsISupportsUtils_h__ michael@0: michael@0: #include "nscore.h" michael@0: #include "nsISupportsBase.h" michael@0: #include "nsError.h" michael@0: #include "nsDebug.h" michael@0: #include "nsISupportsImpl.h" michael@0: #include "mozilla/TypeTraits.h" michael@0: michael@0: /** michael@0: * Macro for adding a reference to an interface. michael@0: * @param _ptr The interface pointer. michael@0: */ michael@0: #define NS_ADDREF(_ptr) \ michael@0: (_ptr)->AddRef() michael@0: michael@0: /** michael@0: * Macro for adding a reference to this. This macro should be used michael@0: * because NS_ADDREF (when tracing) may require an ambiguous cast michael@0: * from the pointers primary type to nsISupports. This macro sidesteps michael@0: * that entire problem. michael@0: */ michael@0: #define NS_ADDREF_THIS() \ michael@0: AddRef() michael@0: michael@0: michael@0: extern "C++" { michael@0: // ...because some one is accidentally including this file inside michael@0: // an |extern "C"| michael@0: michael@0: michael@0: // Making this a |inline| |template| allows |expr| to be evaluated only once, michael@0: // yet still denies you the ability to |AddRef()| an |nsCOMPtr|. michael@0: template michael@0: inline michael@0: void michael@0: ns_if_addref( T expr ) michael@0: { michael@0: if (expr) { michael@0: expr->AddRef(); michael@0: } michael@0: } michael@0: michael@0: } /* extern "C++" */ michael@0: michael@0: /** michael@0: * Macro for adding a reference to an interface that checks for nullptr. michael@0: * @param _expr The interface pointer. michael@0: */ michael@0: #define NS_IF_ADDREF(_expr) ns_if_addref(_expr) michael@0: michael@0: /* michael@0: * Given these declarations, it explicitly OK and efficient to end a `getter' with: michael@0: * michael@0: * NS_IF_ADDREF(*result = mThing); michael@0: * michael@0: * even if |mThing| is an |nsCOMPtr|. If |mThing| is an |nsCOMPtr|, however, it is still michael@0: * _illegal_ to say |NS_IF_ADDREF(mThing)|. michael@0: */ michael@0: michael@0: /** michael@0: * Macro for releasing a reference to an interface. michael@0: * @param _ptr The interface pointer. michael@0: */ michael@0: #define NS_RELEASE(_ptr) \ michael@0: do { \ michael@0: (_ptr)->Release(); \ michael@0: (_ptr) = 0; \ michael@0: } while (0) michael@0: michael@0: /** michael@0: * Macro for releasing a reference to this interface. michael@0: */ michael@0: #define NS_RELEASE_THIS() \ michael@0: Release() michael@0: michael@0: /** michael@0: * Macro for releasing a reference to an interface, except that this michael@0: * macro preserves the return value from the underlying Release call. michael@0: * The interface pointer argument will only be NULLed if the reference count michael@0: * goes to zero. michael@0: * michael@0: * @param _ptr The interface pointer. michael@0: * @param _rc The reference count. michael@0: */ michael@0: #define NS_RELEASE2(_ptr, _rc) \ michael@0: do { \ michael@0: _rc = (_ptr)->Release(); \ michael@0: if (0 == (_rc)) (_ptr) = 0; \ michael@0: } while (0) michael@0: michael@0: /** michael@0: * Macro for releasing a reference to an interface that checks for nullptr; michael@0: * @param _ptr The interface pointer. michael@0: */ michael@0: #define NS_IF_RELEASE(_ptr) \ michael@0: do { \ michael@0: if (_ptr) { \ michael@0: (_ptr)->Release(); \ michael@0: (_ptr) = 0; \ michael@0: } \ michael@0: } while (0) michael@0: michael@0: /* michael@0: * Often you have to cast an implementation pointer, e.g., |this|, to an michael@0: * |nsISupports*|, but because you have multiple inheritance, a simple cast michael@0: * is ambiguous. One could simply say, e.g., (given a base |nsIBase|), michael@0: * |static_cast(this)|; but that disguises the fact that what michael@0: * you are really doing is disambiguating the |nsISupports|. You could make michael@0: * that more obvious with a double cast, e.g., |static_cast michael@0: (* static_cast(this))|, but that is bulky and harder to read... michael@0: * michael@0: * The following macro is clean, short, and obvious. In the example above, michael@0: * you would use it like this: |NS_ISUPPORTS_CAST(nsIBase*, this)|. michael@0: */ michael@0: michael@0: #define NS_ISUPPORTS_CAST(__unambiguousBase, __expr) \ michael@0: static_cast(static_cast<__unambiguousBase>(__expr)) michael@0: michael@0: // a type-safe shortcut for calling the |QueryInterface()| member function michael@0: template michael@0: inline michael@0: nsresult michael@0: CallQueryInterface( T* aSource, DestinationType** aDestination ) michael@0: { michael@0: // We permit nsISupports-to-nsISupports here so that one can still obtain michael@0: // the canonical nsISupports pointer with CallQueryInterface. michael@0: static_assert(!mozilla::IsSame::value || michael@0: mozilla::IsSame::value, michael@0: "don't use CallQueryInterface for compile-time-determinable casts"); michael@0: michael@0: NS_PRECONDITION(aSource, "null parameter"); michael@0: NS_PRECONDITION(aDestination, "null parameter"); michael@0: michael@0: return aSource->QueryInterface(NS_GET_TEMPLATE_IID(DestinationType), michael@0: reinterpret_cast(aDestination)); michael@0: } michael@0: michael@0: #endif /* __nsISupportsUtils_h */