Mercurial > irccd
comparison extern/libircclient/include/libirc_events.h @ 0:1158cffe5a5e
Initial import
author | David Demelier <markand@malikania.fr> |
---|---|
date | Mon, 08 Feb 2016 16:43:14 +0100 |
parents | |
children | 4777f7e18bf2 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:1158cffe5a5e |
---|---|
1 /* | |
2 * Copyright (C) 2004-2012 George Yunaev gyunaev@ulduzsoft.com | |
3 * | |
4 * This library is free software; you can redistribute it and/or modify it | |
5 * under the terms of the GNU Lesser General Public License as published by | |
6 * the Free Software Foundation; either version 3 of the License, or (at your | |
7 * option) any later version. | |
8 * | |
9 * This library is distributed in the hope that it will be useful, but WITHOUT | |
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public | |
12 * License for more details. | |
13 */ | |
14 | |
15 | |
16 #ifndef INCLUDE_IRC_EVENTS_H | |
17 #define INCLUDE_IRC_EVENTS_H | |
18 | |
19 | |
20 #ifndef IN_INCLUDE_LIBIRC_H | |
21 #error This file should not be included directly, include just libircclient.h | |
22 #endif | |
23 | |
24 | |
25 | |
26 /*! | |
27 * \fn typedef void (*irc_event_callback_t) (irc_session_t * session, const char * event, const char * origin, const char ** params, unsigned int count) | |
28 * \brief A most common event callback | |
29 * | |
30 * \param session the session, which generates an event | |
31 * \param event the text name of the event. Useful in case you use a single | |
32 * event handler for several events simultaneously. | |
33 * \param origin the originator of the event. See the note below. | |
34 * \param params a list of event params. Depending on the event nature, it | |
35 * could have zero or more params. The actual number of params | |
36 * is specified in count. None of the params can be NULL, but | |
37 * 'params' pointer itself could be NULL for some events. | |
38 * \param count the total number of params supplied. | |
39 * | |
40 * Every event generates a callback. This callback is generated by most events. | |
41 * Depending on the event nature, it can provide zero or more params. For each | |
42 * event, the number of provided params is fixed, and their meaning is | |
43 * described. | |
44 * | |
45 * Every event has origin, though the \a origin variable may be NULL, which | |
46 * means that event origin is unknown. The origin usually looks like | |
47 * nick!host\@ircserver, i.e. like tim!home\@irc.krasnogorsk.ru. Such origins | |
48 * can not be used in IRC commands, and need to be stripped (i.e. host and | |
49 * server part should be cut off) before using. This can be done either | |
50 * explicitly, by calling irc_target_get_nick(), or implicitly for all the | |
51 * events - by setting the #LIBIRC_OPTION_STRIPNICKS option with irc_option_set(). | |
52 * | |
53 * \ingroup events | |
54 */ | |
55 typedef void (*irc_event_callback_t) (irc_session_t * session, const char * event, const char * origin, const char ** params, unsigned int count); | |
56 | |
57 | |
58 /*! | |
59 * \fn typedef void (*irc_eventcode_callback_t) (irc_session_t * session, unsigned int event, const char * origin, const char ** params, unsigned int count) | |
60 * \brief A numeric event callback | |
61 * | |
62 * \param session the session, which generates an event | |
63 * \param event the numeric code of the event. Useful in case you use a | |
64 * single event handler for several events simultaneously. | |
65 * \param origin the originator of the event. See the note below. | |
66 * \param params a list of event params. Depending on the event nature, it | |
67 * could have zero or more params. The actual number of params | |
68 * is specified in count. None of the params can be NULL, but | |
69 * 'params' pointer itself could be NULL for some events. | |
70 * \param count the total number of params supplied. | |
71 * | |
72 * Most times in reply to your actions the IRC server generates numeric | |
73 * callbacks. Most of them are error codes, and some of them mark list start | |
74 * and list stop markers. Every code has its own set of params; for details | |
75 * you can either experiment, or read RFC 1459. | |
76 * | |
77 * Every event has origin, though the \a origin variable may be NULL, which | |
78 * means that event origin is unknown. The origin usually looks like | |
79 * nick!host\@ircserver, i.e. like tim!home\@irc.krasnogorsk.ru. Such origins | |
80 * can not be used in IRC commands, and need to be stripped (i.e. host and | |
81 * server part should be cut off) before using. This can be done either | |
82 * explicitly, by calling irc_target_get_nick(), or implicitly for all the | |
83 * events - by setting the #LIBIRC_OPTION_STRIPNICKS option with irc_option_set(). | |
84 * | |
85 * \ingroup events | |
86 */ | |
87 typedef void (*irc_eventcode_callback_t) (irc_session_t * session, unsigned int event, const char * origin, const char ** params, unsigned int count); | |
88 | |
89 | |
90 /*! | |
91 * \fn typedef void (*irc_event_dcc_chat_t) (irc_session_t * session, const char * nick, const char * addr, irc_dcc_t dccid) | |
92 * \brief A remote DCC CHAT request callback | |
93 * | |
94 * \param session the session, which generates an event | |
95 * \param nick the person who requested DCC CHAT with you. | |
96 * \param addr the person's IP address in decimal-dot notation. | |
97 * \param dccid an id associated with this request. Use it in calls to | |
98 * irc_dcc_accept() or irc_dcc_decline(). | |
99 * | |
100 * This callback is called when someone requests DCC CHAT with you. In respond | |
101 * you should call either irc_dcc_accept() to accept chat request, or | |
102 * irc_dcc_decline() to decline chat request. | |
103 * | |
104 * \sa irc_dcc_accept or irc_dcc_decline | |
105 * \ingroup events | |
106 */ | |
107 typedef void (*irc_event_dcc_chat_t) (irc_session_t * session, const char * nick, const char * addr, irc_dcc_t dccid); | |
108 | |
109 | |
110 /*! | |
111 * \fn typedef void (*irc_event_dcc_send_t) (irc_session_t * session, const char * nick, const char * addr, const char * filename, unsigned long size, irc_dcc_t dccid) | |
112 * \brief A remote DCC CHAT request callback | |
113 * | |
114 * \param session the session, which generates an event | |
115 * \param nick the person who requested DCC CHAT with you. | |
116 * \param addr the person's IP address in decimal-dot notation. | |
117 * \param filename the sent filename. | |
118 * \param size the filename size. | |
119 * \param dccid an id associated with this request. Use it in calls to | |
120 * irc_dcc_accept() or irc_dcc_decline(). | |
121 * | |
122 * This callback is called when someone wants to send a file to you using | |
123 * DCC SEND. As with chat, in respond you should call either irc_dcc_accept() | |
124 * to accept this request and receive the file, or irc_dcc_decline() to | |
125 * decline this request. | |
126 * | |
127 * \sa irc_dcc_accept or irc_dcc_decline | |
128 * \ingroup events | |
129 */ | |
130 typedef void (*irc_event_dcc_send_t) (irc_session_t * session, const char * nick, const char * addr, const char * filename, unsigned long size, irc_dcc_t dccid); | |
131 | |
132 | |
133 /*! \brief Event callbacks structure. | |
134 * | |
135 * All the communication with the IRC network is based on events. Generally | |
136 * speaking, event is anything generated by someone else in the network, | |
137 * or by the IRC server itself. "Someone sends you a message", "Someone | |
138 * has joined the channel", "Someone has quits IRC" - all these messages | |
139 * are events. | |
140 * | |
141 * Every event has its own event handler, which is called when the | |
142 * appropriate event is received. You don't have to define all the event | |
143 * handlers; define only the handlers for the events you need to intercept. | |
144 * | |
145 * Most event callbacks are the types of ::irc_event_callback_t. There are | |
146 * also events, which generate ::irc_eventcode_callback_t, | |
147 * ::irc_event_dcc_chat_t and ::irc_event_dcc_send_t callbacks. | |
148 * | |
149 * \ingroup events | |
150 */ | |
151 typedef struct | |
152 { | |
153 /*! | |
154 * The "on_connect" event is triggered when the client successfully | |
155 * connects to the server, and could send commands to the server. | |
156 * No extra params supplied; \a params is 0. | |
157 */ | |
158 irc_event_callback_t event_connect; | |
159 | |
160 /*! | |
161 * The "nick" event is triggered when the client receives a NICK message, | |
162 * meaning that someone (including you) on a channel with the client has | |
163 * changed their nickname. | |
164 * | |
165 * \param origin the person, who changes the nick. Note that it can be you! | |
166 * \param params[0] mandatory, contains the new nick. | |
167 */ | |
168 irc_event_callback_t event_nick; | |
169 | |
170 /*! | |
171 * The "quit" event is triggered upon receipt of a QUIT message, which | |
172 * means that someone on a channel with the client has disconnected. | |
173 * | |
174 * \param origin the person, who is disconnected | |
175 * \param params[0] optional, contains the reason message (user-specified). | |
176 */ | |
177 irc_event_callback_t event_quit; | |
178 | |
179 /*! | |
180 * The "join" event is triggered upon receipt of a JOIN message, which | |
181 * means that someone has entered a channel that the client is on. | |
182 * | |
183 * \param origin the person, who joins the channel. By comparing it with | |
184 * your own nickname, you can check whether your JOIN | |
185 * command succeed. | |
186 * \param params[0] mandatory, contains the channel name. | |
187 */ | |
188 irc_event_callback_t event_join; | |
189 | |
190 /*! | |
191 * The "part" event is triggered upon receipt of a PART message, which | |
192 * means that someone has left a channel that the client is on. | |
193 * | |
194 * \param origin the person, who leaves the channel. By comparing it with | |
195 * your own nickname, you can check whether your PART | |
196 * command succeed. | |
197 * \param params[0] mandatory, contains the channel name. | |
198 * \param params[1] optional, contains the reason message (user-defined). | |
199 */ | |
200 irc_event_callback_t event_part; | |
201 | |
202 /*! | |
203 * The "mode" event is triggered upon receipt of a channel MODE message, | |
204 * which means that someone on a channel with the client has changed the | |
205 * channel's parameters. | |
206 * | |
207 * \param origin the person, who changed the channel mode. | |
208 * \param params[0] mandatory, contains the channel name. | |
209 * \param params[1] mandatory, contains the changed channel mode, like | |
210 * '+t', '-i' and so on. | |
211 * \param params[2] optional, contains the mode argument (for example, a | |
212 * key for +k mode, or user who got the channel operator status for | |
213 * +o mode) | |
214 */ | |
215 irc_event_callback_t event_mode; | |
216 | |
217 /*! | |
218 * The "umode" event is triggered upon receipt of a user MODE message, | |
219 * which means that your user mode has been changed. | |
220 * | |
221 * \param origin the person, who changed the channel mode. | |
222 * \param params[0] mandatory, contains the user changed mode, like | |
223 * '+t', '-i' and so on. | |
224 */ | |
225 irc_event_callback_t event_umode; | |
226 | |
227 /*! | |
228 * The "topic" event is triggered upon receipt of a TOPIC message, which | |
229 * means that someone on a channel with the client has changed the | |
230 * channel's topic. | |
231 * | |
232 * \param origin the person, who changes the channel topic. | |
233 * \param params[0] mandatory, contains the channel name. | |
234 * \param params[1] optional, contains the new topic. | |
235 */ | |
236 irc_event_callback_t event_topic; | |
237 | |
238 /*! | |
239 * The "kick" event is triggered upon receipt of a KICK message, which | |
240 * means that someone on a channel with the client (or possibly the | |
241 * client itself!) has been forcibly ejected. | |
242 * | |
243 * \param origin the person, who kicked the poor. | |
244 * \param params[0] mandatory, contains the channel name. | |
245 * \param params[0] optional, contains the nick of kicked person. | |
246 * \param params[1] optional, contains the kick text | |
247 */ | |
248 irc_event_callback_t event_kick; | |
249 | |
250 /*! | |
251 * The "channel" event is triggered upon receipt of a PRIVMSG message | |
252 * to an entire channel, which means that someone on a channel with | |
253 * the client has said something aloud. Your own messages don't trigger | |
254 * PRIVMSG event. | |
255 * | |
256 * \param origin the person, who generates the message. | |
257 * \param params[0] mandatory, contains the channel name. | |
258 * \param params[1] optional, contains the message text | |
259 */ | |
260 irc_event_callback_t event_channel; | |
261 | |
262 /*! | |
263 * The "privmsg" event is triggered upon receipt of a PRIVMSG message | |
264 * which is addressed to one or more clients, which means that someone | |
265 * is sending the client a private message. | |
266 * | |
267 * \param origin the person, who generates the message. | |
268 * \param params[0] mandatory, contains your nick. | |
269 * \param params[1] optional, contains the message text | |
270 */ | |
271 irc_event_callback_t event_privmsg; | |
272 | |
273 /*! | |
274 * The "notice" event is triggered upon receipt of a NOTICE message | |
275 * which means that someone has sent the client a public or private | |
276 * notice. According to RFC 1459, the only difference between NOTICE | |
277 * and PRIVMSG is that you should NEVER automatically reply to NOTICE | |
278 * messages. Unfortunately, this rule is frequently violated by IRC | |
279 * servers itself - for example, NICKSERV messages require reply, and | |
280 * are NOTICEs. | |
281 * | |
282 * \param origin the person, who generates the message. | |
283 * \param params[0] mandatory, contains the target nick name. | |
284 * \param params[1] optional, contains the message text | |
285 */ | |
286 irc_event_callback_t event_notice; | |
287 | |
288 /*! | |
289 * The "channel_notice" event is triggered upon receipt of a NOTICE | |
290 * message which means that someone has sent the client a public | |
291 * notice. According to RFC 1459, the only difference between NOTICE | |
292 * and PRIVMSG is that you should NEVER automatically reply to NOTICE | |
293 * messages. Unfortunately, this rule is frequently violated by IRC | |
294 * servers itself - for example, NICKSERV messages require reply, and | |
295 * are NOTICEs. | |
296 * | |
297 * \param origin the person, who generates the message. | |
298 * \param params[0] mandatory, contains the channel name. | |
299 * \param params[1] optional, contains the message text | |
300 */ | |
301 irc_event_callback_t event_channel_notice; | |
302 | |
303 /*! | |
304 * The "invite" event is triggered upon receipt of an INVITE message, | |
305 * which means that someone is permitting the client's entry into a +i | |
306 * channel. | |
307 * | |
308 * \param origin the person, who INVITEs you. | |
309 * \param params[0] mandatory, contains your nick. | |
310 * \param params[1] mandatory, contains the channel name you're invited into. | |
311 * | |
312 * \sa irc_cmd_invite irc_cmd_chanmode_invite | |
313 */ | |
314 irc_event_callback_t event_invite; | |
315 | |
316 /*! | |
317 * The "ctcp" event is triggered when the client receives the CTCP | |
318 * request. By default, the built-in CTCP request handler is used. The | |
319 * build-in handler automatically replies on most CTCP messages, so you | |
320 * will rarely need to override it. | |
321 * | |
322 * \param origin the person, who generates the message. | |
323 * \param params[0] mandatory, the complete CTCP message, including its | |
324 * arguments. | |
325 * | |
326 * Mirc generates PING, FINGER, VERSION, TIME and ACTION messages, | |
327 * check the source code of \c libirc_event_ctcp_internal function to | |
328 * see how to write your own CTCP request handler. Also you may find | |
329 * useful this question in FAQ: \ref faq4 | |
330 */ | |
331 irc_event_callback_t event_ctcp_req; | |
332 | |
333 /*! | |
334 * The "ctcp" event is triggered when the client receives the CTCP reply. | |
335 * | |
336 * \param origin the person, who generates the message. | |
337 * \param params[0] mandatory, the CTCP message itself with its arguments. | |
338 */ | |
339 irc_event_callback_t event_ctcp_rep; | |
340 | |
341 /*! | |
342 * The "action" event is triggered when the client receives the CTCP | |
343 * ACTION message. These messages usually looks like:\n | |
344 * \code | |
345 * [23:32:55] * Tim gonna sleep. | |
346 * \endcode | |
347 * | |
348 * \param origin the person, who generates the message. | |
349 * \param params[0] mandatory, the ACTION message. | |
350 */ | |
351 irc_event_callback_t event_ctcp_action; | |
352 | |
353 /*! | |
354 * The "unknown" event is triggered upon receipt of any number of | |
355 * unclassifiable miscellaneous messages, which aren't handled by the | |
356 * library. | |
357 */ | |
358 irc_event_callback_t event_unknown; | |
359 | |
360 /*! | |
361 * The "numeric" event is triggered upon receipt of any numeric response | |
362 * from the server. There is a lot of such responses, see the full list | |
363 * here: \ref rfcnumbers. | |
364 * | |
365 * See the params in ::irc_eventcode_callback_t specification. | |
366 */ | |
367 irc_eventcode_callback_t event_numeric; | |
368 | |
369 /*! | |
370 * The "dcc chat" event is triggered when someone requests a DCC CHAT from | |
371 * you. | |
372 * | |
373 * See the params in ::irc_event_dcc_chat_t specification. | |
374 */ | |
375 irc_event_dcc_chat_t event_dcc_chat_req; | |
376 | |
377 /*! | |
378 * The "dcc chat" event is triggered when someone wants to send a file | |
379 * to you via DCC SEND request. | |
380 * | |
381 * See the params in ::irc_event_dcc_send_t specification. | |
382 */ | |
383 irc_event_dcc_send_t event_dcc_send_req; | |
384 | |
385 | |
386 } irc_callbacks_t; | |
387 | |
388 | |
389 #endif /* INCLUDE_IRC_EVENTS_H */ |