michael@0: /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
michael@0:  * vim: set ts=8 sts=4 et sw=4 tw=99:
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: /*
michael@0:  * JS runtime exception classes.
michael@0:  */
michael@0: 
michael@0: #ifndef jsexn_h
michael@0: #define jsexn_h
michael@0: 
michael@0: #include "jsapi.h"
michael@0: #include "NamespaceImports.h"
michael@0: 
michael@0: namespace js {
michael@0: class ErrorObject;
michael@0: 
michael@0: JSErrorReport *
michael@0: CopyErrorReport(JSContext *cx, JSErrorReport *report);
michael@0: 
michael@0: JSString *
michael@0: ComputeStackString(JSContext *cx);
michael@0: }
michael@0: 
michael@0: /*
michael@0:  * Given a JSErrorReport, check to see if there is an exception associated with
michael@0:  * the error number.  If there is, then create an appropriate exception object,
michael@0:  * set it as the pending exception, and set the JSREPORT_EXCEPTION flag on the
michael@0:  * error report.  Exception-aware host error reporters should probably ignore
michael@0:  * error reports so flagged.
michael@0:  *
michael@0:  * Return true if cx->throwing and cx->exception were set.
michael@0:  *
michael@0:  * This means that:
michael@0:  *
michael@0:  *   - If the error is successfully converted to an exception and stored in
michael@0:  *     cx->exception, the return value is true. This is the "normal", happiest
michael@0:  *     case for the caller.
michael@0:  *
michael@0:  *   - If we try to convert, but fail with OOM or some other error that ends up
michael@0:  *     setting cx->throwing to true and setting cx->exception, then we also
michael@0:  *     return true (because callers want to treat that case the same way).
michael@0:  *     The original error described by *reportp typically won't be reported
michael@0:  *     anywhere; instead OOM is reported.
michael@0:  *
michael@0:  *   - If *reportp is just a warning, or the error code is unrecognized, or if
michael@0:  *     we decided to do nothing in order to avoid recursion, then return
michael@0:  *     false. In those cases, this error is just being swept under the rug
michael@0:  *     unless the caller decides to call CallErrorReporter explicitly.
michael@0:  */
michael@0: extern bool
michael@0: js_ErrorToException(JSContext *cx, const char *message, JSErrorReport *reportp,
michael@0:                     JSErrorCallback callback, void *userRef);
michael@0: 
michael@0: /*
michael@0:  * Called if a JS API call to js_Execute or js_InternalCall fails; calls the
michael@0:  * error reporter with the error report associated with any uncaught exception
michael@0:  * that has been raised.  Returns true if there was an exception pending, and
michael@0:  * the error reporter was actually called.
michael@0:  *
michael@0:  * The JSErrorReport * that the error reporter is called with is currently
michael@0:  * associated with a JavaScript object, and is not guaranteed to persist after
michael@0:  * the object is collected.  Any persistent uses of the JSErrorReport contents
michael@0:  * should make their own copy.
michael@0:  *
michael@0:  * The flags field of the JSErrorReport will have the JSREPORT_EXCEPTION flag
michael@0:  * set; embeddings that want to silently propagate JavaScript exceptions to
michael@0:  * other contexts may want to use an error reporter that ignores errors with
michael@0:  * this flag.
michael@0:  */
michael@0: extern bool
michael@0: js_ReportUncaughtException(JSContext *cx);
michael@0: 
michael@0: extern JSErrorReport *
michael@0: js_ErrorFromException(JSContext *cx, js::HandleObject obj);
michael@0: 
michael@0: extern const JSErrorFormatString *
michael@0: js_GetLocalizedErrorMessage(js::ExclusiveContext *cx, void *userRef, const char *locale,
michael@0:                             const unsigned errorNumber);
michael@0: 
michael@0: /*
michael@0:  * Make a copy of errobj parented to scope.
michael@0:  *
michael@0:  * cx must be in the same compartment as scope. errobj may be in a different
michael@0:  * compartment, but it must be an Error object (not a wrapper of one) and it
michael@0:  * must not be one of the prototype objects created by js_InitExceptionClasses
michael@0:  * (errobj->getPrivate() must not be nullptr).
michael@0:  */
michael@0: extern JSObject *
michael@0: js_CopyErrorObject(JSContext *cx, JS::Handle<js::ErrorObject*> errobj, js::HandleObject scope);
michael@0: 
michael@0: static inline JSProtoKey
michael@0: GetExceptionProtoKey(JSExnType exn)
michael@0: {
michael@0:     JS_ASSERT(JSEXN_ERR <= exn);
michael@0:     JS_ASSERT(exn < JSEXN_LIMIT);
michael@0:     return JSProtoKey(JSProto_Error + int(exn));
michael@0: }
michael@0: 
michael@0: #endif /* jsexn_h */