Obsolete since JavaScript 1.8.5
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
Convert any number of arguments to jsvals and store the resulting jsvals in an array.
Syntax
jsval * JS_PushArguments(JSContext *cx, void **markp, const char *format, ...); jsval * JS_PushArgumentsVA(JSContext *cx, void **markp, const char *format, va_list ap);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
The context in which to perform any necessary conversions.
JS_THREADSAFE build, the caller must be in a request on this JSContext. |
markp |
void ** |
Out parameter. On success, *markp receives the internally allocated stack mark which should be passed to JS_PopArguments. |
format |
const char * |
Null-terminated string holding a list of format types to convert the following arguments to. |
... |
various | (in JS_PushArguments) A variable number of arguments to be converted to jsvals. There must be one argument for each argument described in format. |
ap |
va_list |
(in JS_PushArgumentsVA) The list of arguments to be converted to jsvals. There must be one argument for each argument described in format. The type va_list is a standard feature of the C programming language. It is defined in <stdarg.h>. |
Description
JS_PushArguments provides a convenient way to translate a series of native C/C++ values to jsvals with a single function call.
cx is the context for the call. markp points to a void * to hold the internally allocated stack frame pointer to pass back to JS_PopArguments.
format is a sequential character array, where each element of the array indicates the JS type into which to convert the next C/C++ argument. format can contain one or more instances of the following characters, as appropriate:
| Character | Argument type |
|---|---|
b |
JSBool |
c |
uint16 (16-bit, unsigned integer) |
i |
int32 (32-bit, ECMA-compliant signed integer) |
u |
uint32 (32-bit, ECMA-compliant, unsigned integer) |
j |
int32 (32-bit, signed integer) |
d |
jsdouble |
I |
jsdouble (converted to an integer value) |
s |
char * (C string) |
S |
JSString * (Unicode string) |
W |
jschar * (Unicode null-terminated string) |
o |
JSObject * |
f |
JSFunction * |
* |
None. Any asterisks (*) in format are ignored. |
This function also takes in consideration any additional custom types defined in cx using JS_AddArgumentFormatter.
For example, if format is "bIob", then there must be four arguments after format. Their types must be JSBool, jsdouble, JSObject *, and JSBool. If successful, JS_PushArguments would return a pointer to the first element of an array of four jsvals: a boolean, a number, an object (or null), and a boolean.
On success, JS_PushArguments fills in the supplied markp pointer and returns a pointer to the first element of an array of jsval which are automatically rooted as necessary (protected from the GC temporarily). The application must call JS_PopArguments using the supplied markp stack pointer when done with this stack frame, to free the memory and unroot the jsvals.
On error or exception, JS_PushArguments returns NULL.
To perform the opposite conversion, converting an array of jsvals to various native C types, use JS_ConvertArguments.