JSNative

  • Revision slug: SpiderMonkey/JSAPI_Reference/JSNative
  • Revision title: JSNative
  • Revision id: 105111
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 1 words added, 1 words removed; page display name reset to default

Revision Content

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 JSBool (*JSNative)(JSContext *cx, JSObject *obj, uintN argc, jsval *argv, jsval *rval);
Name Type Description
cx JSContext * Pointer to the JS context in which execution is taking place. {{ Jsapi_provides_request() }}
obj JSObject * Pointer to the this object supplied to the function at execution time.
argc uintN The actual number of arguments supplied to the function, as opposed to possibly the number of arguments the function is specified to take in its JSFunctionSpec.
argv jsval * The arguments provided to the function, along with a few other values noted below.
rval jsval * Out parameter. On success, the callback stores a return value in *rval. Defaults to point to JSVAL_VOID, in case this function does not return a value.

Description

JSNative is the type of native implementations of JavaScript functions.

On success, the callback must return JS_TRUE. Otherwise it must either report an error (using e.g. JS_ReportError or JS_ReportOutOfMemory) or raise an exception (using JS_SetPendingException), and the callback must return JS_FALSE.

When a JSNative is invoked by SpiderMonkey, the following locations are GC roots:

  • JS_ARGV_CALLEE(argv), which initially contains a reference to the JS Function object for the function being executed.
  • argv{{ mediawiki.external(-1) }}, which initially contains the this argument.
  • argv{{ mediawiki.external("0") }} through argv{{ mediawiki.external('argc - 1') }}, which initially contain the actual arguments passed to the function.
  • argv{{ mediawiki.external('argc') }} through argv{{ mediawiki.external('nargs - 1') }}, if argc < nargs. Here nargs is a parameter specified when the function was defined (either JSFunctionSpec.nargs or the nargs parameter to JS_FS, JS_DefineFunction, or JS_NewFunction). If present, these locations initially contain JSVAL_VOID.
  • argv{{ mediawiki.external('nargs') }} through argv{{ mediawiki.external('nargs + extra - 1') }}, where extra is (JSFunctionSpec.extra & 0xFFFF) and nargs is as above. If present, these locations initially contain JSVAL_VOID.

JSNatives are free to assign to any of these GC roots. Calling JS_ConvertArguments does this, for example.

Revision Source

