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