|
0
|
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 */ |
