Obsolete since JSAPI 17
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.

JSObjectPrincipalsFinder is the type of a security callback that can be configured using JS_SetObjectPrincipalsFinderJSAPI 1.8 and earlier or JS_SetRuntimeSecurityCallbacksAdded in SpiderMonkey 1.8.1.

Callback syntax

typedef JSPrincipals *
(* JSObjectPrincipalsFinder)(JSContext *cx, JSObject *obj);
Name Type Description
cx JSContext * The context in which to find principals.
obj JSObject * The object whose principals are needed.

Description

The JavaScript engine calls this callback to obtain principals for a JSPrincipals.subsume check.

For example, when a watchpoint triggers, the engine calls the callback, passing the watchpoint handler, to ensure that watchpoint handlers are invoked only when the watcher is permitted to watch the currently executing script.

Another example: when the Function constructor is called, the JavaScript engine calls the object principals finder callback to obtain principals for the local scope object, to check that the caller has access to that object.

The two debugger functions JS_StackFramePrincipals and JS_EvalFramePrincipals also use this callback. Since it is very common for JSObjectOps.checkAccess or JSClass.checkAccess hooks to call these functions, the object principals finder callback is a key security feature.

The callback returns a pointer to the principals associated with obj, possibly via the immutable parent chain leading from obj to a top-level container (such as a window object in the DOM). If there are no principals associated with obj, return NULL. Therefore NULL does not mean an error was reported; in no event should an error be reported or an exception be thrown by this callback's implementation.

The callback should not call JSPRINCIPALS_HOLD.

See Also