Usage of nsIPrincipal Interface

 The principal gotten from the channel the image was loaded from.

readonly attribute nsIPrincipal imagePrincipal

 Returns an object describing the entity which signed 
 an entry. parseManifest must be called first. If aEntryName is an
 entry in the jar, getInputStream must be called after parseManifest.
 If aEntryName is an external file which has meta-information 
 stored in the jar, verifyExternalFile (not yet implemented) must 
 be called before getPrincipal.

nsIPrincipal getCertificatePrincipal(in string aEntryName)

 Return a principal with the specified certificate fingerprint, subject
 name (the full name or concatenated set of names of the entity
 represented by the certificate), pretty name, certificate, and
 codebase URI.  The certificate fingerprint and subject name MUST be
 nonempty; otherwise an error will be thrown.  Similarly, aCert must
 not be null.

[noscript] nsIPrincipal getCertificatePrincipal(in AUTF8String aCertFingerprint, in AUTF8String aSubjectName, in AUTF8String aPrettyName, in nsISupports aCert, in nsIURI aURI)

 Get the principal for the given channel.  This will typically be the
 channel owner if there is one, and the codebase principal for the
 channel's URI otherwise.  aChannel must not be null.

nsIPrincipal getChannelPrincipal(in nsIChannel aChannel)

 Return a principal that has the same origin as aURI.

nsIPrincipal getCodebasePrincipal(in nsIURI aURI)

 Same as getSubjectPrincipal(), only faster. cx must *never* be
 passed null, and it must be the context on the top of the
 context stack. Does *not* reference count the returned
 principal.

[noscript, notxpcom] nsIPrincipal getCxSubjectPrincipal(in JSContextPtr cx)

 Return the principal of the specified object in the specified context.

[noscript] nsIPrincipal getObjectPrincipal(in JSContextPtr cx, in JSObjectPtr obj)

 Returns the principal of the global object of the given context, or null
 if no global or no principal.

[noscript] nsIPrincipal getPrincipalFromContext(in JSContextPtr cx)

 Return the principal of the innermost frame of the currently 
 executing script. Will return null if there is no script 
 currently executing.

[noscript] nsIPrincipal getSubjectPrincipal()

 Return the all-powerful system principal.

[noscript] nsIPrincipal getSystemPrincipal()

 Initialize the principal and document and base URIs that the parser should
 use for documents it creates.  If this is not called, then a null
 principal and its URI will be used.  When creating a DOMParser via the JS
 constructor, this will be called automatically.  This method may only be
 called once.  If this method fails, all following parse attempts will
 fail.

 @param principal The principal to use for documents we create.
                  If this is null, a codebase principal will be created
                  based on documentURI; in that case the documentURI must
                  be non-null.
 @param documentURI The documentURI to use for the documents we create.
                    If null, the principal's URI will be used;
                    in that case, the principal must be non-null and its
                    URI must be non-null.
 @param baseURI The baseURI to use for the documents we create.
                If null, the documentURI will be used.
 @param scriptObject The object from which the context for event handling
                     can be got.

[noscript] void init(in nsIPrincipal principal, in nsIURI documentURI, in nsIURI baseURI, in nsIScriptGlobalObject scriptObject)

 Just like nsIDOMParser.init, but callable from JS.

void init(in nsIPrincipal principal, in nsIURI documentURI, in nsIURI baseURI)

 Returns instance of localStorage object for aURI's origin.
 This method ensures there is always only a single instance
 for a single origin.

nsIDOMStorage getLocalStorageForPrincipal(in nsIPrincipal aPrincipal)

 Create a blank document using the given loadgroup and given
 principal.  aPrincipal is allowed to be null, in which case the
 new document will get the about:blank codebase principal.

nsIDocument createBlankDocument(in nsILoadGroup aLoadGroup, in nsIPrincipal aPrincipal)

 Checks whether a principal should have access to the offline
 cache.
 @param aPrincipal
        The principal to check.
 @param aPrefBranch
        The pref branch to use to check the
        offline-apps.allow_by_default pref.  If not specified,
        the pref service will be used.

boolean offlineAppAllowed(in nsIPrincipal aPrincipal, in nsIPrefBranch aPrefBranch)

 Returns whether the other principal is equivalent to this principal.
 Principals are considered equal if they are the same principal,
 they have the same origin, or have the same certificate fingerprint ID

