<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		The B2BUA implementation in OpenSIPS is separated in two layers:
			<itemizedlist>
			<listitem>
		a lower one(coded in this module)- which implements the basic functions of a UAS and UAC
			</listitem>
			<listitem>
		a upper one - which represents the logic engine of B2BUA, responsible of actually
			implementing the B2BUA services using the functions offered by the low level.
			</listitem>
	</itemizedlist>

		This module stores records corresponding to the dialogs in which the B2BUA
		is involved. It exports an API to be called from other modules which offers functions for
		creating a new dialog record, for sending requests or replies in one dialog and will also
		notify the upper level module when a request or reply is received inside one stored dialog.

		The records are separated in two types: b2b server entities and b2b client entities depending
		on the mode they are created. An entity created for a received initial message will be a server entity,
		while a entity that will send an initial request(create a new dialog) will be a b2b client entity.
		The name corresponds to the behavior in the first transaction - if UAS - server entity and if UAC - client entity.

		This module does not implement a B2BUA alone, but needs a B2B logic implementing module.
	</para>
	<para>
		The module is able to respond to authentication challanges if the
		uac_auth module is loaded first.  The list of credentials for
		b2b authentication is also provided by the uac_auth module.
	</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>tm</emphasis>
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>a db module</emphasis>
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>uac_auth</emphasis>
				(mandatory if authentication is required)
			</para>
			</listitem>
			</itemizedlist>
	</section>
	
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>
			</para>
			</listitem>
			</itemizedlist>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
	<section id="param_server_hsize" xreflabel="server_hsize">
		<title><varname>server_hsize</varname> (int)</title>
		<para>
			The size of the hash table that stores the b2b server entities.
			It is the 2 logarithmic value of the real size.
		</para>
		<para>
		<emphasis>Default value is <quote>9</quote>
		</emphasis>
		 (512 records).
		</para>
		<example>
		<title>Set <varname>server_hsize</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "server_hsize", 10)
...
	</programlisting>
		</example>
	</section>

	<section id="param_client_hsize" xreflabel="client_hsize">
		<title><varname>client_hsize</varname> (int)</title>
		<para>
			The size of the hash table that stores the b2b client entities.
			It is the 2 logarithmic value of the real size.
		</para>
		<para>
		<emphasis>Default value is <quote>9</quote>
		</emphasis>
		 (512 records).
		</para>
		<example>
		<title>Set <varname>client_hsize</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "client_hsize", 10)
...
	</programlisting>
		</example>
	</section>

	<section id="param_script_req_route" xreflabel="script_req_route">
		<title><varname>script_req_route</varname> (str)</title>
		<para>
			The name of the b2b script route that will be called when
			B2B requests are received.
		</para>
		<example>
		<title>Set <varname>script_req_route</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "script_req_route", "b2b_request")
...
	</programlisting>
		</example>
	</section>

	<section id="param_script_reply_route" xreflabel="script_reply_route">
		<title><varname>script_reply_route</varname> (str)</title>
		<para>
			The name of the b2b script route that will be called when
			B2B replies are received.
		</para>
		<example>
		<title>Set <varname>script_repl_route</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "script_reply_route", "b2b_reply")
...
	</programlisting>
		</example>
	</section>

	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (str)</title>
		<para>
			Database URL. It is not compulsory, if not set
			data is not stored in database.
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "db_url", "mysql://opensips:opensipsrw@127.0.0.1/opensips")
...
	</programlisting>
		</example>
	</section>

	<section id="param_cachedb_url" xreflabel="cachedb_url">
		<title><varname>cachedb_url</varname> (str)</title>
		<para>
			URL of a NoSQL database to be used. Only Redis is supported
			at the moment.
		</para>
		<example>
		<title>Set <varname>cachedb_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "cachedb_url", "redis://localhost:6379/")
...
	</programlisting>
		</example>
	</section>

	<section id="param_cachedb_key_prefix" xreflabel="cachedb_key_prefix">
		<title><varname>cachedb_key_prefix</varname> (string)</title>
		<para>
		Prefix to use for every key set in the NoSQL database.
		</para>
		<para>
		<emphasis>
			Default value is <quote>b2be$</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>cachedb_key_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "cachedb_key_prefix", "b2b")
