Obsolete since JSAPI 18
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.
Add or remove a format string handler for JS_ConvertArguments
, JS_PushArguments
, JS_ConvertArgumentsVA
, and JS_PushArgumentsVA
.
Syntax
JSBool JS_AddArgumentFormatter(JSContext *cx, const char *format, JSArgumentFormatter formatter); void JS_RemoveArgumentFormatter(JSContext *cx, const char *format);
Name | Type | Description |
---|---|---|
cx |
JSContext * |
The context in which to install the formatter. |
format |
const char * |
The format string prefix that should be handled by formatter , or whose handler should be removed. |
formatter |
JSArgumentFormatter |
The function to be used to convert arguments described by the given format. This function is described in more detail below. |
Description
JS_AddArgumentFormatter
establishes formatter
as the conversion function for format strings beginning with format
in the context cx
. On success, it returns JS_TRUE
. Otherwise it returns JS_FALSE
. (At the moment, JS_AddArgumentFormatter
fails only if there is no memory available to record the registration.)
JS_AddArgumentFormatter
does not copy format
, it points at the string storage allocated by the caller, which is typically a string constant. If format
is in dynamic storage, the caller must keep the string alive until JS_RemoveArgumentFormatter
is called.
JS_RemoveArgumentFormatter
removes any conversion functions associated with format
.
Callback Syntax
JSBool (*JSArgumentFormatter)(JSContext *cx, const char *format, JSBool fromJS, jsval **vpp, va_list *app);
Name | Type | Description |
---|---|---|
cx |
JSContext * |
The context in which the conversion is being performed. |
format |
const char * |
The tail of the format string whose prefix is associated with this formatting function. |
fromJS |
JSBool |
JS_TRUE if the conversion function should convert from jsval values to C values; JS_FALSE if the conversion function should convert from C values to jsval values. |
vpp |
jsval ** |
In-out parameter. A pointer into an array of jsval values. |
app |
va_list * |
In-out parameter. A pointer to an argument pointer, used to retrieve pointers to C values. |
Callback Description
The conversion function should return true on success, and return false after reporting an error or detecting an already-reported error.
For a given format string, for example "AA"
, the formatter is called from JS_ConvertArgumentsVA
like so:
formatter(cx, "AA...", JS_TRUE, &sp, &ap);
sp
points into the arguments array on the JS stack, while ap
points into the stdarg.h
va_list
on the C stack. The JS_TRUE
passed for fromJS
tells the formatter to convert zero or more jsvals at sp
to zero or more C values accessed via pointers-to-values at ap
, updating both sp
(via *vpp
) and ap
(via *app
) to point past the converted arguments and their result pointers on the C stack.
When called from JS_PushArgumentsVA
, the formatter is invoked thus:
formatter(cx, "AA...", JS_FALSE, &sp, &ap);
where JS_FALSE
for fromJS
means to wrap the C values at ap
according to the format specifier and store them at sp
, updating ap
and sp
appropriately.
The "..."
after "AA"
is the rest of the format string that was passed into JS_{Convert,Push}Arguments{,VA}
. The actual format trailing substring used in each Convert
or PushArguments
call is passed to the formatter, so that one such function may implement several formats, in order to share code.