The C-level API

The C-level extensibility API consists of the following functions:

typedef JSBool (*JSNative)(JSContext *cx, JSObject *obj, unsigned int argc, jsval *argv, jsval *rval)

Description

This function signature describes C-level implementations of JavaScript functions in the following situations:

• The cx pointer is a pointer to an opaque JSContext structure, which must be passed to some of the functions in the JavaScript API. This variable holds the interpreter's execution context.

• The obj pointer is a pointer to the object in whose context the script executes. While the script is running, the this keyword is equal to this object.

• The argc integer is the number of arguments being passed to the function.

• The argv pointer is a pointer to an array of jsval structures. The array is argc elements in length.

• The rval pointer is a pointer to a single jsval structure. The function's return value should be written to *rval.

The function returns JS_TRUE if successful; JS_FALSE otherwise. If the function returns JS_FALSE, the current script stops executing and an error message appears.

JSBool JS_DefineFunction()

Description

This function registers a C-level function with the JavaScript interpreter in Dreamweaver. After the JS_DefineFunction() function registers the C-level function that you specify in the call argument, you can invoke it in a JavaScript script by referring to it with the name that you specify in the name argument. The name is case-sensitive.

Typically, this function is called from the MM_Init() function, which Dreamweaver calls during startup.

Arguments

 char *name, JSNative call, unsigned int nargs 

• The name argument is the name of the function as it is exposed to JavaScript.

• The call argument is a pointer to a C-level function. The function must accept the same arguments as readContentsOfFile, and it must return a JSBool, which indicates success or failure.

• The nargs argument is the number of arguments that the function expects to receive.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

char *JS_ValueToString()

Description

This function extracts a function argument from a jsval structure, converts it to a string, if possible, and passes the converted value back to the caller.

NOTE

Do not modify the returned buffer pointer or you might corrupt the data structures of the JavaScript interpreter. To change the string, you must copy the characters into another buffer and create a new JavaScript string.

Arguments

 JSContext *cx, jsval v, unsigned int *pLength 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The v argument is the jsval structure from which the string is to be extracted.

• The pLength argument is a pointer to an unsigned integer. This function sets *plength equal to the length of the string in bytes.

Returns

A pointer that points to a null-terminated string if successful or to a null value on failure. The calling routine must not free this string when it finishes.

JSBool JS_ValueToInteger()

Description

This function extracts a function argument from a jsval structure, converts it to an integer (if possible), and passes the converted value back to the caller.

Arguments

 JSContext *cx, jsval v, long *lp 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The v argument is the jsval structure from which the integer is to be extracted.

• The lp argument is a pointer to a 4-byte integer. This function stores the converted value in *lp.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSBool JS_ValueToDouble()

Description

This function extracts a function argument from a jsval structure, converts it to a double (if possible), and passes the converted value back to the caller.

Arguments

 JSContext *cx, jsval v, double *dp 

• The cx argument is the opaque JSContext pointer that passed to the JavaScript function.

• The v argument is the jsval structure from which the double is to be extracted.

• The dp argument is a pointer to an 8-byte double. This function stores the converted value in *dp.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSBool JS_ValueToBoolean()

Description

This function extracts a function argument from a jsval structure, converts it to a Boolean value (if possible), and passes the converted value back to the caller.

Arguments

 JSContext *cx, jsval v, JSBool *bp 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The v argument is the jsval structure from which the Boolean value is to be extracted.

• The bp argument is a pointer to a JSBool Boolean value. This function stores the converted value in *bp.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSBool JS_ValueToObject()

Description

This function extracts a function argument from a jsval structure, converts it to an object (if possible), and passes the converted value back to the caller. If the object is an array, use JS_GetArrayLength() and JS_GetElement() to read its contents.

Arguments

 JSContext *cx, jsval v, JSObject **op 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The v argument is the jsval structure from which the object is to be extracted.

• The op argument is a pointer to a JSObject pointer. This function stores the converted value in *op.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSBool JS_StringToValue()

Description

This function stores a string return value in a jsval structure. It allocates a new JavaScript string object.

Arguments

 JSContext *cx, char *bytes, size_t sz, jsval *vp 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The bytes argument is the string to be stored in the jsval structure. The string data is copied, so the caller should free the string when it is not needed. If the string size is not specified (see the sz argument), the string must be null-terminated.

• The sz argument is the size of the string, in bytes. If sz is 0, the length of the null-terminated string is computed automatically.

• The vp argument is a pointer to the jsval structure into which the contents of the string should be copied.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSBool JS_DoubleToValue()

