Module local

Interface to local functions hooking into lots of different parts of the various YXA applications.

Introduced in: 03 Jan 2006 by Fredrik Thulin <ft@it.su.se>

Authors: Fredrik Thulin (ft@it.su.se).

Description

Interface to local functions hooking into lots of different parts of the various YXA applications.

Function Index

can_register/2 Check if a REGISTER message authenticates OK etc.
can_use_address/2 Check if a user (authenticated elsewhere) may use an address.
can_use_address_detail/2 Check if a user (authenticated elsewhere) may use an address.
canonify_addresses/1 Canonify a list of addresses.
canonify_authusername/2 Possibly make us use another username for this request.
canonify_user/1 Turn a SIP username into an address which can be reached from anywhere.
check_config_type/3 Check a local configuration parameter.
config_change_action/3 Perform any necessary actions when a configuration value changes, like perhaps notifying a gen_server or similar.
config_is_soft_reloadable/2 Check if it is possible to change a local configuration parameter with a soft reconfiguration (true), or if a complete restart of the application is necessary (false).
cpl_is_log_dest/1
cpl_log/4
cpl_mail/2
create_dialog_state_uas/4 Create a dialog record out of a received request and some other parameters.
eventserver_locationdb_action/3
format_number_for_remote_party_id/3 Hook for the actual formatting once get_remote_party_number/2 has found a number to be formatted.
get_addresses_for_user/1 Gets all addresses for a user.
get_addresses_for_users/1
get_all_event_packages/0 Get list of all event packages.
get_classes_for_user/1
get_cpl_for_user/1 get the cpl script graph for a certain user.
get_event_package_module/3 Decide which event package should handle a request (SUBSCRIBE or PUBLISH) in the eventserver.
get_forwards_for_users/1
get_locations_for_users/1 Looks up all contacts for a list of users.
get_locations_with_contact/1 like get_user_with_contact but returns a list of siplocationdb_e records instead.
get_password_for_user/1
get_remote_party_name/2 When pstnproxy receives a request from a PSTN gateway, this function is called to see if we can find a nice Display Name for the calling party.
get_remote_party_number/4 This function is used by the pstnproxy to provide a PSTN gateway with usefull caller-id information.
get_telephonenumber_for_user/1
get_user_verified/2
get_user_verified_proxy/2
get_user_with_address/1 Looks up exactly one user with an Address.
get_user_with_contact/1 Checks if any of our users are registered at the location specified.
get_users_for_address_of_record/1 Looks up all users with a given address.
get_users_for_addresses_of_record/1
get_users_for_url/1
get_valid_altnames/3 Hook that lets you manipulate what names are considered valid for a SSL certificate presented by a host.
gruu_make_url/4 Make an URL out of a GRUU.
homedomain/1 Check if something is one of our 'homedomains' - a domain we are the final destination for.
incomingproxy_challenge_before_relay/3 Check if 'incomingproxy' should challenge a request that it has determined it should relay, or if it should proxy the request without authorization instead.
incomingproxy_request_homedomain_event/2
is_acceptable_socket/7 Verify a socket.
is_allowed_pstn_dst/4
is_gruu_url/1 Check if an URL possibly is a GRUU we've created.
is_request_to_this_proxy/1 Determine if a request is meant for this proxy itself, as opposed to say a user of the system.
is_tls_equivalent/3 If a destination (proto:host:port) is not TLS it might still be protected by an equivalence to TLS (like IPsec).
isours/1 lookup:isours/1.
lookup_address_to_users/1
lookup_addresses_to_users/1
lookup_homedomain_request/2 Determine where to route a request that arrived to the 'incomingproxy' application, destined for a local domain when it has been determined that the request was not addressed to one of our users (see local:lookupuser/1).
lookup_remote_request/2 Determine where to route a request that arrived to the 'incomingproxy' application, destined for a remote domain.
lookup_sipsocket_blacklist/1 Check if a destination is blacklisted/whitelisted.
lookup_url_to_addresses/2
lookup_url_to_locations/1
lookupappserver/1
lookupdefault/1
lookupenum/1
lookupnumber/1
lookuppotn/1
lookuppstn/1
lookupregexproute/1
lookupuser/1 The main 'give me a set of locations for one of our users' function that incomingproxy uses, when it determines that a request is for one of it's homedomains.
lookupuser_gruu/2 Look up a GRUU.
lookupuser_locations/2 Return all locations for a list of users that is suitable given a Request-URI.
new_request/3 This function gets called when the transaction layer has decided that a new request has arrived, and figured it should be passed to the YXA application (proxy core/ transaction user).
new_response/3 This function gets called when the transaction layer has decided that a response not assoicated with a running client transaction has arrived.
outgoingproxy_challenge_before_relay/3 Check if 'outgoingproxy' should challenge a request that it has determined it should relay, or if it should proxy the request without authorization instead.
prioritize_locations/2
pstnproxy_allowed_methods/2 Return list of allowed SIP methods.
pstnproxy_allowed_proxy_request/2 Decide if pstnproxy should proxy a request, or reject it with a '403 Forbidden'.
pstnproxy_auth_and_tag/4
pstnproxy_lookup_action/2
pstnproxy_number_based_routing/4
pstnproxy_route_pstn_not_e164/3 When a request destined for PSTN is received by the pstnproxy, and no destination is found using local:lookuppstn(), this function is called.
pstnproxy_verify_from/4
remove_unsuitable_locations/2 Apply local policy for what locations are good to use for a particular Request-URI.
rewrite_potn_to_e164/1
sippipe_received_response/3 When sippipe receives a final response, this function is called.
sipuserdb_backend_override/3 Hook to override a specific sipuserdb backend function.
sipuserdb_mysql_make_sql_statement/2 If you need to make SQL statements other than what is possible using the template-based configuration parameter possibilitys, do it here.
start_client_transaction/4 Start a client transaction, possibly after altering the request to be sent.
start_sippipe/4 Start a sippipe for one of the YXA applications incomingproxy, outgoingproxy or pstnproxy.
url2mnesia_userlist/1
user_has_cpl_script/1 determine if a cpl script has been loaded for the user User.
user_has_cpl_script/2 determine if a cpl script has been loaded for the user User.

