JSNative is the type of many JSAPI callbacks. In particular, APIs such as JS_InitClass and JS_DefineFunctions create custom methods on JavaScript objects that are implemented as JSNative callbacks provided by the application, written in C/C++ code.
The term "native" here refers to C/C++ code as opposed to JavaScript code.
Syntax
typedef bool (* JSNative)(JSContext *cx, unsigned argc, JS::Value *vp);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
The context in which the native function is being called. Provides request. In JS_THREADSAFE builds, the JavaScript engine calls this callback only from within an active request on cx. The callback does not need to call JS_BeginRequest()). |
argc |
unsigned |
The number of arguments supplied to the function by the caller (as opposed to, say, the number of arguments the function is specified to take in its JSFunctionSpec). |
vp |
JS::Value * |
The arguments, the this argument, the return-value slot, and the callee Function object are accessible through this pointer using macros described below. |
Description
JSNative is the type of native implementations of JavaScript functions. Full documentation of how to define a JSNative (or a JSFastNative, the equivalent typedef which preceded it) is available in the API header "js/CallArgs.h" Added in SpiderMonkey 24. This header is new, but the semantics it describes are applicable to all recent SpiderMonkey releases. The preferred way to implement a function is to use the JS::CallArgs structure defined there; the macros providing equivalent functionality are deprecated.
The behavior of a JSNative is implemented using a JS::CallArgs structure Added in SpiderMonkey 17. (This structure is now provided in "js/CallArgs.h" Added in SpiderMonkey 24 as well as through "jsapi.h".) This structure encapsulates access to the callee function, this, the function call's arguments, and the eventual return value.
On success, the callback must set JS::CallArgs::rval() or call JS_SET_RVAL (at least once) and return true. Otherwise it should either report an error (using e.g. JS_ReportError or JS_ReportOutOfMemory) or raise an exception (using JS_SetPendingException), and the callback must return false. (Returning false without reporting an error or raising an exception terminates the script with an uncatchable error. This has limited use cases; it's used to implement Firefox's "slow script" dialog, for example.)
When a JSNative is called, no JSStackFrame is generated. This causes the function not to appear on the stack in JavaScript debuggers. It also means that applications that implement JSCheckAccessOp or JSCheckAccessIdOp in terms of APIs such as JS_FrameIterator and JS_StackFramePrincipals, must take extra care, as the native function's principals will be missing from the stack.