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.