Description

This function stores a floating-point number return value in a jsval structure.

Arguments

 JSContext *cx, double dv, jsval *vp 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The dv argument is an 8-byte floating-point number.

• The vp argument is a pointer to the jsval structure into which the contents of the double should be copied.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSVal JS_BooleanToValue()

Description

This function stores a Boolean return value in a jsval structure.

Arguments

 JSBool bv 

• The bv argument is a Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

Returns

A JSVal structure that contains the Boolean value that passes to the function as an argument.

JSVal JS_IntegerToValue()

Description

This function converts a long integer value to JSVal structure.

Arguments

 lv 

• The lv argument is the long integer value that you want to convert to a jsval structure.

Returns

A JSVal structure that contains the integer that was passed to the function as an argument.

JSVal JS_ObjectToValue()

Description

This function stores an object return value in a JSVal. Use JS_ NewArrayObject() to create an array object; use JS_SetElement() to define its contents.

Arguments

 JSObject *obj 

• The obj argument is a pointer to the JSObject object that you want to convert to a JSVal structure.

Returns

A JSVal structure that contains the object that you passed to the function as an argument.

char *JS_ObjectType()

Description

Given an object reference, the JS_ObjectType() function returns the class name of the object. For example, if the object is a DOM object, the function returns "Document". If the object is a node in the document, the function returns "Element". For an array object, the function returns "Array".

NOTE

Do not modify the returned buffer pointer or you might corrupt the data structures of the JavaScript interpreter.

Arguments

 JSObject *obj 

• Typically, this argument is passed in and converted using the JS_ValueToObject() function.

Returns

A pointer to a null-terminated string. The caller should not free this string when it finishes.

JSObject *JS_NewArrayObject()

Description

This function creates a new object that contains an array of JSVals.

Arguments

 JSContext *cx, unsigned int length, jsval *v 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The length argument is the number of elements that the array can hold.

• The v argument is an optional pointer to the jsvals to be stored in the array. If the return value is not null, v is an array that contains length elements. If the return value is null, the initial content of the array object is undefined and can be set using the JS_SetElement() function.

Returns

A pointer to a new array object or the value null upon failure.

long JS_GetArrayLength()

Description

Given a pointer to an array object, this function gets the number of elements in the array.

Arguments

 JSContext *cx, JSObject *obj 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The obj argument is a pointer to an array object.

Returns

The number of elements in the array or -1 upon failure.

JSBool JS_GetElement()

Description

This function reads a single element of an array object.

Arguments

 JSContext *cx, JSObject *obj, unsigned int index, jsval *v 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The obj argument is a pointer to an array object.

• The index argument is an integer index into the array. The first element is index 0, and the last element is index (length - 1).

• The v argument is a pointer to a jsval where the contents of the jsval structure in the array should be copied.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSBool JS_SetElement()

Description

This function writes a single element of an array object.

Arguments

 JSContext *cx, JSObject *obj, unsigned int index, jsval *v 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The obj argument is a pointer to an array object.

• The index argument is an integer index into the array. The first element is index 0, and the last element is index (length - 1).

• The v argument is a pointer to a jsval structure whose contents should be copied to the jsval in the array.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSBool JS_ExecuteScript()

Description

This function compiles and executes a JavaScript string. If the script generates a return value, it returns in *rval.

Arguments

 JSContext *cx, JSObject *obj, char *script, unsigned int sz, jsval *rval 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The obj argument is a pointer to the object in whose context the script executes. While the script is running, the this keyword is equal to this object. Usually this is the JSObject pointer that passes to the JavaScript function.

• The script argument is a string that contains JavaScript code. If the string size is not specified (see the sz argument), the string must be null-terminated.

• The sz argument is the size of the string, in bytes. If sz is 0, the length of the null-terminated string is computed automatically.

• The rval argument is a pointer to a single jsval structure. The function's return value is stored in *rval.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

JSBool JS_ReportError()

Description

This function describes the reason for a script error. Call this function before returning the value JS_FALSE for a script error to give the user information about why the script failed (for example, "wrong number of arguments").

Arguments

 JSContext *cx, char *error, size_t sz 

• The cx argument is the opaque JSContext pointer that passes to the JavaScript function.

• The error argument is a string that contains the error message. The string is copied, so the caller should free the string when it is not needed. If the string size is not specified (see the sz argument), the string must be null-terminated.

• The sz argument is the size of the string, in bytes. If sz is 0, the length of the null-terminated string is computed automatically.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.