signaling Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters
        1.4. Exported Functions

              1.4.1. send_reply(code, reason)

        1.5. Exported Variables

              1.5.1. $sig_local_totag

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. sl_send_reply usage
   1.2. Usage of $sig_local_totag variable

Chapter 1. Admin Guide

1.1. Overview

   The SIGNALING module comes as a wrapper over tm and sl modules
   and offers one function to be called by the modules that want
   to send a reply.

   The logic behind the module is to first search if a transaction
   is created and if so, send a state full reply, using tm module,
   otherwise send a stateless reply with the function exported by
   sl. In this way, the script writer still has the call on how
   the transaction should be handled, state full or stateless and
   the reply is send accordingly to his choice.

   For example, if you do a t_newtran() in the script before doing
   save() (for registration), the function will automatically send
   the reply in stateful mode as a transaction is available. If no
   transaction is done, the reply will be sent in stateless way
   (as now).

   By doing this, we have the possibility to have same module
   sending either stateful either stateless replies, by just
   controlling this from the script (if we create or not a
   transaction). So, the signalling will be more coherent as the
   replies will be sent according to the transaction presence (or
   not).

   Moreover, this module offers the possibility of loading only
   one of the module, sl or tm, and send reply using only the
   module that is loaded. This is useful as not in all cases a
   user desires to send stateful or stateless replies and he
   should not be forced to load the module only because the send
   reply interface requires it.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   At least one of the following modules must be loaded before
   this module:
     * sl.
     * tm.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None.

1.3. Exported Parameters

     * None.

1.4. Exported Functions

1.4.1.  send_reply(code, reason)

   For the current request, a reply is sent back having the given
   code and text reason. The reply is sent stateless or statefull
   depending on which module is loaded and if a transaction was
   created, as explained above.

   Meaning of the parameters is as follows:
     * code (int) - Return code.
     * reason (string) - Reason phrase.

   This function can be used from REQUEST_ROUTE, ERROR_ROUTE.

   Example 1.1. sl_send_reply usage
...
send_reply(404, "Not found");
...
send_reply($err.rcode, $err.rreason);
...

1.5. Exported Variables

1.5.1. $sig_local_totag

   This variable returns the local To-tag that will be used by
   OpenSIPS for locally sending replies to the current SIP
   request. Yes, this variable should be used only in the context
   of a SIP request and it should be used only in conjunction with
   the using send_reply().

   Whenever you use it, be sure that the function is used in the
   same stateful / stateless SIP mode as the following replying
   function. Otherwise you may get different values for the
   To-tag!!

   NOTE: the variable returns the To-Tag that will be used by
   OpenSIPS in the locally generated reply. This may be completly
   different from the To-tag in the replies received and forwarded
   by OpenSIPS.

   Example 1.2. Usage of $sig_local_totag variable
...
# stateful handling
t_newtran();
xlog("the To-tag to be used is $sig_local_totag \n");
send_reply();  # or t_reply();
...
# stateless handling
xlog("the To-tag to be used is $sig_local_totag \n");
send_reply(); # or sl_send_reply();
...

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Liviu Chircu (@liviuchircu) 12 10 28 37
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 12 9 131 23
   3. Anca Vamanu 9 3 524 2
   4. Razvan Crainea (@razvancrainea) 7 5 6 4
   5. Maksym Sobolyev (@sobomax) 6 4 11 10
   6. Vlad Patrascu (@rvlad-patrascu) 6 3 23 76
   7. Peter Lemenkov (@lemenkov) 3 1 1 1
   8. zhangst 3 1 1 1

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Liviu Chircu (@liviuchircu)         Mar 2014 - May 2024
   2. Maksym Sobolyev (@sobomax)          Oct 2020 - Nov 2023
   3. Razvan Crainea (@razvancrainea)     Aug 2015 - Dec 2020
   4. Bogdan-Andrei Iancu (@bogdan-iancu) Nov 2008 - May 2020
   5. Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   6. Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7. zhangst                             Jul 2014 - Jul 2014
   8. Anca Vamanu                         Nov 2008 - Mar 2010

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Vlad
   Patrascu (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Liviu
   Chircu (@liviuchircu), zhangst, Anca Vamanu.

   Documentation Copyrights:

   Copyright © 2008 FhG FOKUS