...
</programlisting>
		</example>
	</section>

	<section id="param_update_period" xreflabel="update_period">
		<title><varname>update_period</varname> (int)</title>
		<para>
			The time interval at which to update the info in database.
		</para>
		<para>
		<emphasis>Default value is <quote>100</quote>.</emphasis>
		</para>
		<example>
		<title>Set <varname>update_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "update_period", 60)
...
	</programlisting>
		</example>
	</section>

	<section id="param_b2b_key_prefix" xreflabel="b2b_key_prefix">
		<title><varname>b2b_key_prefix</varname> (string)</title>
		<para>
			The string to use when generating the key ( it is inserted
			in the SIP messages as callid or to tag. It is useful to set
			this prefix if you use more instances of opensips B2BUA cascaded
			in the same architecture. Sometimes opensips B2BUA looks at the
			callid or totag to see if it has the format it uses to determine
			if the request was sent by it.
		</para>
		<para>
		<emphasis>Default value is <quote>B2B</quote>.</emphasis>
		</para>
		<example>
		<title>Set <varname>b2b_key_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "b2b_key_prefix", "B2B1")
...
	</programlisting>
		</example>
	</section>
	<section id="param_db_mode" xreflabel="db_mode">
		<title><varname>db_mode</varname> (int)</title>
		<para>
			The B2B modules have support for the 3 type of database storage
		</para>
		<para>
		<itemizedlist>
				<listitem>NO DB STORAGE - set this parameter to 0</listitem>
				<listitem>WRITE THROUGH (synchronous write in database) - set this parameter to 1</listitem>
				<listitem>WRITE BACK (update in db from time to time) - set this parameter to 2</listitem>
		</itemizedlist>
		</para>
		<para>
		<emphasis>Default value is <quote>2</quote> (WRITE BACK).</emphasis>
		</para>
		<example>
		<title>Set <varname>db_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "db_mode", 1)
...
	</programlisting>
		</example>
	</section>

	<section id="param_db_table" xreflabel="db_table">
		<title><varname>db_table</varname> (str)</title>
		<para>
			The name of the table that will be used for storing B2B entities
		</para>
		<para>
		<emphasis>Default value is <quote>b2b_entities</quote></emphasis>
		</para>
		<example>
		<title>Set <varname>db_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "db_table", "some table name")
...
	</programlisting>
		</example>
	</section>

	<section id="param_cluster_id" xreflabel="cluster_id">
		<title><varname>cluster_id</varname> (int)</title>
		<para>
		The ID of the cluster this instance belongs to. Setting this parameter
		enables clustering support for the OpenSIPS B2BUA by replicating the
		B2B entities (B2B dialogs) between instances. This also ensures restart
		persistency through the <emphasis>clusterer</emphasis> module's
		data "sync" mechanism.
		</para>

			&clusterer_sync_cap_para;

		<para>
		<emphasis>Default value is <quote>0</quote> (clustering disabled)</emphasis>
		</para>
		<example>
		<title>Set <varname>cluster_id</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "cluster_id", 10)
...
	</programlisting>
		</example>
	</section>

	<section id="passthru_prack_id" xreflabel="passthru_prack">
		<title><varname>passthru_prack</varname> (int)</title>
		<para>
		This parameter allows to control, whether a PRACK should be generated locally (=0)
		or if we request it to be end-to-end (=1).
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote> (generate PRACK locally)</emphasis>
		</para>
		<example>
		<title>Set <varname>passthru_prack</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "passthru_prack", 1)
...
	</programlisting>
		</example>
	</section>

	<section id="param_advertised_contact" xreflabel="advertised_contact">
		<title><varname>advertised_contact</varname> (str)</title>
		<para>
		Contact to use in generated messages for UA session started with the
		<xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<example>
		<title>Set <varname>advertised_contact</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "advertised_contact", "opensips@10.10.10.10:5060")
