1package DJabberd::HookDocs;
2use strict;
3use vars qw(%hook);
4
5sub allow_hook {
6    my ($class, $ph) = @_;
7    $hook{$ph} = {};
8}
9
10# STUBS FOR NOW
11
12# TODO: make run_hook_chain() also validate (perhaps only in dev mode), the parameters
13# are of right count and type as documented
14
15# TODO: make run_hook_chain() also validate callback methods are documented
16
17$hook{'filter_incoming_client'} = {};
18$hook{'switch_incoming_client'} = {};
19$hook{'filter_incoming_server'} = {};
20$hook{'switch_incoming_server'} = {};
21
22
23$hook{'GetPassword'} = {
24    des => "Lookup a user's plaintext password",
25    args => [ "username" => '$username', "conn" => 'Connection', ],
26    callbacks => {
27        set => ['password'],
28    },
29};
30
31$hook{'CheckCleartext'} = {
32    des => "Check a user's plaintext password",
33    args => [ "username" => '$username', "conn" => 'Connection', 'password' => '$password', ],
34    callbacks => {
35        accept => [],
36        reject => [],
37    },
38};
39
40$hook{'CheckDigest'} = {
41    des => "Check the non-SASL-auth digest field to see if it matches digest of password+streamid",
42    args => [ "username" => '$username', "conn" => 'Connection', 'digest' => '$digest', ],
43    callbacks => {
44        accept => [],
45        reject => [],
46    },
47};
48
49$hook{'CheckJID'} = {
50    des => "Check if this knows about this JID",
51    args => [ "username" => '$username', "conn" => 'Connection', ],
52    callbacks => {
53        accept => [],
54        reject => [],
55    },
56};
57
58
59$hook{'pre_stanza_write'} = {
60    des => "Called before a stanza is written to a user.  Default action if all declined is to just deliver it.",
61};
62
63$hook{'c2s-iq'} = {};
64$hook{'deliver'} = {
65    args => ['Stanza'],
66};
67
68$hook{'RosterGet'} = {
69    args => ['JID'],
70    callbacks => {
71        set_roster => [ 'Roster' ],
72    },
73    des  => "Retrieve user JID's roster.",
74};
75
76$hook{'RosterRemoveItem'} = {
77    args => ['RosterItem'],
78    des  => "Remove an provided RosterItem from connection's roster.",
79};
80
81$hook{'RosterAddUpdateItem'} = {
82    args => ['RosterItem'],
83    callback => {
84        done => [ 'RosterItem' ],
85    },
86    des => "Called when client adds or modifies a roster item.  This doesn't effect the subscription state of the roster item.  In fact, the provided RosterItem object will always have a subscription state of 'none'.  If the roster storage plugin doesn't yet have this item in the list, it should be added with the provided state of 'none'.  However, if this is an update you should ignore the RosterItem's subscription value (which will be none, and potentially override what was previously set by other methods).  This hook must return back to the 'done' callback the resultant RosterItem, with the actual subscription value set.",
87};
88
89$hook{'RosterLoadItem'} = {
90    args => ['JID', 'JID'],
91    callback => {
92        error => [ 'reason' ],
93        set   => [ 'RosterItem' ],  # or undef if second JID not in first JID's roster
94    },
95    des  => "Called to load first JID's rosteritem of second given JID.",
96};
97
98$hook{'RosterSetItem'} = {
99    args => ['JID', 'RosterItem'],
100    callback => {
101        error => [ 'reason' ],
102        done  => [],
103    },
104    des  => "Called to set an item in a JID's roster.",
105};
106
107$hook{'PresenceCheck'} = {
108    args => ['JID', 'CODE'],
109    callback => {
110        decline => [],
111    },
112    des => "Called to request each hook chain item calls the given CODE with parameters (JID,DJabberd::Presence) for each full JID and last presence for that full JID that is based on the provided short JID (the first parameter).  Each hook chain item is just expected to call the CODE subref 0 or more times, then decline.",
113};
114
115$hook{'RegisterJID'} = {
116    args => [username => '$user', password => '$pass'],
117    callback => {
118        saved => {},
119        conflict => {},
120    },
121    des => "In-band registration, way for core to ask auth system to provision an account.",
122};
123
124$hook{'UnregisterJID'} = {
125    args => [username => '$user'],
126    callback => {
127        deleted => {},
128        notfound => {},
129    },
130    des => "In-band unregistration, way for core to ask auth system to unprovision an account.",
131};
132
133$hook{'RosterWipe'} = {
134    args => ['JID'],
135    callback => {
136        done => {},
137        error => {},
138    },
139    des => "Wipe a user's roster",
140};
141
142$hook{'AlterPresenceAvailable'} = {
143    args => ['Connection', 'Presence'],
144    callback => {
145        done => {},
146    },
147    des => "Place to alter outgoing presence available packets from users, in-place.  Just modify the provided second argument, warning will see directed ones",
148};
149
150$hook{'AlterPresenceUnavailable'} = {
151    args => ['Connection', 'Presence'],
152    callback => {
153        done => {},
154    },
155    des => "Place to alter outgoing presence unavailable packets from users, in-place.  Just modify the provided second argument, warning will see directed ones",
156};
157
158$hook{'OnInitialPresence'} = {
159    args => ['Connection'],
160    callback => {
161    },
162    des => "Called when a client first comes online and becomes present.",
163};
164
165$hook{'ConnectionClosing'} = {
166    args => ['Connection'],
167    callback => {
168        done => {},
169    },
170    des => "Gets called when a connection is in closing state, you can't do anything but let it fall through",
171};
172
173# HandleStanza hook is designed to allow plugins to support and respond to additional stanza types.
174# Recipients of the HandleStanza hook must execute thier callbacks synchonously (blocking),
175# or else we will fall though to the unsupported-stanza-type stream error.
176# This make makes sense, because handling the hook should be a very simple operation:
177# simply provide a class name that implements the processing of the stanza.
178# The actual processing will happen via call to 'process' (should be overriden in class provided).
179$hook{'HandleStanza'} = {
180    args => ['Node', 'Stanza'],
181    callback => {
182      handle => [ 'class' ]
183    },
184    des => "When recieving an unknown stanza, one handler must run 'handle' callback with the class to bless stanza to or result is stream error.",
185};
186
187# SendFeatures hook is designed to allow plugins to send additional items in the stream:features stanza to clients.
188# Recipients of the SendFeatures hook must execute thier callbacks synchonously (blocking),
189# or else we will fall though to sending only the default features.
190$hook{'SendFeatures'} = {
191  args => ['Connection'],
192  callback => {
193    stanza => [ 'xml_string' ]
194  },
195  des => "When features stanza is sent to the client right after stream start, adds extra xml to the contents of features.",
196};
197
198$hook{'GetSASLManager'} = {
199    des => "return a SASL Manager object for handling SASL negotiation",
200    args => [ "conn" => 'Connection' ],
201    callbacks => {
202        get => [],
203    },
204};
205
2061;
207