Most useful API functions from the core ejabberd modules.

Router (ejabberd_router)

This module is the main router for XMPP packets on each node. It routes packets based on their destination domains. It has two tables: local and global routes. First, the destination domain of each packet is searched in local table. If found, the packet is routed to the appropriate process. Else, it searches in global table, and routes to the appropriate ejabberd node or process. If it does not exists in either tables, then the packet is sends to the S2S manager.

API

route/3

route(From, To, Packet)
* Packet = {xmlelement, Name, Attrs, SubEl}
* Attrs = [{Name, Value}]
* Name = Value = string()
* SubEl = Packet

Route an XML packet.

register_route/1 and unregister_route/1

register_route(Host)
unregister_route(Host),
* Host = string()

Host is the XMPP name of the route name. See the routage mechanism of services for more details.

dirty_get_all_routes/0

dirty_get_all_routes() -> [RouteName]
* RouteName = string()

Return a list of all registered route names.

dirty_get_all_domains/0

dirty_get_all_domains() -> [Domains]
* Domains = string()

Return a list of all known domains.

Local router (ejabberd_local)

This module routes packets which have a destination domain equal to one of the virtual host name of the server. If destination JID has a non-empty user part, then it routes packets to the session manager, else it is processed depending on it's content.

Session manager (ejabberd_sm)

Handle the currently opened sessions.

This module routes packets to local users. It determines which user resource the packet must be sent via the presence table. If this resource is connected to this node, it is routed to the C2S manager. If it's connected via another node, then the packet is sent to the session manager on that node.

API

get_user_resources/2

get_user_resources(User, Server)
* User = Server = string()

Returns all the resources of a connected user.

dirty_get_sessions_list/0

dirty_get_sessions_list() -> [JID]
* JID = {Username, Host, Resource}
* Username = Host = Resource = string()

Returns the JID of all opened sessions.

get_vh_session_list/0

get_vh_session_list(Host) -> [JID]
* JID = {Username, Host, Resource}
* Username = Host = Resource = string()

Returns the JID of all opened sessions on a virtual host.

dirty_get_my_sessions_list/0

dirty_get_my_sessions_list() -> [{SID, JID, User, Priority}]
* SID = {Time, pid()}
* Time = {MegaSecs, Secs, MicroSecs} (see erlang:now/0)
* JID = {Username, Host, Resource}
* User = {Username, Host}
* Username = Host = Resource = string()
* Priority = integer()

Returns all the opened sessions.
The second element of SID is the PID of the opened connection.

S2S manager (ejabberd_s2s)

Handle the S2S connections.

This module routes packets to other XMPP servers. First, it checks if an open S2S connection from the domain of the source packet to the domain of destination packet already exists. If it is open on another node, it routes the packet to the S2S manager on that node. If it is open on this node, it is routed to the process that serves this connection. If a connection does not exist, then it is opened and registered.

API

have_connection/1

have_connection({From, To}) -> bool()
* From = To = string()

Return true if a S2S connection exists between From and To hosts.

dirty_get_connections/0

dirty_get_connections/0() -> [{From, To}]
* From = To = string()

Return all the S2S connections opened.

C2S manager (ejabberd_c2s)

Handle the C2S connections.

API

get_presence/1

get_presence(PID) -> {Username, Resource, Presence, Status}
* PID = pid()
* Username = Resource = Presence = Status = string()

PID is the PID of the C2S connection.

XML utilities (xml)

Various utilities to manipulate XML packets.

XML representation in ejabberd

Each XML stanza is represented with the following tuple:

XMLElement = {xmlelement, Name, Attrs, [ElementOrCDATA]}
        Name = string()
        Attrs = [Attr]
        Attr = {Key, Val}
        Key = string()
        Val = string()
        ElementOrCDATA = XMLElement | CDATA
        CDATA = {xmlcdata, string()}

E.=C2=A0g. this stanza:

<message to='test@conference.example.org' type='groupchat'>
  <body>test</body>
</message>

is represented as the following structure:

{xmlelement, "message",
    [{"to", "test@conference.example.org"},
     {"type", "groupchat"}],
    [{xmlelement, "body",
         [],
         [{xmlcdata, "test"}]}]}}

API

element_to_string(El) -> string()El = XMLElementReturns string representation of XML stanzaEl.
* crypt(S) -> string()S = string()

