dom/bindings/nsIScriptError.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   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 /*
   7  * nsIConsoleMessage subclass for representing JavaScript errors and warnings.
   8  */
   9
  10
  11 #include "nsISupports.idl"
  12 #include "nsIArray.idl"
  13 #include "nsIConsoleMessage.idl"
  14 interface nsIURI;
  15
  16 %{C++
  17 #include "nsString.h" // for nsDependentCString
  18 %}
  19
  20 [scriptable, uuid(e8933fc9-c302-4e12-a55b-4f88611d9c6c)]
  21 interface nsIScriptErrorNote : nsISupports
  22 {
  23     readonly attribute AString errorMessage;
  24     readonly attribute AString sourceName;
  25
  26     /**
  27      * Unique identifier within the process for the script source this note is
  28      * associated with, or zero.
  29      */
  30     readonly attribute uint32_t sourceId;
  31
  32     readonly attribute uint32_t lineNumber;
  33     readonly attribute uint32_t columnNumber;
  34
  35     AUTF8String toString();
  36 };
  37
  38 [scriptable, uuid(63eb4d3e-7d99-4150-b4f3-11314f9d82a9)]
  39 interface nsIScriptError : nsIConsoleMessage
  40 {
  41     /** pseudo-flag for default case */
  42     const unsigned long errorFlag = 0x0;
  43
  44     /** message is warning */
  45     const unsigned long warningFlag = 0x1;
  46
  47     /** just a log message */
  48     const unsigned long infoFlag = 0x8;
  49
  50     /**
  51      * The error message without any context/line number information.
  52      *
  53      * @note nsIConsoleMessage.message will return the error formatted
  54      *       with file/line information.
  55      */
  56     readonly attribute AString errorMessage;
  57
  58     readonly attribute AString sourceName;
  59     readonly attribute AString sourceLine;
  60
  61     /**
  62      * Unique identifier within the process for the script source this error is
  63      * associated with, or zero.
  64      */
  65     readonly attribute uint32_t sourceId;
  66
  67     readonly attribute uint32_t lineNumber;
  68     readonly attribute uint32_t columnNumber;
  69     readonly attribute uint32_t flags;
  70
  71     /**
  72      * Categories I know about -
  73      * XUL javascript
  74      * content javascript (both of these from nsDocShell, currently)
  75      * system javascript (errors in JS components and other system JS)
  76      */
  77     readonly attribute string category;
  78
  79     /* Get the window id this was initialized with.  Zero will be
  80        returned if init() was used instead of initWithWindowID(). */
  81     readonly attribute unsigned long long outerWindowID;
  82
  83     /* Get the inner window id this was initialized with.  Zero will be
  84        returned if init() was used instead of initWithWindowID(). */
  85     readonly attribute unsigned long long innerWindowID;
  86
  87     readonly attribute boolean isFromPrivateWindow;
  88
  89     readonly attribute boolean isFromChromeContext;
  90
  91     // Error created from a Promise rejection.
  92     readonly attribute boolean isPromiseRejection;
  93
  94     [noscript] void initIsPromiseRejection(in bool isPromiseRejection);
  95
  96     // The "exception" value generated when an uncaught exception is thrown
  97     // by JavaScript. This can be any value, e.g.
  98     // - an Error object (`throw new Error("foobar"`)
  99     // - some primitive (`throw "hello"`)
 100     attribute jsval exception;
 101
 102     // The hasException attribute is used to differentiate between no thrown
 103     // exception and `throw undefined`.
 104     readonly attribute boolean hasException;
 105
 106     attribute jsval stack;
 107
 108     /**
 109      * If |stack| is an object, then stackGlobal must be a global object that's
 110      * same-compartment with |stack|. This can be used to enter the correct
 111      * realm when working with the stack object. We can't use the object itself
 112      * because it might be a cross-compartment wrapper and CCWs are not
 113      * associated with a single realm/global.
 114      */
 115     [noscript] readonly attribute jsval stackGlobal;
 116
 117     /**
 118      * The name of a template string associated with the error message.  See
 119      * js/public/friend/ErrorNumbers.msg.
 120      */
 121     attribute AString errorMessageName;
 122
 123     readonly attribute nsIArray notes;
 124
 125     /**
 126      * If the ScriptError is a CSS parser error, this value will contain the
 127      * CSS selectors of the CSS ruleset where the error occured.
 128      */
 129     attribute AString cssSelectors;
 130
 131     void init(in AString message,
 132               in AString sourceName,
 133               in AString sourceLine,
 134               in uint32_t lineNumber,
 135               in uint32_t columnNumber,
 136               in uint32_t flags,
 137               in string category,
 138               [optional] in bool fromPrivateWindow,
 139               [optional] in bool fromChromeContext);
 140
 141     /* This should be called instead of nsIScriptError.init to
 142      * initialize with a window id.  The window id should be for the
 143      * inner window associated with this error.
 144      *
 145      * This function will check whether sourceName is a uri and sanitize it if
 146      * needed. If you know the source name is sanitized already, use
 147      * initWithSanitizedSource.
 148      * A "sanitized" source name means that passwords are not shown. It will
 149      * use the sensitiveInfoHiddenSpec function of nsIURI interface, that is
 150      * replacing paswords with ***
 151      * (e.g. https://USERNAME:****@example.com/some/path).
 152      */
 153     void initWithWindowID(in AString message,
 154                           in AString sourceName,
 155                           in AString sourceLine,
 156                           in uint32_t lineNumber,
 157                           in uint32_t columnNumber,
 158                           in uint32_t flags,
 159                           in ACString category,
 160                           in unsigned long long innerWindowID,
 161                           [optional] in bool fromChromeContext);
 162
 163     /* This is the same function as initWithWindowID, but it expects an already
 164      * sanitized sourceName.
 165      * Please use it only if sourceName string is already sanitized.
 166      */
 167     void initWithSanitizedSource(in AString message,
 168                                  in AString sourceName,
 169                                  in AString sourceLine,
 170                                  in uint32_t lineNumber,
 171                                  in uint32_t columnNumber,
 172                                  in uint32_t flags,
 173                                  in ACString category,
 174                                  in unsigned long long innerWindowID,
 175                                  [optional] in bool fromChromeContext);
 176
 177     /* This is the same function as initWithWindowID with an uri as a source parameter.
 178      */
 179     void initWithSourceURI(in AString message,
 180                            in nsIURI sourceURI,
 181                            in AString sourceLine,
 182                            in uint32_t lineNumber,
 183                            in uint32_t columnNumber,
 184                            in uint32_t flags,
 185                            in ACString category,
 186                            in unsigned long long innerWindowID,
 187                            [optional] in bool fromChromeContext);
 188
 189     /* Initialize the script source ID in a new error. */
 190     void initSourceId(in uint32_t sourceId);
 191
 192 %{C++
 193     nsresult InitWithWindowID(const nsAString& message,
 194                               const nsAString& sourceName,
 195                               const nsAString& sourceLine,
 196                               uint32_t lineNumber,
 197                               uint32_t columnNumber,
 198                               uint32_t flags,
 199                               const nsACString& category,
 200                               uint64_t aInnerWindowID)
 201     {
 202         return InitWithWindowID(message, sourceName, sourceLine, lineNumber,
 203                                 columnNumber, flags, category, aInnerWindowID,
 204                                 false);
 205     }
 206     // These overloads allow passing a literal string for category.
 207     template<uint32_t N>
 208     nsresult InitWithWindowID(const nsAString& message,
 209                               const nsAString& sourceName,
 210                               const nsAString& sourceLine,
 211                               uint32_t lineNumber,
 212                               uint32_t columnNumber,
 213                               uint32_t flags,
 214                               const char (&c)[N],
 215                               uint64_t aInnerWindowID,
 216                               bool aFromChromeContext = false)
 217     {
 218         nsDependentCString category(c, N - 1);
 219         return InitWithWindowID(message, sourceName, sourceLine, lineNumber,
 220                                 columnNumber, flags, category, aInnerWindowID,
 221                                 aFromChromeContext);
 222     }
 223
 224     nsresult InitWithSanitizedSource(const nsAString& message,
 225                                      const nsAString& sourceName,
 226                                      const nsAString& sourceLine,
 227                                      uint32_t lineNumber,
 228                                      uint32_t columnNumber,
 229                                      uint32_t flags,
 230                                      const nsACString& category,
 231                                      uint64_t aInnerWindowID)
 232     {
 233         return InitWithSanitizedSource(message, sourceName, sourceLine,
 234                                        lineNumber, columnNumber, flags,
 235                                        category, aInnerWindowID,
 236                                        false);
 237     }
 238
 239     template<uint32_t N>
 240     nsresult InitWithSanitizedSource(const nsAString& message,
 241                                      const nsAString& sourceName,
 242                                      const nsAString& sourceLine,
 243                                      uint32_t lineNumber,
 244                                      uint32_t columnNumber,
 245                                      uint32_t flags,
 246                                      const char (&c)[N],
 247                                      uint64_t aInnerWindowID,
 248                                      bool aFromChromeContext = false)
 249     {
 250         nsDependentCString category(c, N - 1);
 251         return InitWithSanitizedSource(message, sourceName, sourceLine,
 252                                        lineNumber, columnNumber, flags,
 253                                        category, aInnerWindowID,
 254                                        aFromChromeContext);
 255     }
 256
 257     nsresult InitWithSourceURI(const nsAString& message,
 258                                nsIURI* sourceURI,
 259                                const nsAString& sourceLine,
 260                                uint32_t lineNumber,
 261                                uint32_t columnNumber,
 262                                uint32_t flags,
 263                                const nsACString& category,
 264                                uint64_t aInnerWindowID)
 265     {
 266         return InitWithSourceURI(message, sourceURI, sourceLine,
 267                                  lineNumber, columnNumber, flags,
 268                                  category, aInnerWindowID, false);
 269     }
 270
 271     template<uint32_t N>
 272     nsresult InitWithSourceURI(const nsAString& message,
 273                                nsIURI* sourceURI,
 274                                const nsAString& sourceLine,
 275                                uint32_t lineNumber,
 276                                uint32_t columnNumber,
 277                                uint32_t flags,
 278                                const char (&c)[N],
 279                                uint64_t aInnerWindowID,
 280                                bool aFromChromeContext = false)
 281     {
 282         nsDependentCString category(c, N - 1);
 283         return InitWithSourceURI(message, sourceURI, sourceLine,
 284                                  lineNumber, columnNumber, flags,
 285                                  category, aInnerWindowID, aFromChromeContext);
 286     }
 287 %}
 288
 289 };
 290
 291 %{ C++
 292 #define NS_SCRIPTERROR_CID \
 293 { 0x1950539a, 0x90f0, 0x4d22, { 0xb5, 0xaf, 0x71, 0x32, 0x9c, 0x68, 0xfa, 0x35 }}
 294
 295 #define NS_SCRIPTERROR_CONTRACTID "@mozilla.org/scripterror;1"
 296 %}