Introduction
ejabber internal modules can add themselves to the route table of the server with an XMPP name. These modules are known as "services".
The services modules must use the "gen_server" behavior in addition of "gen_mod".
Example
mod_echo.erl is good example of a module using the route mechanism.
API
ejabberd_router:register_route(Host) ejabberd_router:unregister_route(Host), * Host = string()
Host is the XMPP name of the module.
gen_server API
The following three functions can be used as shown below as the API of the module, as long as a PROCNAME macro as been define to name the module's thread.
start_link(Host, Opts) ->
Proc = gen_mod:get_module_proc(Host, ?PROCNAME),
gen_server:start_link({local, Proc}, ?MODULE, [Host, Opts], []).
start(Host, Opts) ->
Proc = gen_mod:get_module_proc(Host, ?PROCNAME),
ChildSpec = {Proc,
{?MODULE, start_link, [Host, Opts]},
temporary,
1000,
worker,
[?MODULE]},
supervisor:start_child(ejabberd_sup, ChildSpec).
stop(Host) ->
Proc = gen_mod:get_module_proc(Host, ?PROCNAME),
gen_server:call(Proc, stop),
supervisor:terminate_child(ejabberd_sup, Proc),
supervisor:delete_child(ejabberd_sup, Proc).
gen_server callbacks
The following functions must be defined and exported by the module.
init([Host, Opts]) -> {ok, State} |
{ok, State, Timeout} |
ignore |
{stop, Reason}
handle_info(Info, State) -> {noreply, State} |
{noreply, State, Timeout} |
{stop, Reason, State}
* Info = {route, From, To, Packet}
* To = From = #jid (see jlib core module)
* Packet = {xmlelement, Name, Attrs, SubEl}
terminate(Reason, State) -> void()
handle_call(stop, _From, State) ->
{stop, normal, ok, State}.
handle_cast(_Msg, State) ->
{noreply, State}.
code_change(_OldVsn, State, _Extra) ->
{ok, State}.
The init callback is used to initialize the module. Host is the name of the virtual host where the module runs. Opts is a list of the module options set in the configuration file, that can be retrive with the gen_mod:get_opt/3 function. The ejabberd_router:register_route/1 function is run in this callback.
terminate/2 is used to stop the module. The ejabberd_router:unregister_route function is run in this callback.
handle_info/2 is used to receive XMPP packets send to the module. ejabberd_router:route/3 is used to reroute packets.
All other callbacks can be written as shown above.
