JS_DefineFunction

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_DefineFunction
  • Revision title: JS_DefineFunction
  • Revision id: 89472
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment 14 words removed

Revision Content

Create a native function and assign it as a property to a specified JS object.

Syntax

JSFunction * JS_DefineFunction(JSContext *cx, JSObject *obj,
    const char *name, JSNative call, uintN nargs, uintN flags);

JSFunction * JS_DefineUCFunction(JSContext *cx, JSObject *obj,
    const jschar *name, size_t namelen, JSNative call,
    uintN nargs, uintN attrs);


Name Type Description
cx JSContext * The context in which to define the function. {{ Jsapi-requires-request() }}
obj JSObject * Object for which to define a function as a property (method).
name const char * or const jschar * Name to assign to the function.
call JSNative The native C/C++ function to be wrapped by the new function. If flags contains the JSFUN_FAST_NATIVE bit, this is actually a JSFastNative function pointer, reinterpret-cast to JSNative.
nargs uintN Number of arguments that are passed to the function when it is called.
flags uintN Function attributes.

Description

JS_DefineFunction defines a single function and assigns it as a property (method) to a specified object, obj. JS_DefineUCFunction is the Unicode version of the function.

name is the name to assign to the function in the object. call is a built-in, native C call that is wrapped by your function.

nargs indicates the number of arguments the function expects to receive. This becomes the new function object's arity property (see JS_GetFunctionArity). For JSFastNatives, that is the only effect. For JSNatives, the JavaScript engine also guarantees that whenever it calls call, the argv array contains at least nargs values, even if fewer actual arguments were passed (that is, even if argc < nargs). The argv elements for any missing arguments are filled with JSVAL_VOID.

flags lists the attributes to apply to the function. Currently documented attributes, JSFUN_BOUND_METHOD and JSFUN_GLOBAL_PARENT, are deprecated and should no longer be used. They continue to be supported only for existing applications that already depend on them. The JSFUN_FAST_NATIVE bit indicates that call is a JSFastNative; the JavaScript engine will call it appropriately.

On success, JS_DefineFunction and JS_DefineUCFunction return a pointer to the new function. On error or exception, they return NULL.

See Also

{{ LXRSearch("ident", "i", "JS_DefineFunction") }}
{{ LXRSearch("ident", "i", "JS_DefineUCFunction") }}

JSFUN_BOUND_METHOD, JSFUN_GLOBAL_PARENT, JS_CallFunction, JS_CallFunctionName, JS_CallFunctionValue, JS_CompileFunction, JS_DecompileFunction, JS_DecompileFunctionBody, JS_DefineConstDoubles, JS_DefineElement, JS_DefineFunctions, JS_DefineObject, JS_DefineProperties, JS_DefineProperty, JS_DefinePropertyWithTinyId, JS_GetFunctionObject, JS_NewFunction, JS_SetBranchCallback, JS_ValueToFunction

Revision Source

<p>Create a native function and assign it as a property to a specified JS object.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval"><a href="/en/JSFunction" title="en/JSFunction">JSFunction</a> * <strong>JS_DefineFunction</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *obj,
    const char *name, <a href="/en/SpiderMonkey/JSAPI_Reference/JSNative" title="en/JSNative">JSNative</a> call, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> nargs, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> flags);

<a href="/en/JSFunction" title="en/JSFunction">JSFunction</a> * <strong>JS_DefineUCFunction</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *obj,
    const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *name, size_t namelen, <a href="/en/SpiderMonkey/JSAPI_Reference/JSNative" title="en/JSNative">JSNative</a> call,
    <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> nargs, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> attrs);