Function Details

can_register/2

can_register(Header, ToURL) -> {{Verdict, Reason}, User} | {stale, User} | {false, none}

Check if a REGISTER message authenticates OK etc. See sipauth module for more information.

See also: sipauth:can_register/2.

can_use_address/2

can_use_address(User, URL) -> true | false

Check if a user (authenticated elsewhere) may use an address. See sipauth module for more information.

See also: sipauth:can_use_address/2.

can_use_address_detail/2

can_use_address_detail(User, URL) -> {Verdict, Reason}

Check if a user (authenticated elsewhere) may use an address. See sipauth module for more information.

See also: sipauth:can_use_address_detail/2.

canonify_addresses/1

canonify_addresses(In) -> [string()]

Canonify a list of addresses. Turn anything numeric into it's E.164 canonical representation. Used from some userdb-modules which potentially get non-fully qualified phone numbers (like local extension numbers) back from the database.

canonify_authusername/2

canonify_authusername(Username, Header) -> NewUsername | undefined

Possibly make us use another username for this request. This is needed if your user database allows more than one username per user, or if you have clients that does not allow you to set authorization username explicitly and the username they assume you have is incorrect.

canonify_user/1

canonify_user(User) -> string()

Turn a SIP username into an address which can be reached from anywhere. Used for example from the Mnesia userdb-module. It should be possible to call Mnesia users based on their username, but the username might need sip: prepended to it, or a default domain name appended to it.

check_config_type/3

check_config_type(Key, Value, Src) -> {ok, NewValue} | {error, Msg}

Check a local configuration parameter. Local parameters are local_*.

config_change_action/3

config_change_action(Key, Value, Mode) -> ok | {error, Reason}

Perform any necessary actions when a configuration value changes, like perhaps notifying a gen_server or similar.

config_is_soft_reloadable/2

config_is_soft_reloadable(Key, Value) -> true | false

