ejabberd events and hooks

Introduction

ejabberd provides an event mechanism. Each module can subscribe to events and a hook in the module code is called when the event occurs.

Example

The module mod_offline.erl is an example of how the events/hooks mechanism can be used.

API

ejabberd_hooks:add(Hook, Host, Module, Function, Priority)
ejabberd_hooks:remove(Hook, Host, Module, Function, Priority)
* Hook = atom()
* Host = string()
* Module = atom()
* Function = atom()
* Priority = integer() 

The Hook parameter is the name of the event (see below). Host is the name of the virtual host related to the event. Module and Function describe the hook to be called when the event occurs. Priority is the hook rank, to determine in which order the hooks are run (when several hooks are defined for the same event), use it if you have dependencies between hooks.

List of events

The list of available events, and the type of corresponding hooks, is described below.

Events

adhoc_local_items(Acc, From, To, Lang) -> Adhoc
adhoc_sm_items(Acc, From, To, Lang) -> Adhoc
c2s_stream_features(Acc)
c2s_unauthenticated_iq(Acc, Server, IQ) -> Adhoc
disco_local_features(Acc, From, To, Node, Lang) -> Adhoc
disco_local_identity(Acc, From, To, Node, Lang) -> Adhoc
disco_local_items(Acc, From, To, Node, Lang) -> Adhoc
disco_sm_features(Acc, From, To, Node, Lang) -> Adhoc
disco_sm_identity(Acc, From, To, Node, Lang) -> Adhoc
disco_sm_items(Acc, From, To, Node, Lang) -> Adhoc
ejabberd_ctl_process(Args) -> CtlStatus
filter_packet({From, To, Packet}) -> {From, To, Packet}
local_send_to_resource_hook(From, To, Packet) -> ok
offline_message_hook(From, To, Packet) -> ok
privacy_check_packet(Acc, User, Server, PrivacyList, {From, To, Packet}, Dir) -> Auth
privacy_get_user_list(Acc, User, Server) -> PrivacyList
privacy_iq_get(Acc, From, To, IQ) -> {result, Packet} | {error, Error}
privacy_iq_set(Acc, From, To, IQ) -> {result, Packet} | {error, Error}
privacy_updated_list(Acc, OldPrivacyList, NewPrivacyList) -> PrivacyList
pubsub_publish_item(From, To, Node, ItemID, Payload) -> ok
remove_user(User, Server) -> ok
resend_offline_messages_hook(Acc, User, Server) -> [Route]
resend_subscription_requests_hook(Acc, User, Server) -> [Packet]
roster_get(Acc, {User, Server}) -> [RosterItem]
roster_get_jid_info(Acc, User, Server, JID) -> {Subscription, Groups}
roster_get_subscription_lists(Acc, User, Server) -> {[FromSubscription], [ToSubscription]}
roster_in_subscription(Acc, User, Server, JID, SubscriptionType, Reason) -> bool()
roster_out_subscription(Acc, User, Server, JID, SubscriptionType, Reason) -> bool()
roster_process_item(RosterItem, Server) -> RosterItem
set_presence_hook(User, Server, Resource, Priority) -> none
sm_register_connection_hook(SID, JID) -> ok
sm_remove_connection_hook(SID, JID) -> ok
unset_presence_hook(User, Server, Resource, Status) -> void()
user_available_hook(JID) -> ok
user_receive_packet(JID, From, To, Packet) -> ok
user_send_packet(From, To, Packet) -> ok 

Types

To = From = JID = ServerJID = #jid (see jlib)
Packet = Payload = {xmlelement, Name, Attrs, SubEl}
IQ = #iq (see jlib)
Error = ?STANZA_ERROR/3 (see jlib.h)
Lang = string()
Dir = in | out
Auth = allow | deny
PrivacyList = OldPrivacyList = NewPrivacyList = none | #userlist
CtlStatus = false | ?STATUS_SUCCESS | ?STATUS_ERROR | ?STATUS_USAGE | ?STATUS_BADRPC (see ejabberd_ctl.hrl”)
Adhoc = {result, I} | {error, Error} | empty
Arg = [string()]
Node = [string()]
ItemID = string()
Route = {route, From, To, Packet
RosterItem = #roster (see mod_roster.hrl)
Subscription = none | from | to | both | remove
SubscriptionType = subscribe | unsubscribe
Reason = string()
Groups = [string()]
SimpleJID = FromSubscription = ToSubscription = {User, Server, Resource}
User = string()
Server = string()
Resource = string()
Status = string()
SID = {Time, pid()}
Time = {MegaSecs, Secs, MicroSecs} (see erlang:now/0)
MegaSecs = Secs = MicroSecs = int()
Acc = same type as the return type of the function

Article - Talk ejabberd events and hooks

Introduction

Example

API

List of events

Events

Types