# Functions

## `is_local(domain)`

This function can be used to test whether a given domain name in parameter belongs to one of the virtual domains defined in the domain table. Such domain name is said to be local. The function returns 1 if the domain name is found in the domain table and -1 otherwise.

The first parameter of the function can be anything that returns a string with domain name. In its simplest form it can be a string with domain name: is_local("iptel.org"). You can also test a domain name stored in an attribute: is_local("$my_domain"). And finally you can test a domain name present in the SIP message with selects: is_local("@ruri.host").

Note: Unlike function `lookup_domain`, this function does not make domain attributes of the virtual domain available to the script. Domain attributes are simply ignored by this function.

### is_uri_host_local_local usage

    ...
    if (is_local("@ruri.host")) {
        /* Domain part of Request-URI is local */
    }
    ...

## `lookup_domain(attr_group, domain)`

This is the main function of the domain module. It can be used to implement support for virtual domains in the SIP server. Each virtual domain is identified by a unique identifier (opaque string) and it can have one or more associated domain names. Given a domain name in the second parameter, this function finds the associated virtual domain identifier (known as DID) and stores it in an attribute for later use. In addition to that the function also loads all domain-level attributes for the virtual domain and makes them available to the configuration script.

The first parameter of the function identifies the group of attributes where the DID and domain-level attributes shall be stored. The value of the first parameter can be either "$fd" for the domain-level attribute group that belongs to the calling party (From), or "$td" for the domain-level attribute group that belongs to the called party (Request-URI).

The value of the second parameter can be a simple string, an attribute name, or a select. See the documentation of function `is_local` for more details.

If a match is found then the DID of the virtual domain will be stored either in $fd.did or in $td.did, depending on the value of the first parameter. In addition to that domain-level attributes, if any, will be available as either $fd. or $td..

The function returns 1 when a matching virtual domain for the given domain name was found and -1 otherwise.

The following example shows a typical use of the function. In a multi domain setup, one has usually to figure out whether both the calling and the called domains are local (i.e. configured on the server as the domains the server is responsible for). This is typically done by calling function `lookup_domain` twice, once with the hostname part of the From header as parameter and secondly with the hostname part of the Request-URI as parameter.

The type of the situation can be then determined from the value of corresponding attributes ($td.did and $fd.did). A non-existing attribute value indicates that the domain name is not local (it does not belong to any virtual domain configured in the domain table).

### lookup_domain usage

    lookup_domain("$fd", "@from.uri.host");
    lookup_domain("$td", "@ruri.host");

    if (strempty($fd.did) && strempty($td.did)) {
        # Neither the calling nor the called domain is local
        # This is a relaying attempt which should be forbidden
        sl_reply("403", "Relaying Forbidden");
        drop;
    }
    if (strempty($fd.did) && $td.did) {
        # The calling domain is not local and the called domain
        # is local, this is an inbound call from a 3rd party
        # user to one of local users
    }
    if ($fd.did && strempty($td.did)) {
        # The calling domain is local and the called domain
        # is not local, this is an outbound call from one of
        # our users to a 3rd party user
    }
    if ($fd.did && $td.did) {
        # Both the calling and the called domains are local,
        # one of our local users calls another local user,
        # either in the same virtual domain or in another
        # virtual domain hosted on the same server
    }