#pragma section-numbers on

<<TableOfContents(3)>>

= Introduction =

{{{#!wiki caution
'''Lacking essential documentation'''

What is "ContentPolicy"? What does it do? What is it for? Who might want or need it?
}}}


To enable the content policy:

{{{
require("content-policy");
}}}

= content_policy_scheme_whitelist =

This variable points to a structure whose keys are uri schemes to automatically whitelist.  The default value contains 'about', 'chrome', 'data', 'javascript', and 'moz-icon', which prevents you from blacklisting urls of those schemes in your content_policy_hook.  Some of these are there because they provide vital functionality to the program, so it would be an error to block them (about, chrome).  Others are there because it is a sensible base case, and simplifies the writing of content policy hook funcions in the majority of cases.  So while we document this variable here for completeness, for all practical purposes you can ignore it.

= content_policy_hook =

Content policy actions like blacklisting and whitelisting are implemented through `content_policy_hook`.  This is a run-until-success hook, meaning that each function on the hook will be tried in turn until one of them returns a true value.  If none of the hook functions return a true value, then the request is allowed.  See below in the section on return values for details.  The DOM may be in an inconsistent state when this hook is run, therefore functions in this hook '''must not modify the DOM''', query DOM properties outside of ''context'', or query DOM properties that depend on layout or style.  If you need to modify the DOM, do so in a timeout or a later event.

== Arguments ==

Hook functions are called with the following arguments.

 content_type::
 :: integer ('''1''': other, '''2''': script, '''3''': image, '''4''': stylesheet, '''5''': object, '''6''': document, '''7''': subdocument, '''9''': xbl, '''10''': ping, '''11''': xmlhttprequest, '''12''': object_subrequest, '''13''': dtd, '''14''': font, '''15''': media)  Type 8 will never occur.  If your content-policy is primarily dispatched on the content_type, your work can be simplified by using the provided `content_policy_bytype` function, described in the next section.

 content_location:: nsIURI
 request_origin:: nsIURI; what is this?
 context:: what is this?
 mime_type_guess:: string
 extra::

== Return Values ==

The following constants are provided for such hook functions:

 content_policy_reject:: Blacklist (deny the request)
 content_policy_accept:: Whitelist (allow the request)

In summary, if you want to whitelist a request, have your function return `content_policy_accept`.  If you want to stop a request, have your function return `content_policy_reject`.  Otherwise return null and the next content_policy_hook function, if any, will be tried.


= Provided Hook Functions =

The content-policy module provides some pre-written filtering algorithms which abstract common patterns for easier configuration.

== By Type Filtering ==

To enable by-type filtering:

{{{
add_hook("content_policy_hook", content_policy_bytype);
}}}

=== content_policy_bytype_table ===

By-type filtering is configured in content_policy_bytype_table.  The table has 14 named slots for the 14 content types.  Each slot can be set to a content_policy_hook function to be called by `content_policy_bytype` when a request of that type comes through.  The 14 types are, ('''1''': other, '''2''': script, '''3''': image, '''4''': stylesheet, '''5''': object, '''6''': document, '''7''': subdocument, '''9''': xbl, '''10''': ping, '''11''': xmlhttprequest, '''12''': object_subrequest, '''13''': dtd, '''14''': font, '''15''': media).  Note the absence of number 8.  It will never occur.


= Interactive Commands =

Application of the content-policy can be enabled and disabled with the two interactive commands `content-policy-enable` and `content-policy-disable`.


= Examples =

== Block Flash, with Host Whitelist ==

In fact this blocks all plugin content, not just flash applets, but who's counting?

{{{
require("content-policy.js");

function block_flash (content_type, content_location) {
    var Y = content_policy_accept, N = content_policy_reject;
    var action = ({ "homestarrunner.com":Y }
                  [content_location.host] || N);
    if (action == N)
        dumpln("blocked flash: "+content_location.spec);
    return action;
}
content_policy_bytype_table.object = block_flash;
add_hook("content_policy_hook", content_policy_bytype);
}}}


== Print Flash Video URLs to Console ==

Scrapers do not always work for downloading media whose origin is obfuscated by a Flash (or other plugin) wrapper, but you can use content-policy to obtain the URLs requested by plugins.  This example uses a couple of regular expression filters to limit what URLs will be reported so-as not to flood the console with information; these filters can be easily adjusted.

Note, this will have no effect if you are also blocking flash per the previous example.

{{{
require("content-policy.js");

function watch_flash_requests (content_type, content_location) {
    var url = content_location.spec;
    //dumpln("FLASHREQUEST: "+content_location.spec);
    if (url.match(/[0-9a-f]{32,32}/) ||
        url.match(/avi|flv|mp4|wmv|start=/))
    {
        dumpln("VIDEO? "+content_location.spec);
        return content_policy_reject;
    }
    return content_policy_accept;
}
content_policy_bytype_table.object_subrequest = watch_flash_requests;
add_hook("content_policy_hook", content_policy_bytype);
}}}


== Block Images ==

This is a very simple image blocker.  If you use this, you can still navigate directly to an image to view it.

{{{
require("content-policy.js");

content_policy_bytype_table.image = function () content_policy_reject;
add_hook("content_policy_hook", content_policy_bytype);
}}}