Returns string which correspond to S with encoded XML special characters.

remove_cdata(ECList) -> EListECList = [ElementOrCDATA]
* EList = [XMLElement]

EList is a list of all non-CDATA elements of ECList.

get_path_s(El, Path) -> ResEl = XMLElementPath = [PathItem]
* PathItem = PathElem | PathAttr | PathCDATA
* PathElem = {elem, Name}
* PathAttr = {attr, Name}
* PathCDATA = cdata
* Name = string()
* Res = string() | XMLElement

If Path is empty, then returns El. Else sequentially consider elements of Path. Each element is one of:

• {elem, Name}: Name is the name of subelement of El, if such element exists, then this element is considered in following steps, else returns empty string.
• {attr, Name}: If El have attribute Name, then returns value of this attribute, else returns empty string.
• cdata: returns CDATA of El.

Relational database (ejabberd_odbc)

Used to run SQL queries.

API

The odbc_server configuration directive is used to set the connection parameters to the database.

Query without transaction

sql_query(Server, Request)
* Server = Request = string()

Run an SQL Request. Server is the name of the virtual host.

Query with transaction

sql_query_t(Request)
sql_transaction(Server, Fun)
* Server = Request = string()
* Fun = fun()

sql_transaction/2 is used to run some SQL requests, executed in the Fun function. Server is the name of the virtual host.
sql_query_t/1 is used to run an SQL Request and can only be executed in the function called by sql_transaction/2.

Utilities (jlib)

Various helper functions. Modules should include the jlib.hrl file in order to use the records defined by this module.

API

JID handling

-record(jid, {user, server, resource, luser, lserver, lresource}).

Define a JID. The fields beginning with 'l' are the normalized lowercase versions of the three first ones.

make_jid(User, Server, Ressource) -> #jid
make_jid({User, Server, Ressource}) -> #jid
string_to_jid(JID) -> #jid
jid_to_string(#jid) -> JID
* JID = Username = Server = Resource = string()

Create a #jid from string and vice versa.

IQ handling

-record(iq, {id = "", type, xmlns = "", lang = "", sub_el}).
* type = get | set
* sub_el = {xmlelement, Name, Attrs, SubEl}
* Attrs = [{Name, Value}]
* Name = Value = string()
* SubEl = Packet

Define an IQ.

iq_query_info(Packet) -> #iq
iq_to_xml(#iq) -> Packet
* Packet = {xmlelement, Name, Attrs, SubEl}
* Attrs = [{Name, Value}]
* Name = Value = string()
* SubEl = Packet

Create an IQ from a Packet and vice versa.

XMPP errors

make_error_reply(Packet, Error) -> ErrorPacket
* Packet = ErrorPacket = {xmlelement, Name, Attrs, SubEl}
* Error = ?STANZA_ERROR/3

Return a XMPP error packet. Packet is the XMPP packet initially received. Error is one of the ERR_* macros defined in jlib.hrl

Miscanelleous

tolower(string()) -> string()

Modules utilities (gen_mod)

Utility functions useful in a module.

API

get_opt/2 and get_opt/3

get_opt(Opt, Opts) -> Value
get_opt(Opt, Opts, Default) -> Value
get_module_opt(Host, Module, Opt, Default) -> Value
Opts = [{Opt, Value}]
Opt = Default = Value = Host = string()

Return the value associated to Opt. Opts is the list passed as the second parameter of the start/2 of the module. If the Opt option is not set in the configuration file, Default is used instead.

get_hosts/2

get_hosts(Opts, Prefix) ->
Prefix = string()
Opts = [{Opt, Value}]

Returns the XMPP name of the module as set by the host or hosts configuration option. If not set, the name of the module is constructed by appending Prefix to the virtual host name.

get_module_proc/2

get_module_proc(Host, Base) -> Procname
Host = string()
Base = Procname = atom()

Host is the name of the virtual host. Base is a unique name corresponding to the module (?MODULE can be used).
Return the name of the thread associated to the module by appending Base to Host. Use this function to register the name of the thread with register/2.

loaded_modules/1 and loaded_modules_with_opts/1

loaded_modules(Host) -> [Module]
loaded_modules_with_opts(Host) -> [{Module, Opts}]
Host = string()
Opts = [{Opt, Value}]

loaded_modules/1 returns the list of loaded modules. loaded_modules_with_opts/1 returns the list of loaded modules with their options.