<p><strong><code>JSNative</code></strong> is the type of many JSAPI callbacks. In particular, APIs such as <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_InitClass" title="en/SpiderMonkey/JSAPI_Reference/JS_InitClass">JS_InitClass</a></code> and <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineFunctions" title="en/SpiderMonkey/JSAPI_Reference/JS_DefineFunctions">JS_DefineFunctions</a></code> create custom methods on JavaScript objects that are implemented as <code>JSNative</code> callbacks provided by the application, written in C/C++ code.
</p><p>The term "native" here refers to C/C++ code as opposed to JavaScript code.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval">typedef <a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="En/SpiderMonkey/JSAPI_Reference/JSBool">JSBool</a> (*<strong>JSNative</strong>)(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/SpiderMonkey/JSAPI_Reference/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/SpiderMonkey/JSAPI_Reference/JSObject">JSObject</a> *obj, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/SpiderMonkey/JSAPI_Reference/jsint">uintN</a> argc, <a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="En/SpiderMonkey/JSAPI_Reference/Jsval">jsval</a> *argv, <a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="En/SpiderMonkey/JSAPI_Reference/Jsval">jsval</a> *rval);
</pre>
<table class="fullwidth-table">
<tbody><tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>cx</code></td>
<td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/SpiderMonkey/JSAPI_Reference/JSRuntime">JSContext</a> *</code></td>
<td>Pointer to the JS context in which execution is taking place.
{{ Jsapi_provides_request() }}</td>
</tr>
<tr>
<td><code>obj</code></td>
<td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/SpiderMonkey/JSAPI_Reference/JSObject">JSObject</a> *</code></td>
<td>Pointer to the <code>this</code> object supplied to the function at execution time.</td>
</tr>
<tr>
<td><code>argc</code></td>
<td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/SpiderMonkey/JSAPI_Reference/jsint">uintN</a></code></td>
<td>The actual number of arguments supplied to the function, as opposed to possibly the number of arguments the function is specified to take in its <a href="/en/JSFunctionSpec" title="en/JSFunctionSpec">JSFunctionSpec</a>.</td>
</tr>
<tr>
<td><code>argv</code></td>
<td><code><a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="En/SpiderMonkey/JSAPI_Reference/Jsval">jsval</a> *</code></td>
<td>The arguments provided to the function, along with a few other values noted below.</td>
</tr>
<tr>
<td><code>rval</code></td>
<td><code><a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="En/SpiderMonkey/JSAPI_Reference/Jsval">jsval</a> *</code></td>
<td>Out parameter. On success, the callback stores a return value in <code>*rval</code>. Defaults to point to <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID">JSVAL_VOID</a></code>, in case this function does not return a value.</td>
</tr>
</tbody></table>
<h2 name="Description">Description</h2>
<p><code>JSNative</code> is the type of native implementations of JavaScript functions.</p>
<p>On success, the callback must return <code>JS_TRUE</code>. Otherwise it must either report an error (using e.g. <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_ReportError" title="en/SpiderMonkey/JSAPI_Reference/JS_ReportError">JS_ReportError</a></code> or <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_ReportOutOfMemory" title="en/SpiderMonkey/JSAPI_Reference/JS_ReportOutOfMemory">JS_ReportOutOfMemory</a></code>) or raise an exception (using <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetPendingException" title="en/SpiderMonkey/JSAPI_Reference/JS_SetPendingException">JS_SetPendingException</a></code>), and the callback must return <code>JS_FALSE</code>.</p>
<p>When a <code>JSNative</code> is invoked by SpiderMonkey, the following locations are GC roots:</p>
<ul> <li><code><a href="/en/JS_ARGV_CALLEE" title="en/JS_ARGV_CALLEE">JS_ARGV_CALLEE</a>(argv)</code>, which initially contains a reference to the JS <code>Function</code> object for the function being executed.</li> <li><code>argv{{ mediawiki.external(-1) }}</code>, which initially contains the <code>this</code> argument.</li> <li><code>argv{{ mediawiki.external("0") }}</code> through <code>argv{{ mediawiki.external('argc - 1') }}</code>, which initially contain the actual arguments passed to the function.</li> <li><code>argv{{ mediawiki.external('argc') }}</code> through <code>argv{{ mediawiki.external('nargs - 1') }}</code>, if <code>argc &lt; nargs</code>. Here <code>nargs</code> is a parameter specified when the function was defined (either <code><a href="/En/SpiderMonkey/JSAPI_Reference/JSFunctionSpec" title="en/JSFunctionSpec">JSFunctionSpec</a>.nargs</code> or the <code>nargs</code> parameter to <code><a href="/en/JS_FS" title="en/JS_FS">JS_FS</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineFunction" title="en/SpiderMonkey/JSAPI_Reference/JS_DefineFunction">JS_DefineFunction</a></code>, or <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewFunction" title="en/SpiderMonkey/JSAPI_Reference/JS_NewFunction">JS_NewFunction</a></code>). If present, these locations initially contain <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID" title="en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID">JSVAL_VOID</a></code>.</li> <li><code>argv{{ mediawiki.external('nargs') }}</code> through <code>argv{{ mediawiki.external('nargs + extra - 1') }}</code>, where <code>extra</code> is <code>(<a href="/En/SpiderMonkey/JSAPI_Reference/JSFunctionSpec" title="en/JSFunctionSpec">JSFunctionSpec</a>.extra &amp; 0xFFFF)</code> and <code>nargs</code> is as above. If present, these locations initially contain <code>JSVAL_VOID</code>.</li>
</ul>
<p><code>JSNative</code>s are free to assign to any of these GC roots. Calling <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_ConvertArguments" title="en/SpiderMonkey/JSAPI_Reference/JS_ConvertArguments">JS_ConvertArguments</a></code> does this, for example.</p>
Revert to this revision