	<section id="rfc-3327-support" xreflabel="Path (RFC 3327) Support">
		<title>Path Support (RFC 3327)</title>
		<para>
		The &reg_module; module includes SIP Path header field support
		according to
		<ulink url="https://tools.ietf.org/html/rfc3327">RFC 3327</ulink>,
		for usage in registrars and home-proxies.
		</para>
		<para>
		A call to &reg_save_f; stores, if path support is enabled
		in the &reg_module; module, the values of the Path
		Header(s) along with the Contact information into usrloc. There are
		three modes for building the reply to a REGISTER message which
		includes one or more Path header fields:
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>off</emphasis> - stores the value of the
				Path headers into usrloc without passing it back to
				the UAC in the reply.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>lazy</emphasis> - stores the Path header and
				passes it back to the UAC if Path-support is indicated
				by the <quote>path</quote> param in the Supported HF.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>strict</emphasis> - rejects the registration
				with <quote>420 Bad Extension</quote> if there's a Path
				header but no support for it is indicated by the UAC.
				Otherwise it's stored and passed back to the UAC.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		A call to &reg_lookup_f; always uses the Path header if
		found, and inserts it as Route HF either in front of
		the first Route HF, or after the last Via HF if no
		Route is present. It also sets the destination URI to
		the first Path URI, thus overwriting the received-URI,
		because NAT has to be handled at the outbound-proxy of
		the UAC (the first hop after client's NAT).
		</para>
		<para>
		The whole process is transparent to the user, so no
		config changes are required besides enabling one of the
		"p0" / "p1" / "p2" flags when calling &reg_save_f;.
		</para>
	</section>


	<section id="rfc-5627-support" xreflabel="SIP GRUU (RFC 5627) Support">
		<title>GRUU Support (RFC 5627)</title>
		<para>
		The &reg_module; module includes support for Globally Routable User
		Agent URIs according to <ulink url="https://tools.ietf.org/html/rfc5627">RFC 5627</ulink>.
		</para>
		<para>
		A call to &reg_save_f; stores, if the phone supports GRUU,
		the values of the SIP Instance along with the contact into usrloc.
		The module will generate two types of GRUUs:
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>public</emphasis> - exposes the underlying AOR,
				constructed just by attaching the SIP Instance as the ;gr
				parameter value. These are persistent, valid as long as the
				contact registration is valid.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>temporary</emphasis> - hides the underlying AOR
				Each new Register request leads to the construction of a
				new temporary GRUU, while Register requests with a different
				Call-ID lead to the invalidation of all the previous generated
				temporary GRUUs.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		A call to &reg_lookup_f; will try to detect if the R-URI contains a
		GRUU.  If it does, it will route the request just for the Contact
		that the specific AOR belongs to, without appending any other branches.
		</para>
		<para>
		Even if the the GRUU handling during the registration process is
		transparent to the user, so no config changes are required, you need
		to take care of the GRUU specifics when handling mid-dialog requests.
		</para>
		<para>
		As the GRUU will be present in the contact header of the initial
		requests generated byt GRUU enabled devices, you will have to also
		do a lookup() when receiving a mid-dialog request with the GRUU
		indication in the RURI.
		</para>
	</section>


	<section id="rfc-8599-support" xreflabel="SIP PN (RFC 8599) Support">
		<title>SIP Push Notification Support (RFC 8599)</title>
		<para>
		The &reg_module; module includes support for standards-based SIP Push
		Notifications, per
		<ulink url="https://tools.ietf.org/html/rfc8599">RFC 8599</ulink>.
		Support for the basic version of the draft can be enabled by switching
		<xref linkend="param_pn_enable"/> to <emphasis>true</emphasis>.  The
		module also includes optional support for sending Push Notifications
		during long-lived dialogs (<ulink url="https://tools.ietf.org/html/rfc8599#page-23">see RFC section 6</ulink>),
		through the <xref linkend="param_pn_enable_purr"/> switch.
		</para>
		<para>
			Essential mechanics behind the Push Notification (PN) support:
		</para>
		<itemizedlist>
			<listitem>
			<para>
				the PN support is fully compatible with the existing logic and
				enabling it does not impose any limitations, as the
				&reg_module; can simultaneously handle both SIP PN compliant
				and standard SIP User Agents
			</para>
			</listitem>
			<listitem>
			<para>
				OpenSIPS will raise a
				<ulink url='usrloc#event_E_UL_CONTACT_REFRESH'>E_UL_CONTACT_REFRESH</ulink>
				event any time a Push Notification needs to be sent to a
				PN-enabled contact.  The event includes the PN coordinates of
				the contact -- they may be found in the Contact URI ('uri'
				event parameter) and may be extracted using the {uri.param,name}
				transformation. From here onwards, it is up to the script
				developer to trigger the Push Notification (e.g. possibly by
				sending an HTTP POST with the
				<ulink url='rest_client'>rest_client</ulink> module), thus forcing
				a re-registration from the device.
			</para>
			</listitem>
			<listitem>
			<para>
				REGISTER processing is unchanged -- PN-enabled UAs are saved
				just as regular UAs, with the former ones additionally having
				the <emphasis>4</emphasis> bitflag set in the "Flags" field of
				any MI listing of contacts, for differentiation purposes
			</para>
			</listitem>
			<listitem>
			<para>
				initial INVITE processing is barely changed, with the &reg_lookup_f;
				function now additionally returning a value of
				<emphasis role='bold'>2</emphasis> if the only
				found contacts were PN-enabled contacts, all which required a
				Push Notification.  This means that PNs have been triggered for
				each of them and t_relay() is not required, since they are not
				reachable until they re-register!
			</para>
			<para>
				Using the event_routing module, OpenSIPS will transparently
				fork a new branch from the current INVITE on each
				re-registration from these contacts within the accepted
				<xref linkend="param_pn_refresh_timeout"/>
			</para>
			</listitem>
			<listitem>
			<para>
				mid-dialog requests: In some cases (e.g. long-lived dialogs),
				a PN may be required before being able to route a mid-dialog
				request to a SIP UA.  The <xref linkend="afunc_pn_process_purr"/>
				async function will take care of triggering the PN event and
				resuming the script as soon as a re-registration from the
				concerned contact is received.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		For more information or examples, refer to the documentation of the
		"pn_xxx" module parameters or the OpenSIPS blog posts around the
		"SIP Push Notification" topic.
		</para>
	</section>
