osp_user.sgml

性能优秀的SIP Proxy

      <example>
        <title>Setting the retry limit</title>
        <programlisting format="linespecific">
modparam ("osp", "retry_limit", 2)
        </programlisting>
      </example>
    </section>
    <section>
      <title><varname>timeout</varname></title>
      <para>The timeout (integer) parameter defines the maximum time in milliseconds, to wait for a response from an peering server. If no response is received within this time, the current connection is aborted and the OSP Module attempts to contact the next peering server. The default value is 10 seconds.</para> 
      <example>
        <title>Setting the timeout</title>
        <programlisting format="linespecific">
modparam ("osp", "timeout", 10)
        </programlisting>
      </example>
    </section>
    <section>
      <title><varname>max_destinations</varname></title>
      <para>The max_destinations (integer) parameter defines the maximum number of destinations that OpenSER requests the peering server to return in a peering response. The default value is 5.</para>
      <example>
        <title>Setting the number of destination</title>
        <programlisting format="linespecific">
modparam ("osp", "max_destinations", 5)
        </programlisting>
      </example>
    </section>
    <section>
      <title><varname>validate_call_id</varname></title>
      <para>The validate_call_id (integer) parameter instructs the OSP module to validate call id in the peering token. If this value is set to 1, the OSP Module validates that the call id in the SIP INVITE message matches the call id in the peering token. If they do not match the INVITE is rejected. If this value is set to 0, the OSP Module will not validate the call id in the peering token. The default value is 1</para>
      <example>
        <title>Instructing the module to validate call id</title>
        <programlisting format="linespecific">
modparam ("osp", "validate_call_id", 1)
        </programlisting>
      </example>
    </section>
  </section>
  <section>
    <title>Exported Functions</title>
    <section>
      <title><function moreinfo="none">checkospheader()</function></title>
      <para>This function checks for the existence of the OSP-Auth-Token header field.</para>
      <example>
        <title>checkospheader usage</title>
        <programlisting format="linespecific">
...
if (checkospheader()) {
  log("OSP header field found.\n");
} else {
  log("no OSP header field present\n");
};
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><function moreinfo="none">validateospheader()</function></title>
      <para>This function validates an OSP-Token specified in the OSP-Auth-Tokenheader field of the SIP message. If a peering token is present, it will be validated locally. If no OSP header is found or the header token is invalid or expired, -1 is returned; on successful validation 1 is returned.</para>
      <example>
        <title>validateospheader usage</title>
        <programlisting format="linespecific">
...
if (validateospheader()) {
  log("valid OSP header found\n");
} else {
  log("OSP header not found, invalid or expired\n");
};
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><function moreinfo="none">requestosprouting()</function></title>
      <para>This function launches a query to the peering server requesting the IP address of one or more destination peers serving the called party. If destination peers are available, the peering server will return the IP address and a peering authorization token for each destination peer. The OSP-Auth-Token Header field is inserted into the SIP message and the SIP uri is rewritten to the IP address of destination peer provided by the peering server.</para>
      <para>The address of the called party must be a valid E164 number, otherwise this function returns -1. If the transaction was accepted by the peering server, the uri is being rewritten and 1 returned, on errors (peering servers are not available, authentication failed or there is no route to destination or the route is blocked) -1 is returned.</para>
      <example>
        <title>requestosprouting usage</title>
        <programlisting format="linespecific">
...
if (requestosprouting()) {
  log("successfully queried OSP server, now relaying call\n");
} else {
  log("Authorization request was rejected from OSP server\n");
};
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><function moreinfo="none">preparefirstosproute()</function></title>
      <para>This function tries to prepare the INVITE to be forwarded or redirected using the first destination in the list returned by the peering server. If the route could not be prepared, the function returns 'FALSE' back to the script, which can then decide how to handle the failure.</para>
      <example>
        <title>preparefirstosproute usage</title>
        <programlisting format="linespecific">
...
if (preparefirstosproute ()) {
  log("successfully prepared the first route, now relaying call\n");
} else {
  log("could not prepare the route. The first destination was blocked\n");
};
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><function moreinfo="none">preparenextosproute()</function></title>
      <para>Once the call could not be completed through the first destination, this function tries to prepare the INVITE message using the next destination in the list returned by the peering Server. If it succeeds in preparing the route, the message is either redirected or relayed on (using the t_relay call), or else the function returns 'FALSE' back to the script, which can then decide how to handle the failure.</para>
      <example>
        <title>preparenextosproute usage</title>
        <programlisting format="linespecific">
...
if (preparenextosproute ()) {
  log("successfully prepared the next route, now relaying call\n");
} else {
  log("could not prepare the route. No next destination available\n");
};
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><function moreinfo="none">prepareallosproute()</function></title>
      <para>This function tries to prepare all the routes in the list returned by the peering server. The message is then either forked off or redirected to the destination. If unsuccessful in preparing the routes a SIP 500 is sent back and a trace message is logged.</para>
      <example>
        <title>prepareallosproute usage</title>
        <programlisting format="linespecific">
...
if (prepareallosproute ()) {
  log("successfully prepared the routes, now either forking or redirecting the call\n");
} else {
  log("could not prepare the route. No destination available\n");
};
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><function moreinfo="none">reportospusage()</function></title>
      <para>This function should be called after receiving a BYE message. If the message contains an OSP cookie, the function will forward originating and/or terminating duration usage information to a peering server. The function returns TRUE if the BYE includes an OSP cookie. The actual usage message will be send on a different thread and will not delay BYE processing. The function should be called before relaying the message.</para>
      <example>
        <title>reportospusage usage</title>
        <programlisting format="linespecific">
...
if (reportospusage ()) {
  log("OSP call duration usage will be reported\n");
} else {
  log("The BYE message does not include OSP information, it was not authorized by an OSP server\n");
};
...
        </programlisting>
      </example>
    </section>
  </section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("osp.sgml" "Book" "chapter")
End:
-->