Mercurial > irccd
diff 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 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/extern/libircclient/include/libirc_events.h Mon Feb 08 16:43:14 2016 +0100 @@ -0,0 +1,389 @@ +/* + * Copyright (C) 2004-2012 George Yunaev gyunaev@ulduzsoft.com + * + * This library is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as published by + * the Free Software Foundation; either version 3 of the License, or (at your + * option) any later version. + * + * This library is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public + * License for more details. + */ + + +#ifndef INCLUDE_IRC_EVENTS_H +#define INCLUDE_IRC_EVENTS_H + + +#ifndef IN_INCLUDE_LIBIRC_H + #error This file should not be included directly, include just libircclient.h +#endif + + + +/*! + * \fn typedef void (*irc_event_callback_t) (irc_session_t * session, const char * event, const char * origin, const char ** params, unsigned int count) + * \brief A most common event callback + * + * \param session the session, which generates an event + * \param event the text name of the event. Useful in case you use a single + * event handler for several events simultaneously. + * \param origin the originator of the event. See the note below. + * \param params a list of event params. Depending on the event nature, it + * could have zero or more params. The actual number of params + * is specified in count. None of the params can be NULL, but + * 'params' pointer itself could be NULL for some events. + * \param count the total number of params supplied. + * + * Every event generates a callback. This callback is generated by most events. + * Depending on the event nature, it can provide zero or more params. For each + * event, the number of provided params is fixed, and their meaning is + * described. + * + * Every event has origin, though the \a origin variable may be NULL, which + * means that event origin is unknown. The origin usually looks like + * nick!host\@ircserver, i.e. like tim!home\@irc.krasnogorsk.ru. Such origins + * can not be used in IRC commands, and need to be stripped (i.e. host and + * server part should be cut off) before using. This can be done either + * explicitly, by calling irc_target_get_nick(), or implicitly for all the + * events - by setting the #LIBIRC_OPTION_STRIPNICKS option with irc_option_set(). + * + * \ingroup events + */ +typedef void (*irc_event_callback_t) (irc_session_t * session, const char * event, const char * origin, const char ** params, unsigned int count); + + +/*! + * \fn typedef void (*irc_eventcode_callback_t) (irc_session_t * session, unsigned int event, const char * origin, const char ** params, unsigned int count) + * \brief A numeric event callback + * + * \param session the session, which generates an event + * \param event the numeric code of the event. Useful in case you use a + * single event handler for several events simultaneously. + * \param origin the originator of the event. See the note below. + * \param params a list of event params. Depending on the event nature, it + * could have zero or more params. The actual number of params + * is specified in count. None of the params can be NULL, but + * 'params' pointer itself could be NULL for some events. + * \param count the total number of params supplied. + * + * Most times in reply to your actions the IRC server generates numeric + * callbacks. Most of them are error codes, and some of them mark list start + * and list stop markers. Every code has its own set of params; for details + * you can either experiment, or read RFC 1459. + * + * Every event has origin, though the \a origin variable may be NULL, which + * means that event origin is unknown. The origin usually looks like + * nick!host\@ircserver, i.e. like tim!home\@irc.krasnogorsk.ru. Such origins + * can not be used in IRC commands, and need to be stripped (i.e. host and + * server part should be cut off) before using. This can be done either + * explicitly, by calling irc_target_get_nick(), or implicitly for all the + * events - by setting the #LIBIRC_OPTION_STRIPNICKS option with irc_option_set(). + * + * \ingroup events + */ +typedef void (*irc_eventcode_callback_t) (irc_session_t * session, unsigned int event, const char * origin, const char ** params, unsigned int count); + + +/*! + * \fn typedef void (*irc_event_dcc_chat_t) (irc_session_t * session, const char * nick, const char * addr, irc_dcc_t dccid) + * \brief A remote DCC CHAT request callback + * + * \param session the session, which generates an event + * \param nick the person who requested DCC CHAT with you. + * \param addr the person's IP address in decimal-dot notation. + * \param dccid an id associated with this request. Use it in calls to + * irc_dcc_accept() or irc_dcc_decline(). + * + * This callback is called when someone requests DCC CHAT with you. In respond + * you should call either irc_dcc_accept() to accept chat request, or + * irc_dcc_decline() to decline chat request. + * + * \sa irc_dcc_accept or irc_dcc_decline + * \ingroup events + */ +typedef void (*irc_event_dcc_chat_t) (irc_session_t * session, const char * nick, const char * addr, irc_dcc_t dccid); + + +/*! + * \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) + * \brief A remote DCC CHAT request callback + * + * \param session the session, which generates an event + * \param nick the person who requested DCC CHAT with you. + * \param addr the person's IP address in decimal-dot notation. + * \param filename the sent filename. + * \param size the filename size. + * \param dccid an id associated with this request. Use it in calls to + * irc_dcc_accept() or irc_dcc_decline(). + * + * This callback is called when someone wants to send a file to you using + * DCC SEND. As with chat, in respond you should call either irc_dcc_accept() + * to accept this request and receive the file, or irc_dcc_decline() to + * decline this request. + * + * \sa irc_dcc_accept or irc_dcc_decline + * \ingroup events + */ +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); + + +/*! \brief Event callbacks structure. + * + * All the communication with the IRC network is based on events. Generally + * speaking, event is anything generated by someone else in the network, + * or by the IRC server itself. "Someone sends you a message", "Someone + * has joined the channel", "Someone has quits IRC" - all these messages + * are events. + * + * Every event has its own event handler, which is called when the + * appropriate event is received. You don't have to define all the event + * handlers; define only the handlers for the events you need to intercept. + * + * Most event callbacks are the types of ::irc_event_callback_t. There are + * also events, which generate ::irc_eventcode_callback_t, + * ::irc_event_dcc_chat_t and ::irc_event_dcc_send_t callbacks. + * + * \ingroup events + */ +typedef struct +{ + /*! + * The "on_connect" event is triggered when the client successfully + * connects to the server, and could send commands to the server. + * No extra params supplied; \a params is 0. + */ + irc_event_callback_t event_connect; + + /*! + * The "nick" event is triggered when the client receives a NICK message, + * meaning that someone (including you) on a channel with the client has + * changed their nickname. + * + * \param origin the person, who changes the nick. Note that it can be you! + * \param params[0] mandatory, contains the new nick. + */ + irc_event_callback_t event_nick; + + /*! + * The "quit" event is triggered upon receipt of a QUIT message, which + * means that someone on a channel with the client has disconnected. + * + * \param origin the person, who is disconnected + * \param params[0] optional, contains the reason message (user-specified). + */ + irc_event_callback_t event_quit; + + /*! + * The "join" event is triggered upon receipt of a JOIN message, which + * means that someone has entered a channel that the client is on. + * + * \param origin the person, who joins the channel. By comparing it with + * your own nickname, you can check whether your JOIN + * command succeed. + * \param params[0] mandatory, contains the channel name. + */ + irc_event_callback_t event_join; + + /*! + * The "part" event is triggered upon receipt of a PART message, which + * means that someone has left a channel that the client is on. + * + * \param origin the person, who leaves the channel. By comparing it with + * your own nickname, you can check whether your PART + * command succeed. + * \param params[0] mandatory, contains the channel name. + * \param params[1] optional, contains the reason message (user-defined). + */ + irc_event_callback_t event_part; + + /*! + * The "mode" event is triggered upon receipt of a channel MODE message, + * which means that someone on a channel with the client has changed the + * channel's parameters. + * + * \param origin the person, who changed the channel mode. + * \param params[0] mandatory, contains the channel name. + * \param params[1] mandatory, contains the changed channel mode, like + * '+t', '-i' and so on. + * \param params[2] optional, contains the mode argument (for example, a + * key for +k mode, or user who got the channel operator status for + * +o mode) + */ + irc_event_callback_t event_mode; + + /*! + * The "umode" event is triggered upon receipt of a user MODE message, + * which means that your user mode has been changed. + * + * \param origin the person, who changed the channel mode. + * \param params[0] mandatory, contains the user changed mode, like + * '+t', '-i' and so on. + */ + irc_event_callback_t event_umode; + + /*! + * The "topic" event is triggered upon receipt of a TOPIC message, which + * means that someone on a channel with the client has changed the + * channel's topic. + * + * \param origin the person, who changes the channel topic. + * \param params[0] mandatory, contains the channel name. + * \param params[1] optional, contains the new topic. + */ + irc_event_callback_t event_topic; + + /*! + * The "kick" event is triggered upon receipt of a KICK message, which + * means that someone on a channel with the client (or possibly the + * client itself!) has been forcibly ejected. + * + * \param origin the person, who kicked the poor. + * \param params[0] mandatory, contains the channel name. + * \param params[0] optional, contains the nick of kicked person. + * \param params[1] optional, contains the kick text + */ + irc_event_callback_t event_kick; + + /*! + * The "channel" event is triggered upon receipt of a PRIVMSG message + * to an entire channel, which means that someone on a channel with + * the client has said something aloud. Your own messages don't trigger + * PRIVMSG event. + * + * \param origin the person, who generates the message. + * \param params[0] mandatory, contains the channel name. + * \param params[1] optional, contains the message text + */ + irc_event_callback_t event_channel; + + /*! + * The "privmsg" event is triggered upon receipt of a PRIVMSG message + * which is addressed to one or more clients, which means that someone + * is sending the client a private message. + * + * \param origin the person, who generates the message. + * \param params[0] mandatory, contains your nick. + * \param params[1] optional, contains the message text + */ + irc_event_callback_t event_privmsg; + + /*! + * The "notice" event is triggered upon receipt of a NOTICE message + * which means that someone has sent the client a public or private + * notice. According to RFC 1459, the only difference between NOTICE + * and PRIVMSG is that you should NEVER automatically reply to NOTICE + * messages. Unfortunately, this rule is frequently violated by IRC + * servers itself - for example, NICKSERV messages require reply, and + * are NOTICEs. + * + * \param origin the person, who generates the message. + * \param params[0] mandatory, contains the target nick name. + * \param params[1] optional, contains the message text + */ + irc_event_callback_t event_notice; + + /*! + * The "channel_notice" event is triggered upon receipt of a NOTICE + * message which means that someone has sent the client a public + * notice. According to RFC 1459, the only difference between NOTICE + * and PRIVMSG is that you should NEVER automatically reply to NOTICE + * messages. Unfortunately, this rule is frequently violated by IRC + * servers itself - for example, NICKSERV messages require reply, and + * are NOTICEs. + * + * \param origin the person, who generates the message. + * \param params[0] mandatory, contains the channel name. + * \param params[1] optional, contains the message text + */ + irc_event_callback_t event_channel_notice; + + /*! + * The "invite" event is triggered upon receipt of an INVITE message, + * which means that someone is permitting the client's entry into a +i + * channel. + * + * \param origin the person, who INVITEs you. + * \param params[0] mandatory, contains your nick. + * \param params[1] mandatory, contains the channel name you're invited into. + * + * \sa irc_cmd_invite irc_cmd_chanmode_invite + */ + irc_event_callback_t event_invite; + + /*! + * The "ctcp" event is triggered when the client receives the CTCP + * request. By default, the built-in CTCP request handler is used. The + * build-in handler automatically replies on most CTCP messages, so you + * will rarely need to override it. + * + * \param origin the person, who generates the message. + * \param params[0] mandatory, the complete CTCP message, including its + * arguments. + * + * Mirc generates PING, FINGER, VERSION, TIME and ACTION messages, + * check the source code of \c libirc_event_ctcp_internal function to + * see how to write your own CTCP request handler. Also you may find + * useful this question in FAQ: \ref faq4 + */ + irc_event_callback_t event_ctcp_req; + + /*! + * The "ctcp" event is triggered when the client receives the CTCP reply. + * + * \param origin the person, who generates the message. + * \param params[0] mandatory, the CTCP message itself with its arguments. + */ + irc_event_callback_t event_ctcp_rep; + + /*! + * The "action" event is triggered when the client receives the CTCP + * ACTION message. These messages usually looks like:\n + * \code + * [23:32:55] * Tim gonna sleep. + * \endcode + * + * \param origin the person, who generates the message. + * \param params[0] mandatory, the ACTION message. + */ + irc_event_callback_t event_ctcp_action; + + /*! + * The "unknown" event is triggered upon receipt of any number of + * unclassifiable miscellaneous messages, which aren't handled by the + * library. + */ + irc_event_callback_t event_unknown; + + /*! + * The "numeric" event is triggered upon receipt of any numeric response + * from the server. There is a lot of such responses, see the full list + * here: \ref rfcnumbers. + * + * See the params in ::irc_eventcode_callback_t specification. + */ + irc_eventcode_callback_t event_numeric; + + /*! + * The "dcc chat" event is triggered when someone requests a DCC CHAT from + * you. + * + * See the params in ::irc_event_dcc_chat_t specification. + */ + irc_event_dcc_chat_t event_dcc_chat_req; + + /*! + * The "dcc chat" event is triggered when someone wants to send a file + * to you via DCC SEND request. + * + * See the params in ::irc_event_dcc_send_t specification. + */ + irc_event_dcc_send_t event_dcc_send_req; + + +} irc_callbacks_t; + + +#endif /* INCLUDE_IRC_EVENTS_H */