1.4.3. lookup(domain [, flags [, aor]])
The functions extracts username from Request-URI and tries to find all contacts for the username in usrloc. If there are no such contacts, -1 will be returned. If there are such contacts, Request-URI will be overwritten with the contact that has the highest q value and optionally the rest will be appended to the message (depending on append_branches parameter value).
If the method_filtering option is enabled, the lookup function will return only the contacts that support the method of the processed request.
Meaning of the parameters is as follows:
domain - Name of table that should be used for the lookup.
flags(optional)
'b' (no Branches) - this flag controls how lookup function processes multiple contacts. If there are multiple contacts for the given username in usrloc and this flag is not set, Request-URI will be overwritten with the highest-q rated contact and the rest will be appended to sip_msg structure and can be later used by tm for forking. If the flag is set, only Request-URI will be overwritten with the highest-q rated contact and the rest will be left unprocessed.
'r' (bRanch lookup) - this flag enables searching through existing branches for aor's and expanding them to contacts. For example, you have got AOR A in your ruri but you also want to forward your calls to AOR B. In order to do this, you must put AOR B in a branch, and if this flag enabled, the function will also expand AOR B to contacts, which will be put back into the branches. The AOR's that were in branches before the function call shall be removed.
WARNING: if you want this flag activated, the 'b' (no Branches) flag must not be set, because by setting that flag you won't allow lookup to write in a branch.
'm' (Method filtering) - this flag tells if the contact filtering based on supported methods should be performed during lookup.
'u' (User-Agent filtering) - this flag enables regexp filtering by user-agent. It's useful with enabled append_branches parameter. Regexp must follow the 'u' flag and must use format like 'u/regexp/'.
'i' (Case insensitive search) - this flag enables case insensitive filtering for the 'u' flag.
'e' (Use extended regexp) - this flag enables using of extended regexp format for the 'u' flag.
AOR (optional)- AOR to lookup for; if missing, the RURI is used as AOR; This must be a variable.
Return codes:
1 - contacts found and returned.
-1 - no contact found.
-2 - contacts found, but method not supported.
-3 - internal error during processing.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Example 1.19. lookup usage
...
lookup("location"); # simple lookup
#or
lookup("location","m"); # lookup with method filtering
#or
lookup("location","r"); #lookup with aor branch search;
#all contacts except the first one shall be put
#in the branches
#or
lookup("location","u/phone/i"); # lookup with user-agent filtering
#or
lookup("location","","$var(aor)"); # simple lookup with AOR from PV
switch ($retcode) {
case -1:
case -3:
sl_send_reply("404", "Not Found");
exit;
case -2:
sl_send_reply("405", "Not Found");
exit;
};
...