Mercurial > irccd
annotate extern/libircclient/include/libirc_events.h @ 189:bb70bb9e41eb
Irccd: use native Duktape API
| author | David Demelier <markand@malikania.fr> |
|---|---|
| date | Fri, 03 Jun 2016 13:28:10 +0200 |
| parents | 4777f7e18bf2 |
| children |
| rev | line source |
|---|---|
| 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 /*! | |
|
102
4777f7e18bf2
Irccd: several improvements in servers, #385
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
161 * The "ping" event is triggered when the client receives PING requests. |
|
4777f7e18bf2
Irccd: several improvements in servers, #385
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
162 */ |
|
4777f7e18bf2
Irccd: several improvements in servers, #385
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
163 irc_event_callback_t event_ping; |
|
4777f7e18bf2
Irccd: several improvements in servers, #385
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
164 |
|
4777f7e18bf2
Irccd: several improvements in servers, #385
David Demelier <markand@malikania.fr>
parents:
0
diff
changeset
|
165 /*! |
| 0 | 166 * The "nick" event is triggered when the client receives a NICK message, |
| 167 * meaning that someone (including you) on a channel with the client has | |
| 168 * changed their nickname. | |
| 169 * | |
| 170 * \param origin the person, who changes the nick. Note that it can be you! | |
| 171 * \param params[0] mandatory, contains the new nick. | |
| 172 */ | |
| 173 irc_event_callback_t event_nick; | |
| 174 | |
| 175 /*! | |
| 176 * The "quit" event is triggered upon receipt of a QUIT message, which | |
| 177 * means that someone on a channel with the client has disconnected. | |
| 178 * | |
| 179 * \param origin the person, who is disconnected | |
| 180 * \param params[0] optional, contains the reason message (user-specified). | |
| 181 */ | |
| 182 irc_event_callback_t event_quit; | |
| 183 | |
| 184 /*! | |
| 185 * The "join" event is triggered upon receipt of a JOIN message, which | |
| 186 * means that someone has entered a channel that the client is on. | |
| 187 * | |
| 188 * \param origin the person, who joins the channel. By comparing it with | |
| 189 * your own nickname, you can check whether your JOIN | |
| 190 * command succeed. | |
| 191 * \param params[0] mandatory, contains the channel name. | |
| 192 */ | |
| 193 irc_event_callback_t event_join; | |
| 194 | |
| 195 /*! | |
| 196 * The "part" event is triggered upon receipt of a PART message, which | |
| 197 * means that someone has left a channel that the client is on. | |
| 198 * | |
| 199 * \param origin the person, who leaves the channel. By comparing it with | |
| 200 * your own nickname, you can check whether your PART | |
| 201 * command succeed. | |
| 202 * \param params[0] mandatory, contains the channel name. | |
| 203 * \param params[1] optional, contains the reason message (user-defined). | |
| 204 */ | |
| 205 irc_event_callback_t event_part; | |
| 206 | |
| 207 /*! | |
| 208 * The "mode" event is triggered upon receipt of a channel MODE message, | |
| 209 * which means that someone on a channel with the client has changed the | |
| 210 * channel's parameters. | |
| 211 * | |
| 212 * \param origin the person, who changed the channel mode. | |
| 213 * \param params[0] mandatory, contains the channel name. | |
| 214 * \param params[1] mandatory, contains the changed channel mode, like | |
| 215 * '+t', '-i' and so on. | |
| 216 * \param params[2] optional, contains the mode argument (for example, a | |
| 217 * key for +k mode, or user who got the channel operator status for | |
| 218 * +o mode) | |
| 219 */ | |
| 220 irc_event_callback_t event_mode; | |
| 221 | |
| 222 /*! | |
| 223 * The "umode" event is triggered upon receipt of a user MODE message, | |
| 224 * which means that your user mode has been changed. | |
| 225 * | |
| 226 * \param origin the person, who changed the channel mode. | |
| 227 * \param params[0] mandatory, contains the user changed mode, like | |
| 228 * '+t', '-i' and so on. | |
| 229 */ | |
| 230 irc_event_callback_t event_umode; | |
| 231 | |
| 232 /*! | |
| 233 * The "topic" event is triggered upon receipt of a TOPIC message, which | |
| 234 * means that someone on a channel with the client has changed the | |
| 235 * channel's topic. | |
| 236 * | |
| 237 * \param origin the person, who changes the channel topic. | |
| 238 * \param params[0] mandatory, contains the channel name. | |
| 239 * \param params[1] optional, contains the new topic. | |
| 240 */ | |
| 241 irc_event_callback_t event_topic; | |
| 242 | |
| 243 /*! | |
| 244 * The "kick" event is triggered upon receipt of a KICK message, which | |
| 245 * means that someone on a channel with the client (or possibly the | |
| 246 * client itself!) has been forcibly ejected. | |
| 247 * | |
| 248 * \param origin the person, who kicked the poor. | |
| 249 * \param params[0] mandatory, contains the channel name. | |
| 250 * \param params[0] optional, contains the nick of kicked person. | |
| 251 * \param params[1] optional, contains the kick text | |
| 252 */ | |
| 253 irc_event_callback_t event_kick; | |
| 254 | |
| 255 /*! | |
| 256 * The "channel" event is triggered upon receipt of a PRIVMSG message | |
| 257 * to an entire channel, which means that someone on a channel with | |
| 258 * the client has said something aloud. Your own messages don't trigger | |
| 259 * PRIVMSG event. | |
| 260 * | |
| 261 * \param origin the person, who generates the message. | |
| 262 * \param params[0] mandatory, contains the channel name. | |
| 263 * \param params[1] optional, contains the message text | |
| 264 */ | |
| 265 irc_event_callback_t event_channel; | |
| 266 | |
| 267 /*! | |
| 268 * The "privmsg" event is triggered upon receipt of a PRIVMSG message | |
| 269 * which is addressed to one or more clients, which means that someone | |
| 270 * is sending the client a private message. | |
| 271 * | |
| 272 * \param origin the person, who generates the message. | |
| 273 * \param params[0] mandatory, contains your nick. | |
| 274 * \param params[1] optional, contains the message text | |
| 275 */ | |
| 276 irc_event_callback_t event_privmsg; | |
| 277 | |
| 278 /*! | |
| 279 * The "notice" event is triggered upon receipt of a NOTICE message | |
| 280 * which means that someone has sent the client a public or private | |
| 281 * notice. According to RFC 1459, the only difference between NOTICE | |
| 282 * and PRIVMSG is that you should NEVER automatically reply to NOTICE | |
| 283 * messages. Unfortunately, this rule is frequently violated by IRC | |
| 284 * servers itself - for example, NICKSERV messages require reply, and | |
| 285 * are NOTICEs. | |
| 286 * | |
| 287 * \param origin the person, who generates the message. | |
| 288 * \param params[0] mandatory, contains the target nick name. | |
| 289 * \param params[1] optional, contains the message text | |
| 290 */ | |
| 291 irc_event_callback_t event_notice; | |
| 292 | |
| 293 /*! | |
| 294 * The "channel_notice" event is triggered upon receipt of a NOTICE | |
| 295 * message which means that someone has sent the client a public | |
| 296 * notice. According to RFC 1459, the only difference between NOTICE | |
| 297 * and PRIVMSG is that you should NEVER automatically reply to NOTICE | |
| 298 * messages. Unfortunately, this rule is frequently violated by IRC | |
| 299 * servers itself - for example, NICKSERV messages require reply, and | |
| 300 * are NOTICEs. | |
| 301 * | |
| 302 * \param origin the person, who generates the message. | |
| 303 * \param params[0] mandatory, contains the channel name. | |
| 304 * \param params[1] optional, contains the message text | |
| 305 */ | |
| 306 irc_event_callback_t event_channel_notice; | |
| 307 | |
| 308 /*! | |
| 309 * The "invite" event is triggered upon receipt of an INVITE message, | |
| 310 * which means that someone is permitting the client's entry into a +i | |
| 311 * channel. | |
| 312 * | |
| 313 * \param origin the person, who INVITEs you. | |
| 314 * \param params[0] mandatory, contains your nick. | |
| 315 * \param params[1] mandatory, contains the channel name you're invited into. | |
| 316 * | |
| 317 * \sa irc_cmd_invite irc_cmd_chanmode_invite | |
| 318 */ | |
| 319 irc_event_callback_t event_invite; | |
| 320 | |
| 321 /*! | |
| 322 * The "ctcp" event is triggered when the client receives the CTCP | |
| 323 * request. By default, the built-in CTCP request handler is used. The | |
| 324 * build-in handler automatically replies on most CTCP messages, so you | |
| 325 * will rarely need to override it. | |
| 326 * | |
| 327 * \param origin the person, who generates the message. | |
| 328 * \param params[0] mandatory, the complete CTCP message, including its | |
| 329 * arguments. | |
| 330 * | |
| 331 * Mirc generates PING, FINGER, VERSION, TIME and ACTION messages, | |
| 332 * check the source code of \c libirc_event_ctcp_internal function to | |
| 333 * see how to write your own CTCP request handler. Also you may find | |
| 334 * useful this question in FAQ: \ref faq4 | |
| 335 */ | |
| 336 irc_event_callback_t event_ctcp_req; | |
| 337 | |
| 338 /*! | |
| 339 * The "ctcp" event is triggered when the client receives the CTCP reply. | |
| 340 * | |
| 341 * \param origin the person, who generates the message. | |
| 342 * \param params[0] mandatory, the CTCP message itself with its arguments. | |
| 343 */ | |
| 344 irc_event_callback_t event_ctcp_rep; | |
| 345 | |
| 346 /*! | |
| 347 * The "action" event is triggered when the client receives the CTCP | |
| 348 * ACTION message. These messages usually looks like:\n | |
| 349 * \code | |
| 350 * [23:32:55] * Tim gonna sleep. | |
| 351 * \endcode | |
| 352 * | |
| 353 * \param origin the person, who generates the message. | |
| 354 * \param params[0] mandatory, the ACTION message. | |
| 355 */ | |
| 356 irc_event_callback_t event_ctcp_action; | |
| 357 | |
| 358 /*! | |
| 359 * The "unknown" event is triggered upon receipt of any number of | |
| 360 * unclassifiable miscellaneous messages, which aren't handled by the | |
| 361 * library. | |
| 362 */ | |
| 363 irc_event_callback_t event_unknown; | |
| 364 | |
| 365 /*! | |
| 366 * The "numeric" event is triggered upon receipt of any numeric response | |
| 367 * from the server. There is a lot of such responses, see the full list | |
| 368 * here: \ref rfcnumbers. | |
| 369 * | |
| 370 * See the params in ::irc_eventcode_callback_t specification. | |
| 371 */ | |
| 372 irc_eventcode_callback_t event_numeric; | |
| 373 | |
| 374 /*! | |
| 375 * The "dcc chat" event is triggered when someone requests a DCC CHAT from | |
| 376 * you. | |
| 377 * | |
| 378 * See the params in ::irc_event_dcc_chat_t specification. | |
| 379 */ | |
| 380 irc_event_dcc_chat_t event_dcc_chat_req; | |
| 381 | |
| 382 /*! | |
| 383 * The "dcc chat" event is triggered when someone wants to send a file | |
| 384 * to you via DCC SEND request. | |
| 385 * | |
| 386 * See the params in ::irc_event_dcc_send_t specification. | |
| 387 */ | |
| 388 irc_event_dcc_send_t event_dcc_send_req; | |
| 389 | |
| 390 | |
| 391 } irc_callbacks_t; | |
| 392 | |
| 393 | |
| 394 #endif /* INCLUDE_IRC_EVENTS_H */ |