...
	</programlisting>
		</example>
	</section>

	<section id="param_ua_default_timeout" xreflabel="ua_default_timeout">
		<title><varname>ua_default_timeout</varname> (str)</title>
		<para>
		Default timeout, in seconds, for UA session started with the
		<xref linkend="func_ua_session_server_init"/> function or the
		<xref linkend="mi_ua_session_client_start"/> MI function. After this
		interval a BYE will be sent and the session will be deleted.
		</para>
		<para>
		If not set the default is 43200 (12 hours).
		</para>
		<example>
		<title>Set <varname>ua_default_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("b2b_entities", "ua_default_timeout", 7200)
...
	</programlisting>
		</example>
	</section>

</section>

	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>
	<section id="func_ua_session_server_init" xreflabel="ua_session_server_init()">
		<title>
		<function moreinfo="none">ua_session_server_init([key], [flags])</function>
		</title>
		<para>
		This function initializes a new UA session by processing an initial INVITE.
		Further requests/replies received belonging to this session will only
		be handled via the <xref linkend="event_E_UA_SESSION"/> event.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key (var, optional)</emphasis> - Variable to return the
				b2b entity key of the new UA session.
			</para></listitem>
			<listitem><para>
				<emphasis>flags (string, optional)</emphasis> - configures options
				for this UA session via the following flags:
				<itemizedlist>
					<listitem><para>
					<emphasis>t[nn]</emphasis> - maximum duration of
					this session in seconds. After this timeout a BYE
					will be sent and the session will be deleted. If this
					is not set, the default timeout, configured with
					<xref linkend="param_ua_default_timeout"/> will be used.
					Example: <emphasis>t3600</emphasis>
					</para></listitem>
					<listitem><para>
					<emphasis>a</emphasis> - report the receving of ACK requests
					via the <xref linkend="event_E_UA_SESSION"/> event. 
					</para></listitem>
					<listitem><para>
					<emphasis>r</emphasis> - report the receving of replies via
					the <xref linkend="event_E_UA_SESSION"/> event.
					</para></listitem>
					<listitem><para>
					<emphasis>d</emphasis> - disable the automatic sending of ACK
					upon receving a 200 OK reply for INVITE (in case of UAC session)
					or re-INVITE.
					</para></listitem>
					<listitem><para>
					<emphasis>h</emphasis> - provide the headers of the SIP request/reply
					in the <xref linkend="event_E_UA_SESSION"/> event.
					</para></listitem>
					<listitem><para>
					<emphasis>b</emphasis> - provide the body of the SIP request/reply
					in the <xref linkend="event_E_UA_SESSION"/> event.
					</para></listitem>
					<listitem><para>
					<emphasis>n</emphasis> - do not trigger the
					<xref linkend="event_E_UA_SESSION"/> event (with event_type
					<emphasis>NEW</emphasis>)  for initial INVITES
					handled with this function.
					</para></listitem>
				</itemizedlist>
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
			<title><function>ua_session_server_init</function> usage</title>
		<programlisting format="linespecific">
...
if(is_method("INVITE") &amp;&amp; !has_totag()) {
   ua_session_server_init($var(b2b_key), "arhb");

   ua_session_reply($var(b2b_key), "INVITE", 200, "OK", $var(my_sdp));
   
   exit;
}
...
		</programlisting>
		</example>
	</section>

	<section id="func_ua_session_update" xreflabel="ua_session_update()">
		<title>
		<function moreinfo="none">ua_session_update(key, method, [body], [extra_headers], [content_type])</function>
		</title>
		<para>
		Sends a sequential request for a UA session started with the 
		<xref linkend="func_ua_session_server_init"/> function or
		the <xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key (string)</emphasis> - b2b entity key of the UA session.
			</para></listitem>
			<listitem><para>
				<emphasis>method (string)</emphasis> - name of the SIP method for this
				request.
			</para></listitem>
			<listitem><para>
				<emphasis>body (string, optional)</emphasis> - body to include in the
				SIP message.
			</para></listitem>
			<listitem><para>
				<emphasis>extra_headers (string, optional)</emphasis> - extra headers
				to include in the SIP message.
			</para></listitem>
			<listitem><para>
				<emphasis>content_type (string, optional)</emphasis> - Content-Type
				header. If the parameter is missing and a body is provided,
				"Content-Type: application/sdp" will be used.
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, EVENT_ROUTE.
		</para>
		<example>
			<title><function>ua_session_update</function> usage</title>
		<programlisting format="linespecific">
