OriginRules

#include <Ultralight/OriginRules.h>

Overview

A list of origin patterns that controls which pages get an attached API.

When attaching a js::API, dom::Triggers, or dom::data::Context, you pass OriginRules to AttachTo() to choose which web origins get access.

Pass origin rules when attaching an API to allow a remote domain, its subdomains, and local files:

if (app.AttachTo(view.get(),
                 { .origin_rules = { "https://*.mygame.com", "file://*" } }))
  view->LoadURL("https://play.mygame.com/");

Rule Syntax

Each rule follows the scheme://host[:port] format. If a rule fails to parse, the attach call fails and returns false.

Part	Accepts
Scheme	An exact scheme with no wildcards
Host	An exact host, *, or *.example.com for the domain and all subdomains
Port	A specific port number, :* for any port, or default port if omitted

Common rules illustrate these patterns:

"https://store.mygame.com"   // store.mygame.com on the default port (443)
"https://*.mygame.com"       // mygame.com and all of its subdomains
"http://localhost:*"         // localhost on any port
"file://*"                   // local files

Default Rules

Attach calls restrict page access when you omit origin rules:

• An empty list allows local content. Content loaded from file:// URLs or View::LoadHTML() gets the API.
• Passing any rule replaces the default list. Include "file://*" in your list if you want to keep local page access alongside remote domains.

Origin Matching

Origin rules match only the scheme, host, and port of a page's web origin. Path segments, query strings, and fragment identifiers are never checked.

Origin matching depends on how a document is loaded:

• Frames with inherited origins match by the origin they inherit. Documents loaded in about:blank or srcdoc frames evaluate against the origin of the document that created them.
• HTML loaded with an explicit URL matches that URL. Passing a URL to View::LoadHTML() assigns that URL's origin to the document, matching rules like any page.
• Opaque origins never match any rule. Sandboxed frames, data: URLs, and View::LoadHTML() called without a URL produce opaque origins that fail all rule checks.

To allow an API on pages that cannot match an origin rule, set a filter on the View using js::SetInjectionFilter() or dom::SetInjectionFilter(). A dom::data::Context has no filter mechanism.

String Lifetime

OriginRules refers to rule strings without copying them.

Warning

An inline list's array is destroyed when that statement ends, leaving any variable that stored it (such as an OriginRules or an AttachOptions) pointing at freed memory. The attach call copies the strings, so pass the list directly into that call or keep them in a std::vector until the call completes.

See also

js::API::AttachTo(), dom::Triggers::AttachTo(), dom::data::Context::AttachTo(), js::SetInjectionFilter(), dom::SetInjectionFilter()

Public Member Functions
constexpr	OriginRules ()=default
	Create an empty list (the default policy).
constexpr	OriginRules (std::initializer_list< const char * > rules)
	Create a list from an inline list of rules.
constexpr	OriginRules (const char *const *rules, size_t size)
	Create a list from an array of rules.
template<typename Rules> requires std::is_convertible_v<const Rules&, std::span<const char* const>>
constexpr	OriginRules (const Rules &rules)
	Create a list from a contiguous container of rules (eg, a std::vector, std::array, or std::span of const char*).
constexpr const char *const *	data () const
	Get the rules.
constexpr size_t	size () const
	Get the number of rules.
constexpr bool	empty () const
	Whether or not the list is empty.

Constructor & Destructor Documentation

OriginRules() [1/4]

OriginRules ( )

constexprdefault

Create an empty list (the default policy).

OriginRules() [2/4]

OriginRules ( std::initializer_list< const char * > rules )

inlineconstexpr

Create a list from an inline list of rules.

Parameters

rules

The rules, as null-terminated UTF-8 strings.

OriginRules() [3/4]

OriginRules ( const char *const * rules, size_t size )

inlineconstexpr

Create a list from an array of rules.

Parameters

rules	An array of size rules, as null-terminated UTF-8 strings (can be nullptr when size is 0).
size	The number of entries in rules.

OriginRules() [4/4]

template<typename Rules>
requires std::is_convertible_v<const Rules&, std::span<const char* const>>

OriginRules ( const Rules & rules )

inlineconstexpr

Create a list from a contiguous container of rules (eg, a std::vector, std::array, or std::span of const char*).

Parameters

rules

The rules, as null-terminated UTF-8 strings.

Member Function Documentation

data()

const char *const * data ( ) const

inlineconstexpr

Get the rules.

Returns

Returns a pointer to the first rule (nullptr for an empty list).

empty()

bool empty ( ) const

inlineconstexpr

Whether or not the list is empty.

size()

size_t size ( ) const

inlineconstexpr

Get the number of rules.

---

The documentation for this class was generated from the following file:

• Ultralight/OriginRules.h