Report an error with an application-defined error code.

Syntax

void
JS_ReportErrorNumber(JSContext *cx, JSErrorCallback errorCallback,
                     void *userRef, const unsigned errorNumber, ...);

void
JS_ReportErrorNumberUC(JSContext *cx, JSErrorCallback errorCallback,
                     void *userRef, const unsigned errorNumber, ...);

bool
JS_ReportErrorFlagsAndNumber(JSContext *cx, unsigned flags,
                             JSErrorCallback errorCallback, void *userRef,
                             const unsigned errorNumber, ...);

bool
JS_ReportErrorFlagsAndNumberUC(JSContext *cx, unsigned flags,
                               JSErrorCallback errorCallback, void *userRef,
                               const unsigned errorNumber, ...);

void
JS_ReportErrorNumberUCArray(JSContext *cx, JSErrorCallback errorCallback,
                            void *userRef, const unsigned errorNumber,
                            const char16_t **args); // Added in SpiderMonkey 19
Name Type Description
cx JSContext * The context in which to report the error. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext.
flags unsigned Error report flags.
errorCallback JSErrorCallback Callback to fetch the error message.
userRef void * A pointer to application data. The JavaScript engine passes this pointer to errorCallback. The meaning of the data is up to the application.
errorNumber const unsigned An error code. The JavaScript engine passes this number to errorCallback. The meaning of the error number is up to the application.
... / args ... / const char16_t **

Additional arguments for the error message. These arguments must be of type char * for JS_ReportErrorNumber or JS_ReportErrorFlagsAndNumber, or char16_t * for JS_ReportErrorNumberUC or JS_ReportErrorFlagsAndNumberUC.

The number of additional arguments required depends on the error message, which is determined by the errorCallback.

Callback syntax

typedef const JSErrorFormatString *
(* JSErrorCallback)(void *userRef, const unsigned errorNumber);
Name Type Description
userRef void * The userRef pointer that was passed to the ReportErrorNumber API.
errorNumber const unsigned The errorNumber that was passed to the ReportErrorNumber API.

Description

These functions create a JSErrorReport, populate it with an error message obtained from the given JSErrorCallback, and either report it to the current error reporter callback or create an Error object and set it as the pending exception.

First errorCallback(userRef, errorNumber) is called. If errorCallback returns NULL, (??? what happens?).

Otherwise, if the JSErrorFormatString returned by the JSErrorCallback has .exnType == JSEXN_NONE, then the error reporter, if any, is called, and no Error object is created. (??? The source code seems to say we ignore the .exnType, actually, but surely I'm just missing something.)

Otherwise, if any JavaScript code is running in cx (for example, if the caller is a JSNative that was called from a script), then an Error object is created and becomes the pending exception. The error reporter is not called yet, because the script still has an opportunity to catch and handle the exception.

Otherwise, no JavaScript code is running in cx. If the JSOPTION_DONT_REPORT_UNCAUGHT option is set, (??? what happens?). Otherwise, (??? what happens?).

See Also