<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;
]>
<!-- Auth_db Module User's Guide -->
<chapter>
  <title>&adminguide;</title>

  <section>
    <title>Overview</title>

    <para>This module contains all method related to the IMS policy and 
    charging control functions performed by an Application Function (e.g. 
    P-CSCF) over the Rx interface.  This module is dependent on the CDP (C 
    Diameter Peer) modules for communicating with PCRF as specified in 3GPP 
    specification TS 29.214.
    </para>
  </section>

  <section>
    <title>Dependencies</title>

    <section>
      <title>&kamailio; Modules</title>

      <para>The Following mouldes must be loaded before this module:</para>

      <itemizedlist>
        <listitem>
          <para>Dialog2</para>
        </listitem>
          
        <listitem>
          <para>Usrloc PCSCF</para>
        </listitem>
          
        <listitem>
          <para>TM - Transaction Manager</para>
        </listitem>

        <listitem>
          <para>CDP - C Diameter Peer</para>
        </listitem>

        <listitem>
          <para>CDP_AVP - CDP AVP Applications</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>External Libraries or Applications</title>

      <para>This modules requires the internal IMS library.</para>
    </section>
  </section>

  <section>
    <title>Parameters</title>

    <section>
      <title><varname>rx_dest_realm</varname> (string)</title>

      <para>This is the name of the Diameter realm of the Diameter server 
      (typically a PCRF).</para>

      <para><emphasis> Default value is 'ims.smilecoms.com'.
      </emphasis></para>

      <example>
        <title><varname>rx_dest_realm</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "rx_dest_realm", "ims.smilecoms.com")
...
        </programlisting>
      </example>
    </section>
    
    <section>
      <title><varname>rx_forced_peer</varname> (string)</title>

      <para>This is the optional name of the origin host of the Diameter server
      (typically a PCRF).  If not set then realm routing is used.</para>

      <para><emphasis> Default value is ''.
      </emphasis></para>

      <example>
        <title><varname>rx_forced_peer</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "rx_forced_peer", "pcrf.ims.smilecoms.com")
...
        </programlisting>
      </example>
    </section>
    
    <section>
      <title><varname>rx_auth_expiry</varname> (integer)</title>

      <para>This is the expiry length in seconds of the initiated 
      Diameter sessions.</para>

      <para><emphasis> Default value is 7200.
      </emphasis></para>

      <example>
        <title><varname>rx_auth_expiry</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "rx_auth_expiry", 14400)
...
        </programlisting>
      </example>
    </section>
    
    <section>
      <title><varname>cdp_event_latency</varname> (integer)</title>

      <para>This is a flag to determine whether or slow CDP responses should be 
      reported in the log file. 1 is enabled and 0 is disabled.</para>

      <para><emphasis> Default value is 1.
      </emphasis></para>

      <example>
        <title><varname>cdp_event_latency</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "cdp_event_latency", 1)
...
        </programlisting>
      </example>
    </section>
    
    <section>
      <title><varname>cdp_event_threshold</varname> (integer)</title>

      <para>This time in milliseconds is the limit we should report a CDP 
      response as slow. i.e. if a CDP response exceeds this limit it will be 
      reported in the log file.  This is only relevant is cdp_event_latency is 
      enabled (set to 0).
      </para>

      <para><emphasis> Default value is 500.
      </emphasis></para>

      <example>
        <title><varname>cdp_event_threshold</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "cdp_event_threshold", 500)
...
        </programlisting>
      </example>
    </section>
    
    <section>
      <title><varname>cdp_event_latency_log</varname> (integer)</title>

      <para>This time log level at which we should report slow CDP responses. 
          0 is ERROR, 1 is WARN, 2 is INFO and 3 is DEBUG. This is only 
          relevant is cdp_event_latency is enabled (set to 0)
      </para>

      <para><emphasis> Default value is 0.
      </emphasis></para>

      <example>
        <title><varname>cdp_event_latency_log</varname> parameter usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "cdp_event_latency_log", 1)
...
        </programlisting>
      </example>
    </section>
  
  </section>

  <section>
    <title>Functions</title>

    <section>
      <title><function
      moreinfo="none">Rx_AAR_Register(domain)</function></title>

      <para>Perform a AAR on Diameter RX interface to subscribe to signalling 
      status. This purpose of this is tell a Diameter server (typically a PCRF)
      to inform the requesting Diameter client on changes to the status of 
      signalling bearer for the same framed IP address.  For more details see
      3GGP TS 29.214. </para>

      <para>Meaning of the parameters is as follows:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>domain</emphasis> that usrloc_pcscf uses to store 
          user information.</para>
        </listitem>
      </itemizedlist>

      <para>This function can be used from REQUEST_ROUTE.</para>

      <para>p.s. this is executed asynchronously. See example on how to
      retrieve return value</para>

      <example>
        <title>Rx_AAR_Register</title>

        <programlisting format="linespecific">
...
    Rx_AAR_Register("location");
    
    switch ($avp(s:aar_return_code)) {
        case 1:
            xlog("L_DBG", "Diameter: AAR success on subscription to signalling\n");
            break;
        default:
            xlog("L_ERR", "Diameter: AAR failed on subscription to signalling\n");
            t_reply("403", "Can't register to QoS for signalling");
            exit;
    }

...
</programlisting>
      </example>
    </section>
    
    <section>
      <title><function
      moreinfo="none">Rx_AAR(domain)</function></title>

      <para>Perform a AAR on Diameter RX interface to request resource 
      authorisation from a Diameter server (typically a PCRF). For more details 
      see 3GGP TS 29.214. </para>
      
      <para>Meaning of the parameters is as follows:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>domain</emphasis> that usrloc_pcscf uses to store 
          user information.</para>
        </listitem>
      </itemizedlist>

      <para>This function can be used from REQUEST_ROUTE or ONREPLY_ROUTE.</para>

      <para>p.s. this is executed asynchronously. See example on how to
      retrieve return value</para>

      <example>
        <title>Rx_AAR</title>

        <programlisting format="linespecific">
...
    Rx_AAR("location");
    
    switch ($avp(s:aar_return_code)) {
        case 1:
            xlog("L_DBG", "Diameter: AAR success\n");
            break;
        default:
            xlog("L_ERR", "Diameter: AAR failed\n");
            t_reply("403", "QoS not authorized");
            exit;
    }

...
</programlisting>
      </example>
    </section>

    
    
   </section>

  <section>
    <title>Statistics</title>

    <section>
      <title>AAR Timeouts (aar_timeouts)</title>

      <para>The number of timeouts on sending a AAR. i.e. no response to
      AAR.</para>
    </section>

    <section>
      <title>Average AAR Response Time (aar_avg_response_time)</title>

      <para>The average response time in milliseconds for AAR-AAA
      transaction.</para>
    </section>
  </section>
</chapter>
