ejabberd_local:route_iq/4
I see that as of 2.1.x, ejabberd_local has a route_iq function that supports a callback function to be run when the IQ either times out (apparently after 32 seconds) or completes. This is extremely useful. Some XEP-type modules, like mod_ping, use this function, suggesting that it is a public API, but it is not documented (I am sure this is true of some other APIs).
The question is: May we module developers use this undocumented-but-may-be-documented-in-the-future-API, or do we have to duplicate the functionality?
API
route_iq(From, To, IQ, F)
Example from mod_ping
%% ...
F = fun(Response) ->
gen_server:cast(Pid, {iq_pong, JID, Response})
end,
From = jlib:make_jid("", State#state.host, ""),
ejabberd_local:route_iq(From, JID, IQ, F),
%% ... etc ...It seems that the fun gets called either with the IQ response, or with the atom 'timeout' if the IQ timed out.
emofine
ejabberd_local:route_iq/4
Some XEP-type modules, like mod_ping, use this function, suggesting that it is a public API,
Technically speaking, all exported functions can be used by other erlang modules. Even if a function isn't used in ejabberd itself, it may be used in other modules of ejabberd-modules SVN, other public modules, or private modules. So, all exported functions are modified with care to maintain backwards API compatibility.
but it is not documented (I am sure this is true of some other APIs).
In fact, there are still more functions exported and undocumented, that exported and documented.
May we module developers use this undocumented-but-may-be-documented-in-the-future-API,
or do we have to duplicate the functionality?
Use this and any other exported function, even if it isn't documented yet.
The only problem would be if the function API changes in the future in an incompatible way, and you miss the comment in the git log or in the release notes. But at least in the case of ejabberd_local, which is an old and stable part of ejabberd, API changes are very improbable to happen.
Thanks
Thanks very much!!