Check if it is possible to change a local configuration parameter with a soft reconfiguration (true), or if a complete restart of the application is necessary (false).

cpl_is_log_dest/1

cpl_is_log_dest(LogName) -> term()

cpl_log/4

cpl_log(LogName, Comment, User, Request) -> term()

cpl_mail/2

cpl_mail(Mail, User) -> term()

create_dialog_state_uas/4

create_dialog_state_uas(Caller, Request, ToTag, Contact) -> {ok, Dialog}

Create a dialog record out of a received request and some other parameters.

See also: sipdialog:create_dialog_state_uas/3.

eventserver_locationdb_action/3

eventserver_locationdb_action(Type, User, Location) -> term()

format_number_for_remote_party_id/3

format_number_for_remote_party_id(Number, Header, DstHost) -> {ok, Number}

Hook for the actual formatting once get_remote_party_number/2 has found a number to be formatted.

See also: lookup:format_number_for_remote_party_id/3.

get_addresses_for_user/1

get_addresses_for_user(User) -> term()

Gets all addresses for a user. Used for example to check if a request from a user has an acceptable From: header.

See also: sipuserdb:get_addresses_for_user/1.

get_addresses_for_users/1

get_addresses_for_users(Users) -> term()

See also: sipuserdb:get_addresses_for_users/1.

get_all_event_packages/0

get_all_event_packages() -> {ok, PackageDefs}

