JS_AddArgumentFormatter 编辑

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);

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);

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.

See Also

• bug 788359