JS_DefineFunction

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_DefineFunction
  • Revision title: JS_DefineFunction
  • Revision id: 89480
  • Created:
  • Creator: Jorend
  • Is current revision? Yes
  • Comment 1 words added, 15 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.
nargs uintN Number of arguments that are passed to the function when it is called.
flags uintN The logical OR of zero or more property attributes.

Description

JS_DefineFunction exposes a C/C++ function to scripts by defining a new method on an existing JavaScript object. It creates the new Function object as though by calling JS_NewFunction, then makes it a method of obj as though by calling JS_DefinePropertyJS_DefineUCFunction is the Unicode version of the function.

name is the name of the property to create in obj. That is, it is the method name that scripts can use to call the new function. It also becomes the name property of the new function object and can be accessed using JS_GetFunctionId.

call is a pointer to the C/C++ function that is to be exposed to JavaScript.

nargs indicates the number of arguments the function expects to receive. This becomes the new function object's length property and can be accessed using JS_GetFunctionArity.

flags is the logical OR of zero or more property attributes, which apply to the new property.

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") }}

JS_CallFunctionName, JS_CallFunctionValue, JS_CompileFunction, JS_DefineFunctions, JS_DefineObject, JS_DefineProperties, JS_DefineProperty, JS_GetFunctionObject, JS_NewFunction

Revision Source

<p>Create a native function and assign it as a property to a specified JS object.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval"><a href="/En/SpiderMonkey/JSAPI_Reference/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/SpiderMonkey/JSAPI_Reference/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>
<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.</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>The logical OR of zero or more <a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes#Property_attributes" title="en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes#Property_attributes">property attributes</a>.</td> </tr> </tbody>
</table>
<h2 id="Description" name="Description">Description</h2>
<p><strong><code>JS_DefineFunction</code></strong> exposes a C/C++ function to scripts by defining a new method on an existing JavaScript object. It creates the new Function object as though by calling <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewFunction" title="en/SpiderMonkey/JSAPI Reference/JS NewFunction"><code>JS_NewFunction</code></a>, then makes it a method of <code>obj</code> as though by calling <a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperty" title="en/SpiderMonkey/JSAPI Reference/JS DefineProperty"><code>JS_DefineProperty</code></a>.  <strong><code>JS_DefineUCFunction</code></strong> is the Unicode version of the function.</p>
<p><code>name</code> is the name of the property to create in <code>obj</code>. That is, it is the method name that scripts can use to call the new function. It also becomes the <a class="internal" href="/en/JavaScript/Reference/Global_Objects/Function/name" title="en/Core JavaScript 1.5 Reference/Global Objects/Function/name"><code>name</code></a> property of the new function object and can be accessed using <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_GetFunctionId" title="En/SpiderMonkey/JSAPI Reference/JS GetFunctionId"><code>JS_GetFunctionId</code></a>.</p>
<p><code>call</code> is a pointer to the C/C++ function that is to be exposed to JavaScript.</p>
<p><code>nargs</code> indicates the number of arguments the function expects to receive. This becomes the new function object's <a class="internal" href="/en/JavaScript/Reference/Global_Objects/Function/length" title="En/Core JavaScript 1.5 Reference/Global Objects/Function/Length"><code>length</code></a> property and can be accessed using <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetFunctionArity" title="en/JS_GetFunctionArity">JS_GetFunctionArity</a></code>.</p>
<p><code>flags</code> is the logical OR of zero or more <a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes#Property_attributes" title="en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes#Property_attributes">property attributes</a>, which apply to the new property.</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 id="See_Also" 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/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_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_GetFunctionObject" title="en/JS_GetFunctionObject">JS_GetFunctionObject</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_NewFunction" title="en/JS_NewFunction">JS_NewFunction</a></p>
Revert to this revision