...
ua_session_update($var(b2b_key), "OPTIONS");
...
		</programlisting>
		</example>
	</section>

	<section id="func_ua_session_reply" xreflabel="ua_session_reply()">
		<title>
		<function moreinfo="none">ua_session_reply(key, method, code, [reason], [body], [extra_headers], [content_type])</function>
		</title>
		<para>
		Sends a reply for a UA session started with the 
		<xref linkend="func_ua_session_server_init"/> function or
		the <xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key (string)</emphasis> - b2b entity key of the UA session.
			</para></listitem>
			<listitem><para>
				<emphasis>method (string)</emphasis> - name of the SIP method that is
				replied to.
			</para></listitem>
			<listitem><para>
				<emphasis>code (int)</emphasis> - reply code.
			</para></listitem>
			<listitem><para>
				<emphasis>reason (string, optional)</emphasis> - reply reason string.
			</para></listitem>
			<listitem><para>
				<emphasis>body (string, optional)</emphasis> - body to include in the
				SIP message.
			</para></listitem>
			<listitem><para>
				<emphasis>extra_headers (string, optional)</emphasis> - extra headers
				to include in the SIP message.
			</para></listitem>
			<listitem><para>
				<emphasis>content_type (string, optional)</emphasis> - Content-Type header.
				If the parameter is missing and a body is provided,
				"Content-Type: application/sdp" will be used.
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, EVENT_ROUTE.
		</para>
		<example>
			<title><function>ua_session_reply</function> usage</title>
		<programlisting format="linespecific">
...
ua_session_reply($var(b2b_key), "INVITE", 180, "Ringing");
...
		</programlisting>
		</example>
	</section>

	<section id="func_ua_session_terminate" xreflabel="ua_session_terminate()">
		<title>
		<function moreinfo="none">ua_session_terminate(key, [extra_headers])</function>
		</title>
		<para>
		Terminate a UA session started with the
		<xref linkend="func_ua_session_server_init"/> function or
		the <xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key (string)</emphasis> - b2b entity key of the UA session.
			</para></listitem>
			<listitem><para>
				<emphasis>extra_headers (string, optional)</emphasis> - extra headers
				to include in the SIP message
			</para></listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, EVENT_ROUTE.
		</para>
		<example>
			<title><function>ua_session_terminate</function> usage</title>
		<programlisting format="linespecific">
...
ua_session_terminate($var(b2b_key));
...
		</programlisting>
		</example>
	</section>
	</section>

<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
	<section id="mi_b2be_list" xreflabel="b2be_list">
		<title>
		<function moreinfo="none">b2be_list</function>
		</title>
		<para>
			This command can be used to list the internals of the b2b entities.
		</para>
		<para>
		Name: <emphasis>b2be_list</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
		<itemizedlist>
		</itemizedlist>
		<para>MI FIFO Command Format:</para>
	<programlisting  format="linespecific">
	opensips-cli -x mi b2be_list
	</programlisting>
	</section>

	<section id="mi_ua_session_client_start" xreflabel="ua_session_client_start">
		<title>
		<function moreinfo="none">ua_session_client_start</function>
		</title>
		<para>
		This command starts a new UAC session by sending an initial INVITE.
		Further requests/replies received belonging to this session will only
		be handled via the <xref linkend="event_E_UA_SESSION"/> event.
		</para>
		<para>
		Name: <emphasis>ua_session_client_start</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem>
				<para><emphasis>ruri</emphasis> - Request URI</para>
			</listitem>
			<listitem>
				<para><emphasis>to</emphasis> - To URI; can also be specified as:
				<emphasis>display_name,uri</emphasis> in order to set a Display Name,
				eg. <emphasis>Alice,sip:alice@opensips.org</emphasis>.</para>
			</listitem>
			<listitem>
				<para><emphasis>from</emphasis> - From URI; can also be specified as:
				<emphasis>display_name,uri</emphasis> in order to set a Display Name,
				eg. <emphasis>Alice,sip:alice@opensips.org</emphasis></para>
			</listitem>
			<listitem>
				<para><emphasis>proxy (optional)</emphasis> - URI of the
				outbound proxy to send the INVITE to</para>
			</listitem>
			<listitem>
				<para><emphasis>body (optional)</emphasis> - message body</para>
			</listitem>
			<listitem>
				<para><emphasis>content_type (optional)</emphasis> - Content Type
				header to use. If missing and a body is provided,
				"Content-Type: application/sdp" will be used.</para>
			</listitem>
			<listitem>
				<para><emphasis>extra_headers (optional)</emphasis> - extra headers</para>
			</listitem>
			<listitem>
				<para><emphasis>flags (optional)</emphasis> - flags with the same meaning
				as for the <emphasis>flags</emphasis> paramater of
				<xref linkend="func_ua_session_server_init"/>.</para>
			</listitem>
			<listitem>
				<para><emphasis>socket (optional)</emphasis> - OpenSIPS sending socket</para>
			</listitem>
		</itemizedlist>
		<para>opensips-cli Command Format:</para>
