[Users] NEW FEATURE: branch and script flags

[Bogdan-Andrei Iancu]

Hi everybody,

Following some discussions with Juha regarding some extension for the 
branch flags, we decided it is better to have a re-design of flags in 
openser to allow a better flexibility and extensibility without any 
consistency penalties.

What we had so far:
    - message flags (or transaction flags) which are transaction persistent
    - pseudo-branch flags - a set of flags from the message flags were 
handled by TM as branch flags
           (saved per branch and not only per transaction).

What we have now:
    - message flags (or transaction flags) will works as they do now, 
but the branch mask will be removed (rolling back as in 0.9.x versions). 
These flags are transaction persistent.
    - branch flags (NEW) are saved also in transaction, but per branch; 
also they will be saved in usrloc (per contact). A new set of functions 
were added for manipulating these flags from script. So, there flags 
will be registration persistent and branch persistent.
    - script flags (NEW) are no-message-related flags - they are only 
script persistent and you can strictly use them for scripting. Once you 
exit a top level route, they will be lost. These flags are useful and 
they offer an option to de-congest the message flags - many flags have 
no need to be saved as they just reflect some scripting status.


What changes brings this:
    - NAT flag will become a branch flag all the time.
    - you can have custom flags to be saved into usrloc (via branch flags).
    - more flags in script (via script flags).

Corresponding Functions:

    Message/transaction flags:
       setflag(flag_idx)
       resetflag(flag_idx)
       isflagset(flag_idx)

    Branch flags:
       setbflag/setbranchflag(branch_idx,flag_idx)
       resetbflag/resetbranchflag(branch_idx,flag_idx)
       isbflagset/isbranchflagset(branch_idx,flag_idx)
      or, the shorter format, working on the default (branch 0) flags:
       setbflag(flag_idx)
       resetbflag(flag_idx)
       isbflagset(flag_idx)      

    Script flags:
       setsflag/setscriptflag(flag_idx)
       resetsflag/resetscriptflag(flag_idx)
       issflagset/isscriptflagset(flag_idx)



Flags and Pseudo Variables

     Message/transaction flags
       $mf (decimal) , $mF (hexa)

     Branch flags
       $bf (decimal) , $bF (hexa)

     Script flags
       $sf (decimal) , $sF (hexa)



Flags and routes:

     Message/transaction flags

     These flags will show up in all routes where messages related to 
the initial request are processed. So, they will be visible and 
changeable in onbranch, failure and onreply routes; the flags will be 
visible in all branch routes; if you change a flag in a branch route, 
the next branch routes will inherit the change.

     Branch flags

     There flags will show up in all routes where messages related to 
initial branch request are processed. So, in branch route you will see 
different sets of flags (as they are different branches); in onreply 
route yo will see the branch flags corresponding to the branch the reply 
belongs to; in failure route, the branch flags corresponding to the 
branch the winning reply belongs to will be visible.
     In request route, you can have multiple branches (as a result of a 
lookup(), enum query, append_branch(), etc) - the default branch is 0 
(corresponding to the RURI); In reply routes there will be only one 
branch , the 0 one. In branch route the default branch is the current 
process branch (having index 0); In failure route, initialy there is 
only one branch (index 0), corresponding the the failed branch.

    Script flags

    There flags are available only in script and are reset after each 
top level route execution (routes internally triggered by OpenSER). They 
will be persistent per main route, onreply_route, branch_route, 
failure_route. Note they will be inherit in routes called from other routes.



Example: nat flag handling

..........
# 3 - the nat flag
modparam("usrloc","nat_bflag",3)
..........

route {
    ..........
    if (nat detected)
       setbflag(3); # set branch flag 3 for the branch 0

    ..........
    if (is_method("REGISTER")) {
       # the branch flags (including 3) will be saved into location
       save("location");
       exit;
    } else {
       # lookup will load the branch flag from location
       if (!lookup("location")) {
          sl_send_reply("404","Not Found");
          exit;
       }
       t_on_branch("1")
       t_relay();
    }
}

onbranch_route[1] {
    xlog("-------branch=$T_branch_idx, branch flags=$bF\n");
    if (isbflagset(3)) {
       #current branch is marked as natted
       .........
    }
}

if no parallel forking is done, you can get rid of the branch route and 
add instead of t_on_branch():
    ........
    if (isbflagset(3)) {
       #current branch is marked as natted
       .........
    }
    .........



I will upload this description on the wiki page to be more accessible - 
in the mean while, any feedback (reports, better ideas, bugd) are welcome!

Regards,
Bogdan