JSPrincipals

  • Revision slug: SpiderMonkey/JSAPI_Reference/JSPrincipals
  • Revision title: JSPrincipals
  • Revision id: 146563
  • Created:
  • Creator: Dria
  • Is current revision? No
  • Comment

Revision Content

Summary

Data Structure

Defines security information for an object or script.

Syntax

typedef struct JSPrincipals {
    char *codebase;
    void *(*getPrincipalArray)(JSContext *cx,
       struct JSPrincipals *);
    JSBool (*globalPrivilegesEnabled)(JSContext *cx,
       struct JSPrincipals *);
    uintN refcount;
    void (*destroy)(JSContext *cx, struct JSPrincipals *);
} JSPrincipals;
Name Type Description
*codebase char Pointer to the codebase for the principal.
*getPrincipalArray void Pointer to the function that returns an array of principal definitions.
*globalPrivilegesEnabled JSBool 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 Pointer to the function that decrements the reference count and possibly frees the principals if they are no longer in use.

Description

JSPrincipals is a structure that defines the connection to security data for an object or script. Security data is defined independently of the JS engine, but is passed to the engine through the JSPrincipals structure. This structure is passed as an argument to versions of API calls that compile and evaluate scripts and functions that depend on a security model. Some examples of security-enhanced API call are JS_CompileScriptForPrincipals, JS_CompileFunctionForPrincipals, and JS_EvaluateScriptForPrincipals.

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 used to maintain active principals. 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 is zero, the principals are no longer in use and are destroyed. Use the JSPRINCIPALS_HOLD macro to increment refcount, and use JS_PRINCIPALS_DROP to decrement refcount.

See Also

Groups Data Structures
Documents LXR ID Search
Entries

JSPRINCIPALS_DROP, JSPRINCIPALS_HOLD, JS_CompileFunctionForPrincipals, JS_CompileScriptForPrincipals, JS_CompileUCFunctionForPrincipals, JS_CompileUCScriptForPrincipals, JS_EvaluateScriptForPrincipals

Revision Source

<p>
</p>
<h3 name="Summary"> Summary </h3>
<p><b>Data Structure</b>
</p><p>Defines security information for an object or script.
</p>
<h3 name="Syntax"> Syntax </h3>
<pre>typedef struct JSPrincipals {
    char *codebase;
    void *(*getPrincipalArray)(JSContext *cx,
       struct JSPrincipals *);
    JSBool (*globalPrivilegesEnabled)(JSContext *cx,
       struct JSPrincipals *);
    uintN refcount;
    void (*destroy)(JSContext *cx, struct JSPrincipals *);
} JSPrincipals;
</pre>
<table class="fullwidth-table">
<tbody><tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>*codebase</code></td>
<td><code>char</code></td>
<td>Pointer to the codebase for the principal.</td>
</tr>
<tr>
<td><code>*getPrincipalArray</code></td>
<td><code>void</code></td>
<td>Pointer to the function that returns an array of principal definitions.</td>
</tr>
<tr>
<td><code>*globalPrivilegesEnabled</code></td>
<td><code>JSBool</code></td>
<td>Flag indicating whether principals are enabled globally.</td>
</tr>
<tr>
<td><code>refcount</code></td>
<td><code>uintN</code></td>
<td>Reference count for the principals.  Each reference to a principal increments <code>refcount</code> by one.  As principal references are dropped, call the <code>destroy</code> method to decrement the reference count and free the principals if they are no longer needed.</td>
</tr>
<tr>
<td><code>*destroy</code></td>
<td><code>void</code></td>
<td>Pointer to the function that decrements the reference count and possibly frees the principals if they are no longer in use.</td>
</tr>
</tbody></table>
<h3 name="Description"> Description </h3>
<p><code>JSPrincipals</code> is a structure that defines the connection to security data for an object or script. Security data is defined independently of the JS engine, but is passed to the engine through the <code>JSPrincipals</code> structure. This structure is passed as an argument to versions of API calls that compile and evaluate scripts and functions that depend on a security model. Some examples of security-enhanced API call are <code><a href="en/JSAPI_Reference/JS_CompileScriptForPrincipals">JS_CompileScriptForPrincipals</a></code>, <code><a href="en/JSAPI_Reference/JS_CompileFunctionForPrincipals">JS_CompileFunctionForPrincipals</a></code>, and <code><a href="en/JSAPI_Reference/JS_EvaluateScriptForPrincipals">JS_EvaluateScriptForPrincipals</a></code>.
</p><p><code>codebase</code> points to the common codebase for this object or script. Only objects and scripts that share a common codebase can interact.
</p><p><code>getPrincipalArray</code> is a pointer to the function that retrieves the principals for this object or script.
</p><p><code>globalPrivilegesEnabled</code> is a flag that indicates whether principals are enabled globally.
</p><p><code>refcount</code> is used to maintain active principals. Each time an object is referenced, <code>refcount</code> must be increased by one. Each time an object is dereferenced, <code>refcount</code> must be decremented by one. When <code>refcount</code> is zero, the principals are no longer in use and are destroyed. Use the <code><a href="en/JSAPI_Reference/JSPRINCIPALS_HOLD">JSPRINCIPALS_HOLD</a></code> macro to increment <code>refcount</code>, and use <code><a href="en/JSAPI_Reference/JS_PRINCIPALS_DROP">JS_PRINCIPALS_DROP</a></code> to decrement <code>refcount</code>.
</p>
<h3 name="See_Also"> See Also </h3>
<table class="fullwidth-table">
<tbody><tr>
<td>Groups</td>
<td><a href="en/JSAPI_Reference#Data_Structures">Data Structures</a></td>
</tr>
<tr>
<td>Documents</td>
<td><a class="external" href="http://lxr.mozilla.org/seamonkey/ident?i=JSPrincipals">LXR ID Search</a></td>
</tr>
<tr>
<td>Entries</td>
<td>
<p><a href="en/JSAPI_Reference/JSPRINCIPALS_DROP">JSPRINCIPALS_DROP</a>,
<a href="en/JSAPI_Reference/JSPRINCIPALS_HOLD">JSPRINCIPALS_HOLD</a>,
<a href="en/JSAPI_Reference/JS_CompileFunctionForPrincipals">JS_CompileFunctionForPrincipals</a>,
<a href="en/JSAPI_Reference/JS_CompileScriptForPrincipals">JS_CompileScriptForPrincipals</a>,
<a href="en/JSAPI_Reference/JS_CompileUCFunctionForPrincipals">JS_CompileUCFunctionForPrincipals</a>,
<a href="en/JSAPI_Reference/JS_CompileUCScriptForPrincipals">JS_CompileUCScriptForPrincipals</a>,
<a href="en/JSAPI_Reference/JS_EvaluateScriptForPrincipals">JS_EvaluateScriptForPrincipals</a>
</p>
</td>
</tr>
</tbody></table>
Revert to this revision