JSPrincipals

From MDC

Defines security information for an object or script.

[edit] Syntax

struct JSPrincipals {
    char *codebase;
    void *(*getPrincipalArray)(JSContext *cx, JSPrincipals *);
    JSBool (*globalPrivilegesEnabled)(JSContext *cx, JSPrincipals *);
    uintN refcount;
    void (*destroy)(JSContext *cx, JSPrincipals *);
};

Name	Type	Description
codebase	char *	Pointer to the codebase for the principal.
getPrincipalArray	void * (*)(JSContext *, JSPrincipals *)	Pointer to the function that returns an array of principal definitions.
globalPrivilegesEnabled	JSBool (*)(JSContext *, JSPrincipals *)	Flag indicating whether principals are enabled globally.
refcount	uintN	Reference count for the principals. Each reference to a principal increments refcount by one. As principal references are dropped, call the destroy method to decrement the reference count and free the principals if they are no longer needed.
destroy	void (*)(JSContext *, JSPrincipals *)	Pointer to the function that decrements the reference count and possibly frees the principals if they are no longer in use.

[edit] Description

JSPrincipals is the abstract base class of all principals objects, the objects that identify the source of a function or script and are used to determine its privileges. A principals object is like a Java CodeSource.

The data content of a principals object is defined by the application, which creates instances of JSPrincipals, initializes their refcount fields to 1, and passes them into the engine through the JS_...ForPrincipals functions. Some examples of security-enhanced API call are JS_CompileScriptForPrincipals, JS_CompileFunctionForPrincipals, and JS_EvaluateScriptForPrincipals. These functions ensure that the given JSPrincipals object is indelibly associated not only with the script being compiled or evaluated, but with all functions ever created by that script or code eval()-ed by it.

codebase points to the common codebase for this object or script. Only objects and scripts that share a common codebase can interact.

getPrincipalArray is a pointer to the function that retrieves the principals for this object or script.

globalPrivilegesEnabled is a flag that indicates whether principals are enabled globally.

refcount is the reference count. This is used for memory management. Each time an object is referenced, refcount must be increased by one. Each time an object is dereferenced, refcount must be decremented by one. When refcount reaches zero, the principals are no longer in use and are destroyed. Use the JSPRINCIPALS_HOLD macro to increment refcount, and use JSPRINCIPALS_DROP to decrement refcount.

LXR ID Search for JSPrincipals