</pre>
<p><br>
</p>
<table class="fullwidth-table">
<tbody><tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>cx</code></td>
<td><code>JSContext *</code></td>
<td>The context in which to define the function.
{{ Jsapi-requires-request() }}</td>
</tr>
<tr>
<td><code>obj</code></td>
<td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *</code></td>
<td>Object for which to define a function as a property (method).</td>
</tr>
<tr>
<td><code>name</code></td>
<td><code>const char *</code> <em>or</em> <code>const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *</code></td>
<td>Name to assign to the function.</td>
</tr>
<tr>
<td><code>call</code></td>
<td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSNative" title="en/JSNative">JSNative</a></code></td>
<td>The native C/C++ function to be wrapped by the new function.
If <code>flags</code> contains the <code><a href="/en/JSFUN_FAST_NATIVE" title="en/JSFUN_FAST_NATIVE">JSFUN_FAST_NATIVE</a></code> bit, this is actually a <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSFastNative" title="en/JSFastNative">JSFastNative</a></code> function pointer, reinterpret-cast to <code>JSNative</code>.</td>
</tr>
<tr>
<td><code>nargs</code></td>
<td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a></code></td>
<td>Number of arguments that are passed to the function when it is called.</td>
</tr>
<tr>
<td><code>flags</code></td>
<td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a></code></td>
<td>Function attributes.</td>
</tr>
</tbody></table>
<h2 name="Description"> Description </h2>
<p><code>JS_DefineFunction</code> defines a single function and assigns it as a property (method) to a specified object, <code>obj</code>. <code>JS_DefineUCFunction</code> is the Unicode version of the function.
</p><p><code>name</code> is the name to assign to the function in the object. <code>call</code> is a built-in, native C call that is wrapped by your function.
</p><p><code>nargs</code> indicates the number of arguments the function expects to receive. This becomes the new function object's <code>arity</code> property (see <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetFunctionArity" title="en/JS_GetFunctionArity">JS_GetFunctionArity</a></code>). For <code>JSFastNative</code>s, that is the only effect. For <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSNative" title="en/JSNative">JSNative</a></code>s, the JavaScript engine also guarantees that whenever it calls <code>call</code>, the <code>argv</code> array contains at least <code>nargs</code> values, even if fewer actual arguments were passed (that is, even if <code>argc &lt; nargs</code>). The <code>argv</code> elements for any missing arguments are filled with <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSVAL_VOID" title="en/JSVAL_VOID">JSVAL_VOID</a></code>.
</p><p><code>flags</code> lists the attributes to apply to the function. Currently documented attributes, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSFUN_BOUND_METHOD" title="en/JSFUN_BOUND_METHOD">JSFUN_BOUND_METHOD</a></code> and <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSFUN_GLOBAL_PARENT" title="en/JSFUN_GLOBAL_PARENT">JSFUN_GLOBAL_PARENT</a></code>, are deprecated and should no longer be used. They continue to be supported only for existing applications that already depend on them. The <code><a href="/en/JSFUN_FAST_NATIVE" title="en/JSFUN_FAST_NATIVE">JSFUN_FAST_NATIVE</a></code> bit indicates that <code>call</code> is a <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSFastNative" title="en/JSFastNative">JSFastNative</a></code>; the JavaScript engine will call it appropriately.
</p><p>On success, <code>JS_DefineFunction</code> and <code>JS_DefineUCFunction</code> return a pointer to the new function. On error or exception, they return <code>NULL</code>.
</p>
<h2 name="See_Also"> See Also </h2>
<p>{{ LXRSearch("ident", "i", "JS_DefineFunction") }}<br>
{{ LXRSearch("ident", "i", "JS_DefineUCFunction") }}
</p><p><a href="/en/SpiderMonkey/JSAPI_Reference/JSFUN_BOUND_METHOD" title="en/JSFUN_BOUND_METHOD">JSFUN_BOUND_METHOD</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JSFUN_GLOBAL_PARENT" title="en/JSFUN_GLOBAL_PARENT">JSFUN_GLOBAL_PARENT</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_CallFunction" title="en/JS_CallFunction">JS_CallFunction</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_CallFunctionName" title="en/JS_CallFunctionName">JS_CallFunctionName</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_CallFunctionValue" title="en/JS_CallFunctionValue">JS_CallFunctionValue</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_CompileFunction" title="en/JS_CompileFunction">JS_CompileFunction</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DecompileFunction" title="en/JS_DecompileFunction">JS_DecompileFunction</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DecompileFunctionBody" title="en/JS_DecompileFunctionBody">JS_DecompileFunctionBody</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineConstDoubles" title="en/JS_DefineConstDoubles">JS_DefineConstDoubles</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineElement" title="en/JS_DefineElement">JS_DefineElement</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineFunctions" title="en/JS_DefineFunctions">JS_DefineFunctions</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineObject" title="en/JS_DefineObject">JS_DefineObject</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperties" title="en/JS_DefineProperties">JS_DefineProperties</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperty" title="en/JS_DefineProperty">JS_DefineProperty</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefinePropertyWithTinyId" title="en/JS_DefinePropertyWithTinyId">JS_DefinePropertyWithTinyId</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetFunctionObject" title="en/JS_GetFunctionObject">JS_GetFunctionObject</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewFunction" title="en/JS_NewFunction">JS_NewFunction</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetBranchCallback" title="en/JS_SetBranchCallback">JS_SetBranchCallback</a>,
<a href="/en/SpiderMonkey/JSAPI_Reference/JS_ValueToFunction" title="en/JS_ValueToFunction">JS_ValueToFunction</a>
</p>
Revert to this revision