<programlisting  format="linespecific">
opensips-cli -x mi ua_session_client_start ruri=sip:bob@opensips.org \
to=sip:bob@opensips.org from=sip:alice@opensips.org flags=arhb
</programlisting>
	</section>

	<section id="mi_ua_session_update" xreflabel="ua_session_update">
		<title>
		<function moreinfo="none">ua_session_update</function>
		</title>
		<para>
		Sends a sequential request for a UA session started with the
		<xref linkend="func_ua_session_server_init"/> function or
		the <xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<para>
		Name: <emphasis>ua_session_update</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key</emphasis> - b2b entity key of the UA session.
			</para></listitem>
			<listitem><para>
				<emphasis>method</emphasis> - name of the SIP method for this
				request.
			</para></listitem>
			<listitem><para>
				<emphasis>body (optional)</emphasis> - body to include in the
				SIP message.
			</para></listitem>
			<listitem><para>
				<emphasis>extra_headers (optional)</emphasis> - extra headers
				to include in the SIP message.
			</para></listitem>
			<listitem><para>
				<emphasis>content_type (string)</emphasis> - Content-Type header.
				If the parameter is missing and a body is provided,
				"Content-Type: application/sdp" will be used.
			</para></listitem>
		</itemizedlist>
		<para>opensips-cli Command Format:</para>
<programlisting  format="linespecific">
opensips-cli -x mi ua_session_update key=B2B.436.1925389.1649338095 method=OPTIONS
</programlisting>
	</section>

	<section id="mi_ua_session_reply" xreflabel="ua_session_reply">
		<title>
		<function moreinfo="none">ua_session_reply</function>
		</title>
		<para>
		Sends a reply for a UA session started with the
		<xref linkend="func_ua_session_server_init"/> function or
		the <xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<para>
		Name: <emphasis>ua_session_reply</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key </emphasis> - b2b entity key of the UA session.
			</para></listitem>
			<listitem><para>
				<emphasis>method </emphasis> - name of the SIP method that is
				replied to.
			</para></listitem>
			<listitem><para>
				<emphasis>code </emphasis> - reply code
			</para></listitem>
			<listitem><para>
				<emphasis>reason</emphasis> - reply reason string
			</para></listitem>
			<listitem><para>
				<emphasis>body (optional)</emphasis> - body to include in the
				SIP message
			</para></listitem>
			<listitem><para>
				<emphasis>extra_headers (optional)</emphasis> - extra headers
				to include in the SIP message
			</para></listitem>
			<listitem><para>
				<emphasis>content_type (optional)</emphasis> - Content-Type header.
				If the parameter is missing and a body is provided,
				"Content-Type: application/sdp" will be used.
			</para></listitem>
		</itemizedlist>
		<para>opensips-cli Command Format:</para>
