<!-- Common registrar SIP Push Notification modparams -->

	<section id="param_pn_enable" xreflabel="pn_enable">
		<title><varname>pn_enable</varname> (boolean)</title>
		<para>
			Enable SIP Push Notification support (<ulink url="https://tools.ietf.org/html/rfc8599"><citetitle>RFC 8599</citetitle></ulink>).
			If enabled, Contact header field URIs which include all
			<xref linkend="param_pn_ct_match_params"/> will be matched against
			existing bindings using only these parameters.  Otherwise,
			the module will attempt to match them as usual, using the current
			usrloc <ulink url='usrloc#param_matching_mode'>
					matching_mode</ulink>.
		</para>
		<para>
			<emphasis>
				Default value is <emphasis role='bold'>false</emphasis>.
			</emphasis>
		</para>

		<example>
		<title>Setting the <varname>pn_enable</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("&reg_module;", "pn_enable", true)
...
</programlisting>
		</example>
	</section>


	<section id="param_pn_providers" xreflabel="pn_providers">
		<title><varname>pn_providers</varname> (string)</title>
		<para>
		A list of supported Push Notification providers.  While only three
		possible values are defined by RFC 8599 ("apns", "fcm" and "webpush"),
		non-standard values may be specified as well.
		</para>
		<para>
			<emphasis>
				Default value is <emphasis role='bold'>NULL</emphasis>
						(not set).
			</emphasis>
		</para>

		<example>
		<title>Setting the <varname>pn_providers</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("&reg_module;", "pn_providers", "apns, fcm, webpush")
...
</programlisting>
		</example>
	</section>


	<section id="param_pn_ct_match_params" xreflabel="pn_ct_match_params">
		<title><varname>pn_ct_match_params</varname> (string)</title>
		<para>
			The minimally required list of RFC 8599 parameters (custom ones are
			accepted as well) which must be present in a Contact URI and
			identically match an existing binding in order for the binding
			to be refreshed during a SIP re-REGISTER.  If at least one such
			parameter is missing from a Contact header field URI, the module
			will fall back to performing regular contact matching.
		</para>
		<para>
			Note that if all above PN Contact URI parameters match an existing
			binding, the match is considered to be successful regardless if
			other parts of the SIP URI do not match (e.g. hostname, port,
			other URI parameters, etc.).
		</para>
		<para>
			After calling &reg_lookup_f; or
			<xref linkend="afunc_pn_process_purr"/>, the above PN-related
			parameters will be automatically stripped from the resulting
			Request and Contact URI event parameter, respectively.
		</para>
		<para>
			<emphasis>
				Default value is <emphasis role='bold'>
						"pn-provider, pn-prid, pn-param"</emphasis>.
			</emphasis>
		</para>

		<example>
		<title>Setting the <varname>pn_ct_match_params</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("&reg_module;", "pn_ct_match_params", "pn-provider, pn-prid")
...
</programlisting>
		</example>
	</section>


	<section id="param_pn_pnsreg_interval" xreflabel="pn_pnsreg_interval">
		<title><varname>pn_pnsreg_interval</varname> (integer)</title>
		<para>
			For devices capable of waking up and refreshing their binding on
			their own (signified by the <emphasis>";+sip.pnsreg"</emphasis>
			Contact header field parameter), this setting denotes the
			prior-to-expiration interval advertised by the server at which the
			device should issue its binding refresh request.
		</para>
		<para>
			<emphasis>
				Default value is <emphasis role='bold'>130</emphasis>
						(seconds before expiry).
			</emphasis>
		</para>

		<example>
		<title>Setting the <varname>pn_pnsreg_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("&reg_module;", "pn_pnsreg_interval", 140)
