Skip to content

Latest commit

 

History

History
373 lines (303 loc) · 12.4 KB

service.md

File metadata and controls

373 lines (303 loc) · 12.4 KB
Raw

NkSIP Services' API

It is imporant to note that starting an nksip service, is really starting a nkservice service! An nkservice is a generic service that can be many different things, including in this case, a SIP service.

Much of the functionality of the nksip module is done via nkservice. There are helper or convinience functions here, that really just call nkservice functions.

NkSIP can be used as a stand-alone product or with other services available via nkservice.

This document describes the API that NkSIP makes available to Services.
The SIP-specific functions are available in the nksip.erl module, while other functions are available in the nkservice module.

See Also:

Function Description
start/2 Starts a new Service
stop/1 Stops a started Service
stop_all/0 Stops all started Services
update/2 Updates the configuration of a started Service
get_all_services/0 Gets all currenty started Services
get/2 Gets a value for a Service variable
get/3 Gets a value for a Service variable, with a default
put/3 Saves a vaule for a Service variable
del/2 Deletes a Service variable
get_srv_id/1 Finds the internal name for a currently started Service
call/2 Synchronous call to the Service's gen_server process
call/3 Synchronous call to the Service's gen_server process with timeout
cast/2 Asynchronous call to the Service's gen_server process
get_uuid/1 Get the current UUID for a stared Service

Functions list

start/4

Starts a new Service.

NkSIP returns the internal name of the application. In most API calls you can use the user defined name ServiceName or the internal generated id srv_id().

For now OptionsMapOrList can either be a list of tuples (which is the old way of doing things) or a map() which is the new way. Maps are preferred.

-spec start( ServiceName, OptionsMapOrList ) -> Result when 
            ServiceName      :: srv_name(), 
            OptionsMapOrList     :: optslist(),
            Result          :: {ok, srv_id()} 
                | {error, term()}.

Example(s):

nksip:start(test_server_1, #{
        sip_local_host => "localhost",
        callback => nksip_tutorial_server_callbacks,
        plugins => [nksip_registrar],
        sip_listen => "sip:all:5060, <sip:all:5061;transport=tls>"
    }).
{ok,armejl7}

or

nksip:start(client5, []).    %% Note the list() options.  See also Configuration notes below for options
{ok,bvdc609}

or