Get list of all event packages. Duplicate Package is allowed (and has a purpose, if you want to have more than one possible Module for a Package (decided using get_event_package_module/3 above).

get_classes_for_user/1

get_classes_for_user(User) -> term()

See also: sipuserdb:get_classes_for_user/1.

get_cpl_for_user/1

get_cpl_for_user(User) -> nomatch | {ok, CPLGraph}

get the cpl script graph for a certain user

See also: cpl_db:get_cpl_for_user/1.

get_event_package_module/3

get_event_package_module(EventPackage, Request, YxaCtx) -> {ok, PackageModule} | undefined

Decide which event package should handle a request (SUBSCRIBE or PUBLISH) in the eventserver. You can use this to make only certain SUBSCRIBE/PUBLISH requests go to a custom event package. Remember to make get_all_event_packages return any additions too.

get_forwards_for_users/1

get_forwards_for_users(Users) -> term()

See also: sipuserdb:get_forwards_for_users/1.

get_locations_for_users/1

get_locations_for_users(Users) -> term()

Looks up all contacts for a list of users. Used to find out where a set of users are to see where we should route a request.

See also: siplocation:get_locations_for_users/1.

get_locations_with_contact/1

get_locations_with_contact(URI) -> term()

like get_user_with_contact but returns a list of siplocationdb_e records instead

See also: siplocation:get_locations_with_contact/1.

get_password_for_user/1

get_password_for_user(User) -> term()

See also: sipuserdb:get_password_for_user/1.

get_remote_party_name/2

get_remote_party_name(Key, DstHost) -> {ok, DisplayName} | none

When pstnproxy receives a request from a PSTN gateway, this function is called to see if we can find a nice Display Name for the calling party. By default, we only do the actual lookup if we can rewrite Key into a E.164 number.

See also: lookup:get_remote_party_name/2.

get_remote_party_number/4

get_remote_party_number(User, Header, URI, DstHost) -> {ok, Number} | none

This function is used by the pstnproxy to provide a PSTN gateway with usefull caller-id information. PSTN networks typically gets upset if the "A-number" (calling party) is a SIP URL. Different gateways might want the number formatted differently, thus the DstHost parameter (a TSP gateway to PSTN might only handle E.164 numbers, while a PBX might be expecting only a 4-digit extension number).

See also: lookup:get_remote_party_number/4.

get_telephonenumber_for_user/1

get_telephonenumber_for_user(User) -> term()

See also: sipuserdb:get_telephonenumber_for_user/1.

get_user_verified/2

get_user_verified(Header, Method) -> term()

See also: sipauth:get_user_verified/2.

get_user_verified_proxy/2

get_user_verified_proxy(Header, Method) -> term()

See also: sipauth:get_user_verified_proxy/2.

get_user_with_address/1

get_user_with_address(Address) -> term()

Looks up exactly one user with an Address. Used for example in REGISTER. If there are multiple users with an address, this function returns {error}.

See also: sipuserdb:get_user_with_address/1.

get_user_with_contact/1

get_user_with_contact(URI) -> term()

Checks if any of our users are registered at the location specified. Used to determine if we should proxy requests to a URI without authorization.

See also: siplocation:get_user_with_contact/1.

get_users_for_address_of_record/1

get_users_for_address_of_record(Address) -> term()

Looks up all users with a given address. Used to find out to which users we should send a request.

See also: sipuserdb:get_users_for_address_of_record/1.

get_users_for_addresses_of_record/1

get_users_for_addresses_of_record(Addresses) -> term()

See also: sipuserdb:get_users_for_addresses_of_record/1.

get_users_for_url/1

get_users_for_url(URL) -> term()

See also: sipuserdb:get_users_for_url/1.

get_valid_altnames/3

get_valid_altnames(Names, Subject, AltNames) -> NewAltNames

Hook that lets you manipulate what names are considered valid for a SSL certificate presented by a host. If, for example, the host p1.example.org returns a certificate with the subjectAltNames, Names might be ["example.org"] since a user tried to reach sip:user@example.org, and AltNames might be ["p1.example.org"]. In this case, you must add "example.org" to AltNames, to allow the certificate.

gruu_make_url/4

gruu_make_url(User, InstanceId, GRUU, To) -> URL | undefined

Make an URL out of a GRUU. Return 'undefined' for default algorithm.

See also: foo.

homedomain/1

homedomain(Domain) -> true | false

Check if something is one of our 'homedomains' - a domain we are the final destination for.

See also: lookup:homedomain/1.

incomingproxy_challenge_before_relay/3

incomingproxy_challenge_before_relay(Origin, Request, Dst) -> term()

Check if 'incomingproxy' should challenge a request that it has determined it should relay, or if it should proxy the request without authorization instead.

incomingproxy_request_homedomain_event/2

incomingproxy_request_homedomain_event(Request, Origin) -> term()

is_acceptable_socket/7

is_acceptable_socket(Socket, Dir, Proto, Host, Port, Module, Subject) -> true | false | undefined

Verify a socket. Return 'true' for acceptable, 'false' for NOT acceptable and 'undefined' to do default checks.

is_allowed_pstn_dst/4

is_allowed_pstn_dst(User, ToNumber, Header, Class) -> bool()

See also: sipauth:is_allowed_pstn_dst/4.

is_gruu_url/1

is_gruu_url(URL) -> {true, GRUU} | false

Check if an URL possibly is a GRUU we've created.

See also: gruu:is_gruu_url/1.

is_request_to_this_proxy/1

is_request_to_this_proxy(Request) -> true | false

Determine if a request is meant for this proxy itself, as opposed to say a user of the system.

See also: lookup:is_request_to_this_proxy/1.

is_tls_equivalent/3

is_tls_equivalent(Proto, Host, Port) -> true | false | undefined

If a destination (proto:host:port) is not TLS it might still be protected by an equivalence to TLS (like IPsec). When we require a TLS-protected destination, this hook lets you indicate that a particular destination is to be considered secure at the transport layer.

isours/1

isours(URL) -> term()

lookup:isours/1.

See also: foo.

lookup_address_to_users/1

lookup_address_to_users(Address) -> term()

See also: lookup:lookup_address_to_users/1.

lookup_addresses_to_users/1

lookup_addresses_to_users(Addresses) -> term()

See also: lookup:lookup_addresses_to_users/1.

lookup_homedomain_request/2

lookup_homedomain_request(Request, Origin) -> {proxy, PDst} | {relay, RDst} | {error, S} | {response, S, R} | {forward, Fwd} | none

Determine where to route a request that arrived to the 'incomingproxy' application, destined for a local domain when it has been determined that the request was not addressed to one of our users (see local:lookupuser/1). Return 'none' for default routing.

lookup_remote_request/2

lookup_remote_request(Request, Origin) -> {proxy, PDst} | {relay, RDst} | {error, S} | {response, S, R} | {forward, Fwd} | none

Determine where to route a request that arrived to the 'incomingproxy' application, destined for a remote domain. Return 'none' to perform default routing.

lookup_sipsocket_blacklist/1

lookup_sipsocket_blacklist(Dst) -> {ok, Entry} | {ok, blacklisted} | {ok, whitelisted} | undefined

Check if a destination is blacklisted/whitelisted. Return 'undefined' for default processing.

See also: sipsocket_blacklist:lookup_sipsocket_blacklist/1.

lookup_url_to_addresses/2

lookup_url_to_addresses(Src, URL) -> term()

See also: lookup:lookup_url_to_addresses/2.

lookup_url_to_locations/1

lookup_url_to_locations(URL) -> term()

See also: lookup:lookup_url_to_locations/1.

lookupappserver/1

lookupappserver(Key) -> term()

See also: lookup:lookupappserver/1.

lookupdefault/1

lookupdefault(URL) -> term()

See also: lookup:lookupdefault/1.

lookupenum/1

lookupenum(Number) -> term()

See also: lookup:lookupenum/1.

lookupnumber/1

lookupnumber(Number) -> term()

See also: lookup:lookupnumber/1.

lookuppotn/1

lookuppotn(Number) -> term()

See also: lookup:lookuppotn/1.

lookuppstn/1

lookuppstn(Number) -> term()

See also: lookup:lookuppstn/1.

lookupregexproute/1

lookupregexproute(User) -> term()

See also: lookup:lookupregexproute/1.

lookupuser/1

lookupuser(URL) -> {proxy, URL} | {relay, URL} | {forward, URL} | {response, Status, Reason} | none | nomatch

The main 'give me a set of locations for one of our users' function that incomingproxy uses, when it determines that a request is for one of it's homedomains.

See also: lookup:lookupuser/1.

lookupuser_gruu/2

lookupuser_gruu(URL, GRUU) -> {proxy, URL} | {relay, URL} | {forward, URL} | {response, Status, Reason} | none | nomatch

Look up a GRUU. Used by incomingproxy and outgouingproxy.

See also: lookup:lookupuser_gruu/2.

lookupuser_locations/2

lookupuser_locations(Users, URL) -> Locations

Return all locations for a list of users that is suitable given a Request-URI. By suitable, we mean that we filter out SIP locations if Request-URI was SIPS, unless this proxy is configured not to.

See also: lookup:lookupuser_locations/2.

new_request/3

new_request(AppModule, Request, YxaCtx) -> undefined | ignore | {modified, NewAppModule, NewRequest, NewOrigin, NewLogStr}

This function gets called when the transaction layer has decided that a new request has arrived, and figured it should be passed to the YXA application (proxy core/ transaction user). Depending on what this function returns, the AppModule:request/2 function will either not be called at all, called with the parameters unchanged or called with a modified set of parameters. Note : DON'T ALTER THE URI OF INVITE REQUESTS HERE! If you do, the ACKs of non-2xx responses will be disqualified by the server transaction since the URI of the ACK doesn't match the URI of the original INVITE (since you changed it).

new_response/3

new_response(AppModule, Response, YxaCtx) -> undefined | ignore | {modified, NewAppModule, NewResponse, NewOrigin, NewLogStr}

This function gets called when the transaction layer has decided that a response not assoicated with a running client transaction has arrived. Such responses should be passed to the YXA application (proxy core/transaction user). Depending on what this function returns, the AppModule:response/2 function will either not be called at all, called with the parameters unchanged or called with a modified set of parameters.

outgoingproxy_challenge_before_relay/3

outgoingproxy_challenge_before_relay(Origin, Request, Dst) -> term()

Check if 'outgoingproxy' should challenge a request that it has determined it should relay, or if it should proxy the request without authorization instead.

prioritize_locations/2

prioritize_locations(Key, Locations) -> term()

See also: siplocation:prioritize_locations/1.

pstnproxy_allowed_methods/2

pstnproxy_allowed_methods(Request, PstnCtx) -> {ok, AllowedMethods}

Return list of allowed SIP methods. Must be upper-cased.

pstnproxy_allowed_proxy_request/2

pstnproxy_allowed_proxy_request(Request, PstnCtx) -> true | false | undefined

Decide if pstnproxy should proxy a request, or reject it with a '403 Forbidden'. Return 'undefined' for default processing.

pstnproxy_auth_and_tag/4

pstnproxy_auth_and_tag(Request, Origin, THandler, PstnCtx) -> term()

pstnproxy_lookup_action/2

pstnproxy_lookup_action(Request, PstnCtx) -> term()

pstnproxy_number_based_routing/4

pstnproxy_number_based_routing(Request, THandler, LogTag, PstnCtx) -> term()

pstnproxy_route_pstn_not_e164/3

pstnproxy_route_pstn_not_e164(DstNumber, Request, PstnCtx) -> undefined | nomatch | ignore | Relay

When a request destined for PSTN is received by the pstnproxy, and no destination is found using local:lookuppstn(), this function is called. The return values have the following meaning : undefined - proceed with default behavior nomatch - there is no destination for DstNumber, reject request with a '404 Not Found' ignore - pstnproxy should do nothing further (this function must generate a final response) Response - send a response Relay - send Request to DstURI

pstnproxy_verify_from/4

pstnproxy_verify_from(Request, THandler, YXAPeerAuth, PstnCtx) -> term()

remove_unsuitable_locations/2

remove_unsuitable_locations(URL, Locations) -> [#sipurl{}]

Apply local policy for what locations are good to use for a particular Request-URI.

See also: lookup:remove_unsuitable_locations/2.

rewrite_potn_to_e164/1

rewrite_potn_to_e164(Key) -> term()

See also: lookup:rewrite_potn_to_e164/1.

sippipe_received_response/3

sippipe_received_response(Request, Response, DstList) -> undefined | {huntstop, Status, Reason} | {next, NewDstList}

When sippipe receives a final response, this function is called. Depending on the return value of this function, sippipe will behave differently. 'undefined' means sippipe will fall back to it's default 'huntstop' will make sippipe stop processing and instruct the server transaction to send a response (Status, Reason). 'next' will tell sippipe to try the next destination in NewDstList (possibly altered version of DstList).

sipuserdb_backend_override/3

sipuserdb_backend_override(Module, Function, Args) -> {ok, Res} | undefined

Hook to override a specific sipuserdb backend function. If 'undefined' is returned, the real backend function will be called

sipuserdb_mysql_make_sql_statement/2

sipuserdb_mysql_make_sql_statement(CfgKey, Args) -> {ok, Res} | undefined

If you need to make SQL statements other than what is possible using the template-based configuration parameter possibilitys, do it here. Return 'undefined' to let sipuserdb_mysql do it's default query construction. Note : You have to mysql:quote() everything you use from Args!

start_client_transaction/4

start_client_transaction(Request, Dst, Branch, Timeout) -> Pid | {error, Reason}

Start a client transaction, possibly after altering the request to be sent.

See also: transactionlayer:start_client_transaction/5.

start_sippipe/4

start_sippipe(Request, YxaCtx, Dst, AppData) -> term()

returns: result of sipppipe:start/5

Start a sippipe for one of the YXA applications incomingproxy, outgoingproxy or pstnproxy. This is a very suitable place to for example add/delete headers.

See also: sippipe:start/5.

url2mnesia_userlist/1

url2mnesia_userlist(URL) -> term()

user_has_cpl_script/1

user_has_cpl_script(User) -> true | false

determine if a cpl script has been loaded for the user User

See also: cpl_db:user_has_cpl_script/1.

user_has_cpl_script/2

user_has_cpl_script(User, Direction) -> true | false

determine if a cpl script has been loaded for the user User

See also: cpl_db:user_has_cpl_script/1.


Generated by EDoc, Oct 17 2007, 16:48:25.