xpcom/base/nsError.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef nsError_h__
   7 #define nsError_h__
   8
   9 #include "mozilla/Likely.h"
  10 #include "mozilla/TypedEnum.h"
  11
  12 #include <stdint.h>
  13
  14 /*
  15  * To add error code to your module, you need to do the following:
  16  *
  17  * 1) Add a module offset code.  Add yours to the bottom of the list
  18  *    right below this comment, adding 1.
  19  *
  20  * 2) In your module, define a header file which uses one of the
  21  *    NE_ERROR_GENERATExxxxxx macros.  Some examples below:
  22  *
  23  *    #define NS_ERROR_MYMODULE_MYERROR1 NS_ERROR_GENERATE(NS_ERROR_SEVERITY_ERROR,NS_ERROR_MODULE_MYMODULE,1)
  24  *    #define NS_ERROR_MYMODULE_MYERROR2 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_MYMODULE,2)
  25  *    #define NS_ERROR_MYMODULE_MYERROR3 NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_MYMODULE,3)
  26  *
  27  */
  28
  29
  30 /**
  31  * @name Standard Module Offset Code. Each Module should identify a unique number
  32  *       and then all errors associated with that module become offsets from the
  33  *       base associated with that module id. There are 16 bits of code bits for
  34  *       each module.
  35  */
  36
  37 #define NS_ERROR_MODULE_XPCOM      1
  38 #define NS_ERROR_MODULE_BASE       2
  39 #define NS_ERROR_MODULE_GFX        3
  40 #define NS_ERROR_MODULE_WIDGET     4
  41 #define NS_ERROR_MODULE_CALENDAR   5
  42 #define NS_ERROR_MODULE_NETWORK    6
  43 #define NS_ERROR_MODULE_PLUGINS    7
  44 #define NS_ERROR_MODULE_LAYOUT     8
  45 #define NS_ERROR_MODULE_HTMLPARSER 9
  46 #define NS_ERROR_MODULE_RDF        10
  47 #define NS_ERROR_MODULE_UCONV      11
  48 #define NS_ERROR_MODULE_REG        12
  49 #define NS_ERROR_MODULE_FILES      13
  50 #define NS_ERROR_MODULE_DOM        14
  51 #define NS_ERROR_MODULE_IMGLIB     15
  52 #define NS_ERROR_MODULE_MAILNEWS   16
  53 #define NS_ERROR_MODULE_EDITOR     17
  54 #define NS_ERROR_MODULE_XPCONNECT  18
  55 #define NS_ERROR_MODULE_PROFILE    19
  56 #define NS_ERROR_MODULE_LDAP       20
  57 #define NS_ERROR_MODULE_SECURITY   21
  58 #define NS_ERROR_MODULE_DOM_XPATH  22
  59 /* 23 used to be NS_ERROR_MODULE_DOM_RANGE (see bug 711047) */
  60 #define NS_ERROR_MODULE_URILOADER  24
  61 #define NS_ERROR_MODULE_CONTENT    25
  62 #define NS_ERROR_MODULE_PYXPCOM    26
  63 #define NS_ERROR_MODULE_XSLT       27
  64 #define NS_ERROR_MODULE_IPC        28
  65 #define NS_ERROR_MODULE_SVG        29
  66 #define NS_ERROR_MODULE_STORAGE    30
  67 #define NS_ERROR_MODULE_SCHEMA     31
  68 #define NS_ERROR_MODULE_DOM_FILE   32
  69 #define NS_ERROR_MODULE_DOM_INDEXEDDB 33
  70 #define NS_ERROR_MODULE_DOM_FILEHANDLE 34
  71 #define NS_ERROR_MODULE_SIGNED_JAR 35
  72
  73 /* NS_ERROR_MODULE_GENERAL should be used by modules that do not
  74  * care if return code values overlap. Callers of methods that
  75  * return such codes should be aware that they are not
  76  * globally unique. Implementors should be careful about blindly
  77  * returning codes from other modules that might also use
  78  * the generic base.
  79  */
  80 #define NS_ERROR_MODULE_GENERAL    51
  81
  82 /**
  83  * @name Severity Code.  This flag identifies the level of warning
  84  */
  85
  86 #define NS_ERROR_SEVERITY_SUCCESS       0
  87 #define NS_ERROR_SEVERITY_ERROR         1
  88
  89 /**
  90  * @name Mozilla Code.  This flag separates consumers of mozilla code
  91  *       from the native platform
  92  */
  93
  94 #define NS_ERROR_MODULE_BASE_OFFSET 0x45
  95
  96 /* Helpers for defining our enum, to be undef'd later */
  97 #define SUCCESS_OR_FAILURE(sev, module, code) \
  98   ((uint32_t)(sev) << 31) | \
  99   ((uint32_t)(module + NS_ERROR_MODULE_BASE_OFFSET) << 16) | \
 100   (uint32_t)(code)
 101 #define SUCCESS(code) \
 102   SUCCESS_OR_FAILURE(NS_ERROR_SEVERITY_SUCCESS, MODULE, code)
 103 #define FAILURE(code) \
 104   SUCCESS_OR_FAILURE(NS_ERROR_SEVERITY_ERROR, MODULE, code)
 105
 106 /**
 107  * @name Standard return values
 108  */
 109
 110 /*@{*/
 111
 112 /* Unfortunately, our workaround for compilers that don't support enum class
 113  * doesn't really work for nsresult.  We need constants like NS_OK with type
 114  * nsresult, but they can't be used in (e.g.) switch cases if they're objects.
 115  * But if we define them to be of type nsresult::Enum instead, that causes
 116  *   return foo ? F() : NS_ERROR_FAILURE;
 117  * to fail, because nsresult and nsresult::Enum are two distinct types and
 118  * either can be converted to the other, so it's ambiguous.  So we have to fall
 119  * back to a regular enum.
 120  */
 121 #if defined(MOZ_HAVE_CXX11_STRONG_ENUMS)
 122   typedef enum class tag_nsresult : uint32_t
 123   {
 124     #undef ERROR
 125     #define ERROR(key, val) key = val
 126     #include "ErrorList.h"
 127     #undef ERROR
 128   } nsresult;
 129
 130   /*
 131    * enum classes don't place their initializers in the global scope, so we need
 132    * #define's for compatibility with old code.
 133    */
 134   #include "ErrorListCxxDefines.h"
 135 #elif defined(MOZ_HAVE_CXX11_ENUM_TYPE)
 136   typedef enum tag_nsresult : uint32_t
 137   {
 138     #undef ERROR
 139     #define ERROR(key, val) key = val
 140     #include "ErrorList.h"
 141     #undef ERROR
 142   } nsresult;
 143 #elif defined(__cplusplus)
 144   /*
 145    * We're C++ in an old compiler lacking enum classes *and* typed enums (likely
 146    * gcc < 4.5.1 as clang/MSVC have long supported one or both), or compiler
 147    * support is unknown.  Yet nsresult must have unsigned 32-bit representation.
 148    * So just make it a typedef, and implement the constants with global consts.
 149    */
 150   typedef uint32_t nsresult;
 151
 152   const nsresult
 153   #undef ERROR
 154   #define ERROR(key, val) key = val
 155   #include "ErrorList.h"
 156   #undef ERROR
 157     ;
 158 #else
 159   /*
 160    * C doesn't have any way to fix the type underlying an enum, and enum
 161    * initializers can't have values outside the range of 'int'.  So typedef
 162    * nsresult to the correct unsigned type, and fall back to using #defines for
 163    * all error constants.
 164    */
 165   typedef uint32_t nsresult;
 166   #include "ErrorListCDefines.h"
 167 #endif
 168
 169 #undef SUCCESS_OR_FAILURE
 170 #undef SUCCESS
 171 #undef FAILURE
 172
 173 /**
 174  * @name Standard Error Handling Macros
 175  * @return 0 or 1 (false/true with bool type for C++)
 176  */
 177
 178 #ifdef __cplusplus
 179 inline uint32_t NS_FAILED_impl(nsresult _nsresult) {
 180   return static_cast<uint32_t>(_nsresult) & 0x80000000;
 181 }
 182 #define NS_FAILED(_nsresult)    ((bool)MOZ_UNLIKELY(NS_FAILED_impl(_nsresult)))
 183 #define NS_SUCCEEDED(_nsresult) ((bool)MOZ_LIKELY(!NS_FAILED_impl(_nsresult)))
 184
 185 /* Check that our enum type is actually uint32_t as expected */
 186 static_assert(((nsresult)0) < ((nsresult)-1),
 187               "nsresult must be an unsigned type");
 188 static_assert(sizeof(nsresult) == sizeof(uint32_t),
 189               "nsresult must be 32 bits");
 190 #else
 191 #define NS_FAILED_impl(_nsresult) ((_nsresult) & 0x80000000)
 192 #define NS_FAILED(_nsresult)    (MOZ_UNLIKELY(NS_FAILED_impl(_nsresult)))
 193 #define NS_SUCCEEDED(_nsresult) (MOZ_LIKELY(!NS_FAILED_impl(_nsresult)))
 194 #endif
 195
 196 /**
 197  * @name Standard Error Generating Macros
 198  */
 199
 200 #define NS_ERROR_GENERATE(sev, module, code) \
 201     (nsresult)(((uint32_t)(sev) << 31) | \
 202                ((uint32_t)(module + NS_ERROR_MODULE_BASE_OFFSET) << 16) | \
 203                ((uint32_t)(code)))
 204
 205 #define NS_ERROR_GENERATE_SUCCESS(module, code) \
 206   NS_ERROR_GENERATE(NS_ERROR_SEVERITY_SUCCESS, module, code)
 207
 208 #define NS_ERROR_GENERATE_FAILURE(module, code) \
 209   NS_ERROR_GENERATE(NS_ERROR_SEVERITY_ERROR, module, code)
 210
 211  /*
 212   * This will return the nsresult corresponding to the most recent NSPR failure
 213   * returned by PR_GetError.
 214   *
 215   ***********************************************************************
 216   *      Do not depend on this function. It will be going away!
 217   ***********************************************************************
 218   */
 219 extern nsresult
 220 NS_ErrorAccordingToNSPR();
 221
 222
 223 /**
 224  * @name Standard Macros for retrieving error bits
 225  */
 226
 227 #ifdef __cplusplus
 228 inline uint16_t NS_ERROR_GET_CODE(nsresult err) {
 229   return uint32_t(err) & 0xffff;
 230 }
 231 inline uint16_t NS_ERROR_GET_MODULE(nsresult err) {
 232   return ((uint32_t(err) >> 16) - NS_ERROR_MODULE_BASE_OFFSET) & 0x1fff;
 233 }
 234 inline bool NS_ERROR_GET_SEVERITY(nsresult err) {
 235   return uint32_t(err) >> 31;
 236 }
 237 #else
 238 #define NS_ERROR_GET_CODE(err)     ((err) & 0xffff)
 239 #define NS_ERROR_GET_MODULE(err)   ((((err) >> 16) - NS_ERROR_MODULE_BASE_OFFSET) & 0x1fff)
 240 #define NS_ERROR_GET_SEVERITY(err) (((err) >> 31) & 0x1)
 241 #endif
 242
 243
 244 #ifdef _MSC_VER
 245 #pragma warning(disable: 4251) /* 'nsCOMPtr<class nsIInputStream>' needs to have dll-interface to be used by clients of class 'nsInputStream' */
 246 #pragma warning(disable: 4275) /* non dll-interface class 'nsISupports' used as base for dll-interface class 'nsIRDFNode' */
 247 #endif
 248
 249 #endif