...
</programlisting>
		</example>
	</section>


	<section id="param_pn_trigger_interval" xreflabel="pn_trigger_interval">
		<title><varname>pn_trigger_interval</varname> (integer)</title>
		<para>
			If a binding refresh REGISTER request from a given SIP endpoint does
			not arrive within at least <xref linkend="param_pn_trigger_interval"/>
			seconds prior to expiration (e.g. because the device does not
			support <emphasis>";+sip.pnsreg"</emphasis> or because of other
			error conditions), the <ulink url='usrloc#event_E_UL_CONTACT_REFRESH'>E_UL_CONTACT_REFRESH</ulink>
			usrloc event will be triggered.
		</para>
		<para>
			Once <ulink url='usrloc#event_E_UL_CONTACT_REFRESH'>E_UL_CONTACT_REFRESH</ulink>
			is triggered, the script writer should use
			the RFC 8599 parameters from the Contact URI in order to generate a
			Push Notification request to the PN provider of the device, in
			order to cause the device to wake up and re-register.
		</para>
		<para>
			<emphasis>
				Default value is <emphasis role='bold'>120</emphasis>
						(seconds before expiry).
			</emphasis>
		</para>

		<example>
		<title>Setting the <varname>pn_trigger_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("&reg_module;", "pn_trigger_interval", 130)
...
</programlisting>
		</example>
	</section>


	<section id="param_pn_skip_pn_interval" xreflabel="pn_skip_pn_interval">
		<title><varname>pn_skip_pn_interval</varname> (integer)</title>
		<para>
			Following a successful (re)registration of a contact, this setting
			denotes a time interval, in seconds, during which the contact is
			assumed to be reachable, so any Push Notifications will be skipped.
		</para>
		<para>
			<emphasis>
				Default value is <emphasis role='bold'>0</emphasis> seconds
					(always generate Push Notifications).
			</emphasis>
		</para>

		<example>
		<title>Setting the <varname>pn_skip_pn_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("&reg_module;", "pn_skip_pn_interval", 10)
...
</programlisting>
		</example>
	</section>


	<section id="param_pn_refresh_timeout" xreflabel="pn_refresh_timeout">
		<title><varname>pn_refresh_timeout</varname> (integer)</title>
		<para>
			This timeout starts counting following a &reg_lookup_f; or a
			<xref linkend="afunc_pn_process_purr"/> which
			triggers a Push Notification.  The value represents the maximum
			allowed sum of the duration required for the Push Notification to
			be sent and the duration required for the corresponding
			re-registration from the device to arrive.
		</para>
		<para>
			Once this timeout is exceeded for an initial or a mid-dialog
			request, any further re-registrations which match the pending Push
			Notification will no longer cause the desired effects. For example:
			<itemizedlist>
			<listitem><para>
				pending initial INVITE transactions will complete and will no
				longer auto-fork an additional branch for each REGISTER
				sent by the callee side
			</para></listitem>
			<listitem><para>
				pending BYE messages will time out and OpenSIPS will attempt to
				route them despite not having received a confirmation that the
				target device is actually reachable
			</para></listitem>
			</itemizedlist>
		</para>
		<para>
			<emphasis>
				Default value is <emphasis role='bold'>6</emphasis> seconds.
			</emphasis>
		</para>

		<example>
		<title>Setting the <varname>pn_refresh_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("&reg_module;", "pn_refresh_timeout", 10)
...
</programlisting>
		</example>
	</section>


	<section id="param_pn_enable_purr" xreflabel="pn_enable_purr">
		<title><varname>pn_enable_purr</varname> (boolean)</title>
		<para>
			Enable the SIP Push Notification mechanism for long-lived dialogs.
			If enabled, the &reg_module; will include a
			<emphasis>"+sip.pnspurr"</emphasis>
			Feature-Caps header field tag in 200 OK replies to REGISTER
			requests.  This tag represents a unique identifier for the
			registration (PURR - Proxy Unique Registration Reference).
		</para>
		<para>
			During dialog setup, each UA may include, in its Contact header,
			the PURR value returned by OpenSIPS during registration.  By
			including the PURR (e.g. ";pn-purr=XXX"), an agent indicates that
			it expects to be first awoken by a PN before being able to receive
			a mid-dialog request sent by the other party.
		</para>
		<para>
			When enabling this parameter, make sure to also add logic for
			<xref linkend="afunc_pn_process_purr"/>.
		</para>
		<para>
			<emphasis>
				Default value is <emphasis role='bold'>false</emphasis>.
			</emphasis>
		</para>

		<example>
		<title>Setting the <varname>pn_enable_purr</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("&reg_module;", "pn_enable_purr", true)
...
</programlisting>
		</example>
	</section>
