libircclient/include/libirc_events.h

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