<programlisting  format="linespecific">
opensips-cli -x mi ua_session_reply key=B2B.436.1925389.1649338095 method=OPTIONS code=200 reason=OK
</programlisting>
	</section>

	<section id="mi_ua_session_terminate" xreflabel="ua_session_terminate">
		<title>
		<function moreinfo="none">ua_session_terminate</function>
		</title>
		<para>
		Terminate a UA session started with the
		<xref linkend="func_ua_session_server_init"/> function or
		the <xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<para>
		Name: <emphasis>ua_session_terminate</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key </emphasis> - b2b entity key of the UA session.
			</para></listitem>
			<listitem><para>
				<emphasis>extra_headers (optional)</emphasis> - extra headers
				to include in the SIP message
			</para></listitem>
		</itemizedlist>
		<para>opensips-cli Command Format:</para>
<programlisting  format="linespecific">
opensips-cli -x mi ua_session_terminate key=B2B.436.1925389.1649338095
</programlisting>
	</section>

	<section id="mi_ua_session_list" xreflabel="ua_session_list">
		<title>
		<function moreinfo="none">ua_session_list</function>
		</title>
		<para>
		List information about UA sessions started with
		<xref linkend="func_ua_session_server_init"/> function or
		the <xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<para>
		Name: <emphasis>ua_session_list</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key (optional)</emphasis> - b2b entity key of the UA session
				to list. If missing, all sessions will be listed.
			</para></listitem>
		</itemizedlist>
		<para>MI FIFO Command Format:</para>
	<programlisting  format="linespecific">
	opensips-cli -x mi ua_session_list
	</programlisting>
	</section>

</section>

<section id="exported_events" xreflabel="Exported Events">
<title>Exported Events</title>

	<section id="event_E_UA_SESSION" xreflabel="E_UA_SESSION">
		<title>
		<function moreinfo="none">E_UA_SESSION</function>
		</title>
		<para>
			This event is triggered for requests/replies belonging to an ongoing UA
			session started with the
			<xref linkend="func_ua_session_server_init"/> function or
		the <xref linkend="mi_ua_session_client_start"/> MI function.
		</para>
		<para>
			Note that replies will not be reported at all unless the
			<emphasis>r</emphasis> flag was set when initiating the UA session. Also
			ACK requests are only reported if the <emphasis>a</emphasis> flag was set.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>key</emphasis> - b2b entity key of the UA session.
			</para></listitem>
			<listitem><para>
				<emphasis>entity_type</emphasis> - indicates whether this is a
				<emphasis>UAS</emphasis> or <emphasis>UAc</emphasis> entity.
			</para></listitem>
			<listitem><para>
				<emphasis>event_type</emphasis> - the type of event:
				<itemizedlist>
					<listitem><para>
						<emphasis>NEW</emphasis> - for initial INVITE requests,
						handled with the <xref linkend="func_ua_session_server_init"/>
						function.
					</para></listitem>
					<listitem><para>
						<emphasis>EARLY</emphasis> - for 1xx provisional
						responses
					</para></listitem>
					<listitem><para>
						<emphasis>ANSWERED</emphasis> - for 2xx successful
						responses
					</para></listitem>
					<listitem><para>
						<emphasis>REJECTED</emphasis> - for 3xx-6xx failure
						responses
					</para></listitem>
					<listitem><para>
						<emphasis>UPDATED</emphasis> - for any sequential requests,
						including ACK but excluding BYE/CANCEL
					</para></listitem>
					<listitem><para>
						<emphasis>TERMINATED</emphasis> - for BYE or CANCEL
						requests
					</para></listitem>
				</itemizedlist>
			</para></listitem>
			<listitem><para>
				<emphasis>status</emphasis> - the reply status code if the message is
				a SIP reply
			</para></listitem>
			<listitem><para>
				<emphasis>reason</emphasis> - the reply reason if the message is
				a SIP reply
			</para></listitem>
			<listitem><para>
				<emphasis>method</emphasis> - the SIP method name
			</para></listitem>
			<listitem><para>
				<emphasis>body</emphasis> - SIP message body
			</para></listitem>
			<listitem><para>
				<emphasis>headers</emphasis> - full list of all SIP headers in the
				message.
			</para></listitem>
		</itemizedlist>
	</section>

</section>

</chapter>