boolean equals(in nsIPrincipal other)

 Returns whether the other principal is equal to or weaker than this
 principal.  Principals are equal if they are the same object, they
 have the same origin, or they have the same certificate ID.

 Thus a principal always subsumes itself.

 The system principal subsumes itself and all other principals.

 A null principal (corresponding to an unknown, hence assumed minimally
 privileged, security context) is not equal to any other principal
 (including other null principals), and therefore does not subsume
 anything but itself.

 Both codebase and certificate principals are subsumed by the system
 principal, but no codebase or certificate principal yet subsumes any
 other codebase or certificate principal.  This may change in a future
 release; note that nsIPrincipal is unfrozen, not slated to be frozen.

 XXXbz except see bug 147145!

 Note for the future: Perhaps we should consider a certificate principal
 for a given URI subsuming a codebase principal for the same URI?  Not
 sure what the immediate benefit would be, but I think the setup could
 make some code (e.g. MaybeDowngradeToCodebase) clearer.

[noscript] boolean subsumes(in nsIPrincipal other)

 Similar to checkLoadURIWithPrincipal but there are two differences:

 1) The URI is a string, not a URI object.
 2) This function assumes that the URI may still be subject to fixup (and
 hence will check whether fixed-up versions of the URI are allowed to
 load as well); if any of the versions of this URI is not allowed, this
 function will return error code NS_ERROR_DOM_BAD_URI.

void checkLoadURIStrWithPrincipal(in nsIPrincipal aPrincipal, in AUTF8String uri, in unsigned long flags)

 Check that content with principal aPrincipal can load "uri".

 Will return error code NS_ERROR_DOM_BAD_URI if the load request 
 should be denied.

 @param aPrincipal the principal identifying the actor causing the load
 @param uri the URI that is being loaded
 @param flags the permission set, see above

void checkLoadURIWithPrincipal(in nsIPrincipal aPrincipal, in nsIURI uri, in unsigned long flags)

 Check whether a given principal is a system principal.  This allows us
 to avoid handing back the system principal to script while allowing
 script to check whether a given principal is system.

boolean isSystemPrincipal(in nsIPrincipal aPrincipal)

 Return true if content from the given principal is allowed to
 execute scripts.

[noscript] boolean canExecuteScripts(in JSContextPtr cx, in nsIPrincipal principal)

 Request that 'capability' can be enabled by scripts or applets
 running with 'principal'. Will prompt user if
 necessary. Returns nsIPrincipal::ENABLE_GRANTED or
 nsIPrincipal::ENABLE_DENIED based on user's choice.

[noscript] short requestCapability(in nsIPrincipal principal, in string capability)

 Synchronously load the document from the specified channel.

 @param aChannel   The channel to load the document from.
 @param aLoaderPrincipal Principal of loading document. For security
                         checks null if no securitychecks should be done

 @returns The document loaded from the URI.

nsIDOMDocument loadDocument(in nsIChannel aChannel, in nsIPrincipal aLoaderPrincipal)

 Synchronously load an XML document from the specified
 channel. The channel must be possible to open synchronously.

 @param aChannel   The channel to load the document from.
 @param aLoaderPrincipal Principal of loading document. For security
                         checks null if no securitychecks should be done

 @returns The document loaded from the URI.

nsIDOMDocument loadLocalDocument(in nsIChannel aChannel, in nsIPrincipal aLoaderPrincipal)

 Initialize the object for use from C++ code with the principal, script
 context, and owner window that should be used.

 @param principal The principal to use for the request. This must not be
                  null.
 @param scriptContext The script context to use for the request. May be
                      null.
 @param ownerWindow The associated window for the request. May be null.
 @param baseURI The base URI to use when resolving relative URIs. May be
                null.

[noscript] void init(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow, in nsIURI baseURI)

 Returns a XPCNativeWrapper, XPCSafeJSObjectWrapper, or
 XPCCrossOriginWrapper for the given object based on the principal, scope,
 and filename flags that are passed in.

 Note: In C++, the out jsval parameter must already be a strong GC root.

 @param aJSContext
     A JSContext.
 @param aObject
     The object to wrap.
 @param aScope
     The scope to be used in the event that we create a
     XPCCrossOriginWrapper. Can be null.
 @param aPrincipal
     The principal that should be used for the wrapper. If this parameter
     is given then aFilenameFlags will not be calculated and will be
     assumed to be 0 unless another value is given. If this parameter is
     null then aFilenameFlags will be calculated and the value of that
     argument will be ignored.
 @param aFilenameFlags
     The filename flags from the script that will use this wrapper. See
     above (aPrincipal) for details.

[noscript] JSVal getWrapperForObject(in JSContextPtr aJSContext, in JSObjectPtr aObject, in JSObjectPtr aScope, in nsIPrincipal aPrincipal, in unsigned long aFilenameFlags)

 Create a sandbox for evaluating code in isolation using
 evalInSandboxObject().

 @param cx A context to use when creating the sandbox object.
 @param principal The principal (or NULL to use the null principal)
                  to use when evaluating code in this sandbox.

[noscript] nsIXPConnectJSObjectHolder createSandbox(in JSContextPtr cx, in nsIPrincipal principal)