nksip:start(me2, #{}).     %% Note the map() options.  See also Configuration notes below for options
{ok,bbkj953}

See Also:

Note:

The srv_id() returned by this function is both the id, but it is also a real (compiled on the fly) name of an Erlang module. While you should not use it as a module, for developers it can be useful to know about this.


An example of the functions availble for the `bbkj953` module (also the `srv_id()`) are listed below: ```erlang ([email protected])5> bbkj953: class/0 config/0 config_nkservice/0 config_nksip/0 id/0 listen/0 listen_ids/0 log_level/0 module_info/0 module_info/1 name/0 nksip_authorize_data/3 nksip_call/3 nksip_connection_recv/4 nksip_connection_sent/2 nksip_debug/3 nksip_dialog_update/3 nksip_make_uac_dialog/4 nksip_method/2 nksip_parse_uac_opts/2 nksip_parse_uas_opt/3 nksip_route/4 nksip_transport_uac_headers/6 nksip_transport_uas_sent/1 nksip_uac_pre_request/4 nksip_uac_pre_response/3 nksip_uac_proxy_opts/2 nksip_uac_reply/3 nksip_uac_response/4 nksip_uas_dialog_response/4 nksip_uas_method/4 nksip_uas_process/2 nksip_uas_send_reply/3 nksip_uas_sent_reply/1 nksip_uas_timer/3 plugins/0 service_code_change/3 service_handle_call/3 service_handle_cast/2 service_handle_info/2 service_init/2 service_terminate/2 sip_ack/2 sip_authorize/3 sip_bye/2 sip_cancel/3 sip_dialog_update/3 sip_get_user_pass/4 sip_info/2 sip_invite/2 sip_message/2 sip_notify/2 sip_options/2 sip_publish/2 sip_refer/2 sip_register/2 sip_reinvite/2 sip_resubscribe/2 sip_route/5 sip_session_update/3 sip_subscribe/2 sip_update/2 timestamp/0 uuid/0 ```

stop/1

Stops a currently started Service.

Notice that the parameter for stop is either the user defined name ServiceName used with the nksip:start/2 function or the internal generated id srv_id() which was generated and returned with nksip:start/2

-spec stop( ServiceNameOrId ) -> Result when 
        ServiceNameOrId     :: srv_name()  
            | srv_id(),
        Result              :: ok 
            |  {error, not_running}.

Example(s):

(nksip_shell@127.0.0.1)7> nksip:stop(me2).    
11:04:18.384 [info] Plugin nksip stopped for service me2
ok

stop_all/0

Stops all currently started SIP Services.

-spec stop_all() -> 
    ok.

update/2

Updates the callback module or options of a running Service, on the fly.

You can change any configuration parameter on the fly, even for transports. See Configuration Options for a list of available configuration options.

See Configuration.

-spec update( ServiceNameOrId, OptionsMapOrList ) -> Result when 
            ServiceNameOrId     :: srv_name()
                | srv_id(),
            OptionsMapOrList         :: optslist(),
            Result              ::  {ok, srv_id()} 
                | {error, term()}.

Example(s):

> nksip:update(me, #{log_level => debug}).     %% NOTE: Using map() for options
11:31:39.701 [info] Skipping started transport {udp,{0,0,0,0},0}
11:31:39.734 [info] Added config: #{log_level => 8}
11:31:39.734 [info] Removed config: #{log_level => notice}
ok

or

> nksip:update(me, [{log_level, notice}]). 
11:32:16.524 [info] Skipping started transport {udp,{0,0,0,0},0}
11:32:16.555 [info] Added config: #{log_level => 6}
11:32:16.555 [info] Removed config: #{log_level => 8}
ok

See Also:

get_all_services/0

Gets Id, Name, Class and Pid of all started SIP Services.

-spec get_all_services() -> Result when 
    Result          :: [ ServiceData ],
    ServiceData     :: { Id, Name, Class, Pid },
    Id              :: nkservice:id(),
    Name            :: nkservice:name(),
    Class           :: nkservice:class(),
    Pid             :: nkservice:pid().

Example(s):

(nksip_shell@127.0.0.1)11> nksip:get_all_services().   
[{bo4yxv5,foo4,nksip,<0.1188.0>},
 {bvdc609,me,nksip,<0.168.0>}]

get/2

Get the Value into of a Key from the data storage. Each service has data storage options (See saving state information ) for storing things they want to store and get back.

NOTE: This is a convienance function for nkservice:get(ServiceNameOrId, Key)

-spec get(ServiceNameOrId, Key ) -> Result when 
            ServiceNameOrId     :: srv_name()
                | srv_id(),
            Key                 :: term(),
            Result              :: term().

Example(s):

> nksip:get(m2, hello_world).                    
  "Hello World"

See Also:

get/3

Get the Value of a Key from the data storage or `DefaultValue' if there is no stored value. Each service has data storage options (See saving state information ) for storing things they want to store and get back.

NOTE: This is a convienance function for nkservice:get(ServiceNameOrId, Key, DefaultValue)

-spec get(ServiceNameOrId, Key, DefaultValue ) -> Result when 
            ServiceNameOrId     :: srv_name()
                | srv_id(),
            Key                 :: term(),
            DefaultValue        :: term(),
            Result              :: term().

Example(s):

> nksip:get(m2, hello_jim, "Hello there, Jim!").                    
  "Hello there, Jim!"

See Also:

put/3

Inserts or Updates a Key and Value into data storage. Each service has data storage options (See saving state information ) for storing things they want to store and get back.

-spec put(ServiceNameOrId, Key, Value ) -> Result when 
            ServiceNameOrId     :: srv_name()
                | srv_id(),
            Key                 :: term(),
            Value               :: term(),
            Result              :: ok.

Example(s):

> nksip:put(m2, hello_world, "Hello World").
  ok

See Also:

del/2

Delete the Key and Value from the data store. Each service has data storage options (See saving state information ) for storing things they want to store and get back.

NOTE: This is a convienance function for nkservice:del(ServiceNameOrId, Key)

-spec del( ServiceNameOrId, Key ) -> ok when 
            ServiceNameOrId     :: srv_name()
                | srv_id(),
            Key                 :: term().

Example(s):

> nksip:del(m2, hello).
  ok

See Also:

find_srv_id/1

nkservice_server:get_srv_id(term()) ->
    {ok, srv_id()} | not_found.

Finds the internal name of an existing Service.

call/2

nkservice_server:call(nksip:srv_name()|nksip:srv_id(), term()) ->
    term().

Synchronous call to the Service's gen_server process. It is a simple gen_server:call/2 but allowing Service names.

call/3

nkservice_server:call(nksip:srv_name()|nksip:srv_id(), term(), pos_integer()|infinity) ->
    term().

Synchronous call to the Service's gen_server process. It is a simple gen_server:call/3 but allowing Service names.

cast/2

nkservice_server:cast(nksip:srv_name()|nksip:srv_id(), term()) ->
    term().

Asynchronous call to the Service's gen_server process. It is a simple gen_server:cast/2 but allowing Service names.

get_uuid/1

Gets the Service's UUID.

-spec get_uuid( ServiceNameOrId ) -> Result when 
            ServiceNameOrId     :: srv_name()
                | srv_id(),
            Result              :: binary().

Example(s):

nkserver:uuid(bbkj953). 	%% srv_id()
<<"<urn:uuid:545f1233-28d4-e321-93d7-28cfe9192deb>">>

or

nkserver:uuid(me2).    	%% srv_name()
<<"<urn:uuid:545f1233-28d4-e321-93d7-28cfe9192deb>">>