Module eturnal_module

An eturnal module adds functionality to the eturnal server.

This module defines the eturnal_module behaviour.
Required callback functions: handle_event/2, options/0.
Optional callback functions: start/0, stop/0.

Description

An eturnal module adds functionality to the eturnal server. It is to be named mod_foo, where foo describes the added functionality. The module must export handle_event/2 and options/0 callbacks, and may optionally export start/0 and stop/0 functions.

The optional start/0 function must return ok or {ok, Events}, where Events is the list of events the module is interested in. Currently, the following events may be triggered: stun_query, turn_session_start, and turn_session_stop. If the start/0 function doesn't return a list of events (or returns {ok, [all]}), the handle_event/2 callback will be called for all events.

The handle_event/2 function is called with the event name as the first argument and a map with metadata related to the event as the second. The contents of that map depend on the event. Note that the handle_event/2 callback is executed by the process handling the STUN/TURN session, so it should never block. If it might, and/or if it needs some #state{}, one or more handler processes must be created.

The options/0 callback returns an options() tuple with two elements. The first is a map of configuration options, where the keys are the option names specified as atom()s, and the values are functions that validate the option values. Those functions are returned by the yval library. The second tuple element is a list of optional tuples to specify {required, [Options]} and/or {defaults, #{Option => Value}}. For example:

   options() ->
       {#{threshold => yval:pos_int()},
        [{defaults,
         #{threshold => 42}}]}.

The option values are queried by calling eturnal_module:get_opt/2 with the ?MODULE name as the first and the option name as the second argument. Note that the lookup is very efficient, so there's no point in saving option values into some #state{}.

The optional stop/0 function must return ok. Note that the start/0 and stop/0 functions might not just be called on eturnal startup and shutdown, but also on configuration reloads.

If the module depends on other applications, those must be added to the rebar.config file, but not to the app file. They are to be started by calling eturnal_module:ensure_deps/2, where the first argument is the ?MODULE name and the second is the dependency's name.

The module is enabled by adding its configuration to the modules section of eturnal's configuration file as described in doc/overview.edoc. The module configuration options are to be documented in that file as well.

Data Types

dep()

dep() = atom()

event()

event() = atom()

events()

events() = [atom()]

info()

info() = #{atom() => term()}

option()

option() = atom()

options()

options() = {yval:validators(), yval:validator_option()}

Function Index

ensure_deps/2
get_opt/2
handle_event/2
options/1
start/1
stop/1

Function Details

ensure_deps/2

ensure_deps(Mod::module(), Deps::[dep()]) -> ok | no_return()

get_opt/2

get_opt(Mod::module(), Opt::option()) -> term()

handle_event/2

handle_event(Event::event(), Info::info()) -> ok

options/1

options(Mod::module()) -> options()

start/1

start(Mod::module()) -> ok | {error, term()}

stop/1

stop(Mod::module()) -> ok | {error, term()}


Generated by EDoc