PageRenderTime 31ms CodeModel.GetById 2ms app.highlight 18ms RepoModel.GetById 1ms app.codeStats 0ms

/libs/libircclient/libircclient.h

https://bitbucket.org/jite/jquake
C Header | 1483 lines | 89 code | 104 blank | 1290 comment | 0 complexity | b7488f96914738fce92dd166efba89c0 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1/* 
   2 * Copyright (C) 2004-2009 Georgy 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 2 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 * \file libircclient.h
  17 * \author Georgy Yunaev
  18 * \version 1.0
  19 * \date 09.2004
  20 * \brief This file defines all prototypes and functions to use libircclient.
  21 *
  22 * libircclient is a small but powerful library, which implements client-server IRC
  23 * protocol. It is designed to be small, fast, portable and compatible to RFC
  24 * standards, and most IRC clients. libircclient features include:
  25 * - Full multi-threading support.
  26 * - Single threads handles all the IRC processing.
  27 * - Support for single-threaded applications, and socket-based applications, 
  28 *   which use select()
  29 * - Synchronous and asynchronous interfaces.
  30 * - CTCP support with optional build-in reply code.
  31 * - Flexible DCC support, including both DCC chat, and DCC file transfer.
  32 * - Can both initiate and react to initiated DCC.
  33 * - Can accept or decline DCC sessions asynchronously.
  34 * - Plain C interface and implementation (possible to use from C++ code, 
  35 *   obviously)
  36 * - Compatible with RFC 1459 and most IRC clients.
  37 * - Free, licensed under LGPL license.
  38 *
  39 * Note that to use libircclient, only libircclient.h should be included into your 
  40 * program. Do not include other libirc_* headers.
  41 */
  42
  43#ifndef INCLUDE_LIBIRC_H
  44#define INCLUDE_LIBIRC_H
  45
  46#if !defined (WIN32)
  47	#include <sys/select.h>	/* fd_set */
  48#else
  49	#include <winsock2.h>
  50	#include <ws2tcpip.h>
  51	#if defined (ENABLE_IPV6)
  52		typedef int  (WSAAPI * getaddrinfo_ptr_t)  (const char *, const char* , const struct addrinfo *, struct addrinfo **);
  53		typedef void (WSAAPI * freeaddrinfo_ptr_t) (struct addrinfo*);
  54	#endif
  55#endif
  56
  57#ifdef	__cplusplus
  58extern "C" {
  59#endif
  60
  61/*! \brief A libircclient IRC session.
  62 *
  63 * This structure describes an IRC session. Its members are internal to 
  64 * libircclient, and should not be used directly.
  65 */
  66typedef struct irc_session_s	irc_session_t;
  67
  68/*! \brief A libircclient DCC session.
  69 *
  70 * This structure describes a DCC session used by libircclient. 
  71 * Its members are internal to libircclient, and should not be used directly.
  72 */
  73typedef struct irc_dcc_session_s	irc_dcc_session_t;
  74
  75
  76/*! \brief A DCC session identifier.
  77 *
  78 * The irc_dcc_t type is a DCC session identifier, used to identify the
  79 * DCC sessions in callbacks and various functions.
  80 */
  81typedef unsigned int				irc_dcc_t;
  82
  83
  84/*!
  85 * \fn typedef void (*irc_dcc_callback_t) (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length)
  86 * \brief A common DCC callback, used to inform you about the current DCC state or event.
  87 *
  88 * \param session An IRC session which generates the callback
  89 * \param id  A DCC session id.
  90 * \param status An error status. 0 means no error, otherwise error code.
  91 * \param ctx A user-supplied context.
  92 * \param data Data supplied (if available)
  93 * \param length data length (if available)
  94 *
  95 * This callback is called for all DCC functions when state change occurs.
  96 *
  97 * For DCC CHAT, the callback is called in next circumstances:
  98 * - \a status is LIBIRC_ERR_CLOSED: connection is closed by remote peer. 
  99 *      After returning from the callback, the DCC session is automatically 
 100 *      destroyed.
 101 * - \a status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error 
 102 *      (connect error, accept error, recv error, send error). After returning 
 103 *      from the callback, the DCC session is automatically destroyed.
 104 * - \a status is 0: new chat message received, \a data contains the message
 105 *      (null-terminated string), \a length contains the message length.
 106 *      
 107 * For DCC SEND, while file is sending, callback called in next circumstances:
 108 * - \a status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error 
 109 *      (connect error, accept error, recv error, send error). After returning 
 110 *      from the callback, the DCC session is automatically destroyed.
 111 * - \a status is 0: new data received, \a data contains the data received,
 112 *      \a length contains the amount of data received.
 113 *      
 114 * For DCC RECV, while file is sending, callback called in next circumstances:
 115 * - \a status is neither 0 nor LIBIRC_ERR_CLOSED: socket I/O error 
 116 *      (connect error, accept error, recv error, send error). After returning 
 117 *      from the callback, the DCC session is automatically destroyed.
 118 * - \a status is 0, and \a data is 0: file has been received successfully.
 119 *      After returning from the callback, the DCC session is automatically 
 120 *      destroyed.
 121 * - \a status is 0, and \a data is not 0: new data received, \a data contains 
 122 *      the data received, \a length contains the amount of data received.
 123 *
 124 * \ingroup dccstuff
 125 */
 126typedef void (*irc_dcc_callback_t) (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length);
 127
 128
 129#define IN_INCLUDE_LIBIRC_H
 130#include "libirc_errors.h"
 131#include "libirc_rfcnumeric.h"
 132#include "libirc_events.h"
 133#include "libirc_options.h"
 134
 135#if defined (IN_BUILDING_LIBIRC)
 136	#include "libirc_session.h"
 137	#include "libirc_dcc.h"
 138#endif
 139
 140
 141/*!
 142 * \fn irc_session_t * irc_create_session (irc_callbacks_t * callbacks)
 143 * \brief Creates and initiates a new IRC session.
 144 *
 145 * \param callbacks A structure, which defines several callbacks, which will 
 146 *                  be called on appropriate events. Must not be NULL.
 147 *
 148 * \return An ::irc_session_t object, or 0 if creation failed. Usually,
 149 *         failure is caused by out of memory error.
 150 *
 151 * Every ::irc_session_t object describes a single IRC session - a connection
 152 * to an IRC server, and possibly to some DCC clients. Almost every irc_* 
 153 * function requires this object to be passed to, and therefore this function 
 154 * should be called first.
 155 *
 156 * Every session created must be destroyed when it is not needed anymore
 157 * by calling irc_destroy_session().
 158 *
 159 * The most common function sequence is:
 160 * \code
 161 *  ... prepare irc_callbacks_t structure ...
 162 *  irc_create_session();
 163 *  irc_connect();
 164 *  irc_run();
 165 *  irc_destroy_session();
 166 * \endcode
 167 *
 168 * \sa irc_destroy_session
 169 * \ingroup initclose
 170 */
 171irc_session_t * irc_create_session (irc_callbacks_t	* callbacks);
 172
 173
 174/*!
 175 * \fn void irc_destroy_session (irc_session_t * session)
 176 * \brief Destroys previously created IRC session.
 177 *
 178 * \param session A session to destroy. Must not be NULL.
 179 *
 180 * This function should be used to destroy an IRC session, close the 
 181 * connection to the IRC server, and free all the used resources. After 
 182 * calling this function, you should not use this session object anymore.
 183 *
 184 * \ingroup initclose
 185 */
 186void irc_destroy_session (irc_session_t * session);
 187
 188
 189/*!
 190 * \fn int irc_connect (irc_session_t * session, const char * server, unsigned short port, const char * server_password, const char * nick, const char * username, const char * realname);
 191 * \brief Initiates a connection to IRC server.
 192 *
 193 * \param session A session to initiate connections on. Must not be NULL.
 194 * \param server  A domain name or an IP address of the IRC server to connect 
 195 *                to. Must not be NULL.
 196 * \param port    An IRC server port, usually 6667.
 197 * \param server_password  An IRC server password, if the server requires it.
 198 *                May be NULL, in this case password will not be send to the 
 199 *                IRC server. Vast majority of IRC servers do not require passwords.
 200 * \param nick    A nick, which libircclient will use to login to the IRC server.
 201 *                Must not be NULL.
 202 * \param username A username of the account, which is used to connect to the
 203 *                IRC server. This is for information only, will be shown in
 204 *                "user properties" dialogs and returned by /whois request.
 205 *                May be NULL, in this case 'nobody' will be sent as username.
 206 * \param realname A real name of the person, who connects to the IRC. Usually
 207 *                people put some wide-available information here (URL, small
 208 *                description or something else). This information also will 
 209 *                be shown in "user properties" dialogs and returned by /whois 
 210 *                request. May be NULL, in this case 'noname' will be sent as 
 211 *                username.
 212 *
 213 * \return Return code 0 means success. Other value means error, the error 
 214 *  code may be obtained through irc_errno(). Any error, generated by the 
 215 *  IRC server, is available through irc_callbacks_t::event_numeric.
 216 *
 217 * This function prepares and initiates a connection to the IRC server. The
 218 * connection is done asynchronously (see irc_callbacks_t::event_connect), so the success 
 219 * return value means that connection was initiated (but not completed!)
 220 * successfully.
 221 *
 222 * \sa irc_run
 223 * \ingroup conndisc
 224 */
 225int irc_connect (irc_session_t * session, 
 226			const char * server, 
 227			unsigned short port,
 228			const char * server_password,
 229			const char * nick,
 230			const char * username,
 231			const char * realname);
 232
 233
 234/*!
 235 * \fn int irc_connect6 (irc_session_t * session, const char * server, unsigned short port, const char * server_password, const char * nick, const char * username, const char * realname);
 236 * \brief Initiates a connection to IRC server using IPv6.
 237 *
 238 * \param session A session to initiate connections on. Must not be NULL.
 239 * \param server  A domain name or an IP address of the IRC server to connect 
 240 *                to. Must not be NULL.
 241 * \param port    An IRC server port, usually 6667.
 242 * \param server_password  An IRC server password, if the server requires it.
 243 *                May be NULL, in this case password will not be send to the 
 244 *                IRC server. Vast majority of IRC servers do not require passwords.
 245 * \param nick    A nick, which libircclient will use to login to the IRC server.
 246 *                Must not be NULL.
 247 * \param username A username of the account, which is used to connect to the
 248 *                IRC server. This is for information only, will be shown in
 249 *                "user properties" dialogs and returned by /whois request.
 250 *                May be NULL, in this case 'nobody' will be sent as username.
 251 * \param realname A real name of the person, who connects to the IRC. Usually
 252 *                people put some wide-available information here (URL, small
 253 *                description or something else). This information also will 
 254 *                be shown in "user properties" dialogs and returned by /whois 
 255 *                request. May be NULL, in this case 'noname' will be sent as 
 256 *                username.
 257 *
 258 * \return Return code 0 means success. Other value means error, the error 
 259 *  code may be obtained through irc_errno(). Any error, generated by the 
 260 *  IRC server, is available through irc_callbacks_t::event_numeric.
 261 *
 262 * This function prepares and initiates a connection to the IRC server. The
 263 * connection is done asynchronously (see irc_callbacks_t::event_connect), so the success 
 264 * return value means that connection was initiated (but not completed!)
 265 * successfully.
 266 *
 267 * \sa irc_run
 268 * \ingroup conndisc
 269 */
 270int irc_connect6 (irc_session_t * session, 
 271			const char * server, 
 272			unsigned short port,
 273			const char * server_password,
 274			const char * nick,
 275			const char * username,
 276			const char * realname);
 277
 278/*!
 279 * \fn void irc_disconnect (irc_session_t * session)
 280 * \brief Disconnects a connection to IRC server.
 281 *
 282 * \param session An IRC session.
 283 *
 284 * \return Return code 0 means success. Other value means error, the error 
 285 *  code may be obtained through irc_errno().
 286 *
 287 * This function closes the IRC connection. After that connection is closed,
 288 * libircclient automatically leaves irc_run loop.
 289 *
 290 * \sa irc_connect irc_run
 291 * \ingroup conndisc
 292 */
 293void irc_disconnect (irc_session_t * session);
 294
 295
 296/*!
 297 * \fn int irc_is_connected (irc_session_t * session)
 298 * \brief Checks whether the session is connecting/connected to the IRC server.
 299 *
 300 * \param session An initialized IRC session.
 301 *
 302 * \return Return code 1 means that session is connecting or connected to the
 303 *   IRC server, zero value means that the session has been disconnected.
 304 *
 305 * \sa irc_connect irc_run
 306 * \ingroup conndisc
 307 */
 308int irc_is_connected (irc_session_t * session);
 309
 310
 311/*!
 312 * \fn int irc_run (irc_session_t * session)
 313 * \brief Goes into forever-loop, processing IRC events and generating 
 314 *  callbacks.
 315 *
 316 * \param session An initiated and connected session.
 317 *
 318 * \return Return code 0 means success. Other value means error, the error 
 319 *  code may be obtained through irc_errno().
 320 *
 321 * This function goes into forever loop, processing the IRC events, and 
 322 * calling appropriate callbacks. This function will not return until the 
 323 * server connection is terminated - either by server, or by calling 
 324 * irc_cmd_quit. This function should be used, if you don't need asynchronous
 325 * request processing (i.e. your bot just reacts on the events, and doesn't
 326 * generate it asynchronously). Even in last case, you still can call irc_run,
 327 * and start the asynchronous thread in event_connect handler. See examples. 
 328 *
 329 * \ingroup running 
 330 */
 331int irc_run (irc_session_t * session);
 332
 333
 334/*!
 335 * \fn int irc_add_select_descriptors (irc_session_t * session, fd_set *in_set, fd_set *out_set, int * maxfd)
 336 * \brief Adds IRC socket(s) for the descriptor set to use in select().
 337 *
 338 * \param session An initiated and connected session.
 339 * \param in_set  A FD_IN descriptor set for select()
 340 * \param out_set A FD_OUT descriptor set for select()
 341 * \param maxfd   A max descriptor found.
 342 *
 343 * \return Return code 0 means success. Other value means error, the error 
 344 *  code may be obtained through irc_errno().
 345 *
 346 * This function should be used when you already have a program with select()
 347 * based data processing. You prepare your descriptors, call this function
 348 * to add session's descriptor(s) into set, and then call select(). When it
 349 * returns, you should call irc_add_select_descriptors, which sends/recvs all
 350 * available data, parses received data, calls your callbacks(!), and returns.
 351 * Then you can process your sockets from set. See the example.
 352 *
 353 * \sa irc_process_select_descriptors
 354 * \ingroup running 
 355 */
 356int irc_add_select_descriptors (irc_session_t * session, fd_set *in_set, fd_set *out_set, int * maxfd);
 357
 358
 359/*!
 360 * \fn int irc_process_select_descriptors (irc_session_t * session, fd_set *in_set, fd_set *out_set)
 361 * \brief Processes the IRC socket(s), which descriptor(s) are set.
 362 *
 363 * \param session An initiated and connected session.
 364 * \param in_set  A FD_IN descriptor set for select()
 365 * \param out_set A FD_OUT descriptor set for select()
 366 *
 367 * \return Return code 0 means success. Other value means error, the error 
 368 *  code may be obtained through irc_errno().
 369 *
 370 * This function should be used in pair with irc_add_select_descriptors 
 371 * function. See irc_add_select_descriptors description.
 372 *
 373 * \sa irc_add_select_descriptors
 374 * \ingroup running 
 375 */
 376int irc_process_select_descriptors (irc_session_t * session, fd_set *in_set, fd_set *out_set);
 377
 378
 379/*!
 380 * \fn int irc_send_raw (irc_session_t * session, const char * format, ...)
 381 * \brief Sends raw data to the IRC server.
 382 *
 383 * \param session An initiated and connected session.
 384 * \param format  A printf-formatted string, followed by function args.
 385 *
 386 * \return Return code 0 means success. Other value means error, the error 
 387 *  code may be obtained through irc_errno(). Any error, generated by the 
 388 *  IRC server, is available through irc_callbacks_t::event_numeric.
 389 *
 390 * This function sends the raw data as-is to the IRC server. Use it to 
 391 * generate a server command, which is not (yet) provided by libircclient 
 392 * directly.
 393 *
 394 * \ingroup ircmd_oth
 395 */
 396int irc_send_raw (irc_session_t * session, const char * format, ...);
 397
 398
 399/*!
 400 * \fn int irc_cmd_quit (irc_session_t * session, const char * reason)
 401 * \brief Sends QUIT command to the IRC server.
 402 *
 403 * \param session An initiated and connected session.
 404 * \param reason  A reason to quit. May be NULL.
 405 *
 406 * \return Return code 0 means success. Other value means error, the error 
 407 *  code may be obtained through irc_errno(). Any error, generated by the 
 408 *  IRC server, is available through irc_callbacks_t::event_numeric.
 409 *
 410 * This function sends the QUIT command to the IRC server. This command 
 411 * forces the IRC server to close the IRC connection, and terminate the 
 412 * session.
 413 *
 414 * \ingroup ircmd_oth
 415 */
 416int irc_cmd_quit (irc_session_t * session, const char * reason);
 417
 418
 419/*!
 420 * \fn int irc_cmd_join (irc_session_t * session, const char * channel, const char * key)
 421 * \brief Joins the new IRC channel.
 422 *
 423 * \param session An initiated and connected session.
 424 * \param channel A channel name to join to. Must not be NULL.
 425 * \param key     Channel password. May be NULL.
 426 *
 427 * \return Return code 0 means success. Other value means error, the error 
 428 *  code may be obtained through irc_errno(). Any error, generated by the 
 429 *  IRC server, is available through irc_callbacks_t::event_numeric.
 430 *
 431 * This function is used to JOIN the IRC channel. If the channel is not exist,
 432 * it will be automatically created by the IRC server. Note that to JOIN the
 433 * password-protected channel, you must know the password, and specify it in
 434 * the \a key argument.
 435 *
 436 * If join is successful, the irc_callbacks_t::event_join is called (with \a origin == 
 437 * your nickname), then you are sent the channel's topic 
 438 * (using ::LIBIRC_RFC_RPL_TOPIC) and the list of users who are on the 
 439 * channel (using ::LIBIRC_RFC_RPL_NAMREPLY), which includes the user 
 440 * joining - namely you.
 441 *
 442 * Possible error responces for this command from the RFC1459:
 443 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS
 444 * - ::LIBIRC_RFC_ERR_BANNEDFROMCHAN
 445 * - ::LIBIRC_RFC_ERR_INVITEONLYCHAN
 446 * - ::LIBIRC_RFC_ERR_BADCHANNELKEY
 447 * - ::LIBIRC_RFC_ERR_CHANNELISFULL
 448 * - ::LIBIRC_RFC_ERR_BADCHANMASK
 449 * - ::LIBIRC_RFC_ERR_NOSUCHCHANNEL
 450 * - ::LIBIRC_RFC_ERR_TOOMANYCHANNELS
 451 *
 452 * And on success the following replies returned:
 453 * - ::LIBIRC_RFC_RPL_TOPIC
 454 * - ::LIBIRC_RFC_RPL_NAMREPLY
 455 * 
 456 * \ingroup ircmd_ch
 457 */
 458int irc_cmd_join (irc_session_t * session, const char * channel, const char * key);
 459
 460
 461/*!
 462 * \fn int irc_cmd_part (irc_session_t * session, const char * channel)
 463 * \brief Leaves the IRC channel.
 464 *
 465 * \param session An initiated and connected session.
 466 * \param channel A channel name to leave. Must not be NULL.
 467 *
 468 * \return Return code 0 means success. Other value means error, the error 
 469 *  code may be obtained through irc_errno(). Any error, generated by the 
 470 *  IRC server, is available through irc_callbacks_t::event_numeric.
 471 *
 472 * This function is used to leave the IRC channel you've already joined to.
 473 * An attempt to leave the channel you aren't in results a ::LIBIRC_RFC_ERR_NOTONCHANNEL
 474 * server error.
 475 *
 476 * Possible error responces for this command from the RFC1459:
 477 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS
 478 * - ::LIBIRC_RFC_ERR_NOSUCHCHANNEL
 479 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
 480 *
 481 * \ingroup ircmd_ch
 482 */
 483int irc_cmd_part (irc_session_t * session, const char * channel);
 484
 485
 486/*!
 487 * \fn int irc_cmd_invite (irc_session_t * session, const char * nick, const char * channel)
 488 * \brief Invites a user to invite-only channel.
 489 *
 490 * \param session An initiated and connected session.
 491 * \param nick    A nick to invite. Must not be NULL.
 492 * \param channel A channel name to invite to. Must not be NULL.
 493 *
 494 * \return Return code 0 means success. Other value means error, the error 
 495 *  code may be obtained through irc_errno(). Any error, generated by the 
 496 *  IRC server, is available through irc_callbacks_t::event_numeric.
 497 *
 498 * This function is used to invite someone to invite-only channel. 
 499 * "Invite-only" is a channel mode, which restricts anyone, except invided,
 500 * to join this channel. After invitation, the user could join this channel.
 501 * The user, who is invited, will receive the irc_callbacks_t::event_invite event.
 502 * Note that you must be a channel operator to INVITE the users.
 503 *
 504 * Possible error responces for this command from the RFC1459:
 505 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS
 506 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
 507 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
 508 * - ::LIBIRC_RFC_ERR_ERR_USERONCHANNEL
 509 * - ::LIBIRC_RFC_ERR_ERR_CHANOPRIVSNEEDED
 510 *
 511 * And on success one of the following replies returned:
 512 * - ::LIBIRC_RFC_RPL_INVITING
 513 * - ::LIBIRC_RFC_RPL_AWAY
 514 *
 515 * \sa irc_callbacks_t::event_invite irc_cmd_channel_mode
 516 * \ingroup ircmd_ch
 517 */
 518int irc_cmd_invite (irc_session_t * session, const char * nick, const char * channel);
 519
 520
 521/*!
 522 * \fn int irc_cmd_names (irc_session_t * session, const char * channel)
 523 * \brief Obtains a list of users who're in channel.
 524 *
 525 * \param session An initiated and connected session.
 526 * \param channel A channel name(s) to obtain user list. Must not be NULL. 
 527 *                It is possible to specify more than a single channel, but 
 528 *                several channel names should be separated by a comma.
 529 *
 530 * \return Return code 0 means success. Other value means error, the error 
 531 *  code may be obtained through irc_errno(). Any error, generated by the 
 532 *  IRC server, is available through irc_callbacks_t::event_numeric.
 533 *
 534 * This function is used to ask the IRC server for the list of the users 
 535 * who're in specified channel. You can list all nicknames that are visible 
 536 * to you on any channel that you can see. The list of users will be returned 
 537 * using ::RPL_NAMREPLY and ::RPL_ENDOFNAMES numeric codes.
 538 *
 539 * The channel names are returned by irc_callbacks_t::event_numeric 
 540 * using the following reply codes:
 541 * - ::LIBIRC_RFC_RPL_NAMREPLY
 542 * - ::LIBIRC_RFC_RPL_ENDOFNAMES
 543 *
 544 * \ingroup ircmd_ch
 545 */
 546int irc_cmd_names (irc_session_t * session, const char * channel);
 547
 548
 549/*!
 550 * \fn int irc_cmd_list (irc_session_t * session, const char * channel)
 551 * \brief Obtains a list of active server channels with their topics.
 552 *
 553 * \param session An initiated and connected session.
 554 * \param channel A channel name(s) to list. May be NULL, in which case all the
 555 *                channels will be listed. It is possible to specify more than 
 556 *                a single channel, but several channel names should be 
 557 *                separated by a comma.
 558 *
 559 * \return Return code 0 means success. Other value means error, the error 
 560 *  code may be obtained through irc_errno(). Any error, generated by the 
 561 *  IRC server, is available through irc_callbacks_t::event_numeric.
 562 *
 563 * This function is used to ask the IRC server for the active (existing) 
 564 * channels list. The list will be returned using ::LIBIRC_RFC_RPL_LISTSTART - 
 565 * ::LIBIRC_RFC_RPL_LIST - ::LIBIRC_RFC_RPL_LISTEND sequence.
 566 * Note that "private" channels are listed (without their topics) as channel 
 567 * "Prv" unless the client generating the LIST query is actually on that 
 568 * channel. Likewise, secret channels are 
 569 * not listed at all unless the client is a member of the channel in question.
 570 *
 571 * Possible error responces for this command from the RFC1459:
 572 * - ::LIBIRC_RFC_ERR_NOSUCHSERVER
 573 *
 574 * And the channel list is returned using the following reply codes:
 575 * - ::LIBIRC_RFC_RPL_LISTSTART
 576 * - ::LIBIRC_RFC_RPL_LISTEND
 577 * - ::LIBIRC_RFC_RPL_LIST
 578 *
 579 * \ingroup ircmd_ch
 580 */
 581int irc_cmd_list (irc_session_t * session, const char * channel);
 582
 583
 584/*!
 585 * \fn int irc_cmd_topic (irc_session_t * session, const char * channel, const char * topic)
 586 * \brief Views or changes the channel topic.
 587 *
 588 * \param session An initiated and connected session.
 589 * \param channel A channel name to invite to. Must not be NULL.
 590 * \param topic   A new topic to change. If NULL, the old topic will be 
 591 *                returned, and topic won't changed.
 592 *
 593 * \return Return code 0 means success. Other value means error, the error 
 594 *  code may be obtained through irc_errno(). Any error, generated by the 
 595 *  IRC server, is available through irc_callbacks_t::event_numeric.
 596 *
 597 * The irc_cmd_topic() is used to change or view the topic of a channel.
 598 * The topic for \a channel is returned if \a topic is NULL. If the \a topic
 599 * is not NULL, the topic for the \a channel will be changed. Note that, 
 600 * depending on \a +t channel mode, you may be required to be a channel 
 601 * operator to change the channel topic.
 602 *
 603 * If the command succeed, the IRC server will generate a ::RPL_NOTOPIC or 
 604 * ::RPL_TOPIC message, containing either old or changed topic. Also the IRC
 605 * server can (but not have to) generate the non-RFC ::RPL_TOPIC_EXTRA message,
 606 * containing the nick of person, who's changed the topic, and the time of 
 607 * latest topic change.
 608 *
 609 * Possible error responces for this command from the RFC1459:
 610 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS
 611 * - ::LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
 612 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
 613 *
 614 * And the topic information is returned using one of following reply codes:
 615 * - ::LIBIRC_RFC_RPL_NOTOPIC
 616 * - ::LIBIRC_RFC_RPL_TOPIC
 617 *
 618 * \sa irc_callbacks_t::event_topic irc_cmd_channel_mode
 619 * \ingroup ircmd_ch
 620 */
 621int irc_cmd_topic (irc_session_t * session, const char * channel, const char * topic);
 622
 623
 624/*!
 625 * \fn int irc_cmd_channel_mode (irc_session_t * session, const char * channel, const char * mode)
 626 * \brief Views or changes the channel mode.
 627 *
 628 * \param session An initiated and connected session.
 629 * \param channel A channel name to invite to. Must not be NULL.
 630 * \param mode    A channel mode, described below. If NULL, the channel mode is
 631 *                not changed, just the old mode is returned.
 632 *
 633 * \return Return code 0 means success. Other value means error, the error 
 634 *  code may be obtained through irc_errno(). Any error, generated by the 
 635 *  IRC server, is available through irc_callbacks_t::event_numeric.
 636 *
 637 * The irc_cmd_channel_mode() is used to change or view the channel modes.
 638 * The \a channel mode is returned if the \a mode is NULL. If the \a mode
 639 * is not NULL, the mode for the \a channel will be changed. Note that, 
 640 * only channel operators can change the channel modes.
 641 *
 642 * Channel mode is represended by the letters combination. Every letter has
 643 * its own meaning in channel modes. Most channel mode letters are boolean
 644 * (i.e. could only be set or reset), but a few channel mode letters accept a 
 645 * parameter. All channel options are set by adding a plus sign before the 
 646 * letter, and reset by adding a minus sign before the letter.
 647 * 
 648 * Here is the list of 'standard' channel modes:
 649 *
 650 * - \a o \a nickname - gives (+o nick) or takes (-o nick) the channel 
 651 *      operator privileges from  a \a nickname. This mode affects the 
 652 *      users in channel, not the channel itself. 
 653 *      Examples: "+o tim", "-o watson".
 654 *
 655 * - \a p - sets (+p) or resets (-p) private channel flag. 
 656 *      Private channels are shown in channel list as 'Prv', without the topic.
 657 *
 658 * - \a s - sets (+p) or resets (-p) secret channel flag. 
 659 *      Secret channels aren't shown in channel list at all.
 660 *
 661 * - \a i - sets (+i) or resets (-i) invite-only channel flag. When the flag
 662 *      is set, only the people who are invited by irc_cmd_invite(), can
 663 *      join this channel.
 664 *
 665 * - \a t - sets (+t) or resets (-t) topic settable by channel operator only
 666 *      flag. When the flag is set, only the channel operators can change the
 667 *      channel topic.
 668 *
 669 * - \a n - sets (+n) or resets (-n) the protection from the clients outside 
 670 *      the channel. When the \a +n mode is set, only the clients, who are in 
 671 *      channel, can send the messages to the channel.
 672 *
 673 * - \a m - sets (+m) or resets (-m) the moderation of the channel. When the
 674 *      moderation mode is set, only channel operators and the users who have
 675 *      the \a +v user mode can speak in the channel.
 676 *
 677 * - \a v \a nickname - gives (+v nick) or takes (-v nick) from user the 
 678 *      ability to speak on a moderated channel.
 679 *      Examples: "+v tim", "-v watson".
 680 *
 681 * - \a l \a number - sets (+l 20) or removes (-l) the restriction of maximum
 682 *      users in channel. When the restriction is set, and there is a number
 683 *      of users in the channel, no one can join the channel anymore.
 684 *
 685 * - \a k \a key - sets (+k secret) or removes (-k) the password from the 
 686 *      channel. When the restriction is set, any user joining the channel 
 687 *      required to provide a channel key.
 688 *
 689 * - \a b \a mask - sets (+b *!*@*.mil) or removes (-b *!*@*.mil) the ban mask
 690 *      on a user to keep him out of channel. Note that to remove the ban you 
 691 *      must specify the ban mask to remove, not just "-b".
 692 *
 693 * Note that the actual list of channel modes depends on the IRC server, and
 694 * can be bigger. If you know the popular channel modes, which aren't 
 695 * mentioned here - please contact me at tim@krasnogorsk.ru
 696 *
 697 * Possible error responces for this command from the RFC1459:
 698 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS
 699 * - ::LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
 700 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
 701 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
 702 * - ::LIBIRC_RFC_ERR_KEYSET
 703 * - ::LIBIRC_RFC_ERR_UNKNOWNMODE
 704 * - ::LIBIRC_RFC_ERR_NOSUCHCHANNEL
 705 *
 706 * And the mode information is given using following reply codes:
 707 * - ::LIBIRC_RFC_RPL_CHANNELMODEIS
 708 * - ::LIBIRC_RFC_RPL_BANLIST
 709 * - ::LIBIRC_RFC_RPL_ENDOFBANLIST
 710 *
 711 * \sa irc_cmd_topic irc_cmd_list
 712 * \ingroup ircmd_ch
 713 */
 714int irc_cmd_channel_mode (irc_session_t * session, const char * channel, const char * mode);
 715
 716
 717/*!
 718 * \fn int irc_cmd_user_mode (irc_session_t * session, const char * mode)
 719 * \brief Views or changes your own user mode.
 720 *
 721 * \param session An initiated and connected session.
 722 * \param mode    A user mode, described below. If NULL, the user mode is
 723 *                not changed, just the old mode is returned.
 724 *
 725 * \return Return code 0 means success. Other value means error, the error 
 726 *  code may be obtained through irc_errno(). Any error, generated by the 
 727 *  IRC server, is available through irc_callbacks_t::event_numeric.
 728 *
 729 * The irc_cmd_user_mode() is used to change or view the user modes.
 730 * Note that, unlike channel modes, not all user modes can be changed. 
 731 * The user mode is returned if the \a mode is NULL. If the \a mode
 732 * is not NULL, the mode for you will be changed, and new mode will be 
 733 * returned.
 734 *
 735 * Like channel mode, user mode is also represended by the letters combination.
 736 * All the user mode letters are boolean (i.e. could only be set or reset),
 737 * they are set by adding a plus sign before the letter, and reset by adding 
 738 * a minus sign before the letter.
 739 * 
 740 * Here is the list of 'standard' user modes:
 741 *
 742 * - \a o - represents an IRC operator status. Could not be set directly (but
 743 *      can be reset though), to set it use the IRC \a OPER command.
 744 *
 745 * - \a i - if set, marks a user as 'invisible' - that is, not seen by lookups 
 746 *      if the user is not in a channel.
 747 *
 748 * - \a w - if set, marks a user as 'receiving wallops' - special messages 
 749 *      generated by IRC operators using WALLOPS command.
 750 *
 751 * - \a s - if set, marks a user for receipt of server notices.
 752 *
 753 * - \a r - NON-STANDARD MODE. If set, user has been authenticated with 
 754 *      NICKSERV IRC service.
 755 *
 756 * - \a x - NON-STANDARD MODE. If set, user's real IP is hidden by IRC 
 757 *      servers, to prevent scriptkiddies to do nasty things to the user's 
 758 *      computer.
 759 *
 760 * Note that the actual list of user modes depends on the IRC server, and
 761 * can be bigger. If you know the popular user modes, which aren't 
 762 * mentioned here - please contact me at tim@krasnogorsk.ru
 763 *
 764 * Possible error responces for this command from the RFC1459:
 765 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS
 766 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
 767 * - ::LIBIRC_RFC_ERR_UNKNOWNMODE
 768 * - ::LIBIRC_RFC_ERR_USERSDONTMATCH
 769 * - ::LIBIRC_RFC_ERR_UMODEUNKNOWNFLAG
 770 *
 771 * And the mode information is given using reply code ::LIBIRC_RFC_RPL_UMODEIS
 772 *
 773 * \ingroup ircmd_oth
 774 */
 775int irc_cmd_user_mode (irc_session_t * session, const char * mode);
 776
 777
 778/*!
 779 * \fn int irc_cmd_nick (irc_session_t * session, const char * newnick)
 780 * \brief Changes your nick.
 781 *
 782 * \param session An initiated and connected session.
 783 * \param newnick A new nick. Must not be NULL.
 784 *
 785 * \return Return code 0 means success. Other value means error, the error 
 786 *  code may be obtained through irc_errno(). Any error, generated by the 
 787 *  IRC server, is available through irc_callbacks_t::event_numeric.
 788 *
 789 * This function is used to change your current nick to another nick. Note 
 790 * that such a change is not always possible; for example you cannot change 
 791 * nick to the existing nick, or (on some servers) to the registered nick.
 792 *
 793 * Possible error responces for this command from the RFC1459:
 794 * - ::LIBIRC_RFC_ERR_NONICKNAMEGIVEN
 795 * - ::LIBIRC_RFC_ERR_ERRONEUSNICKNAME
 796 * - ::LIBIRC_RFC_ERR_NICKNAMEINUSE
 797 * - ::LIBIRC_RFC_ERR_NICKCOLLISION
 798 *
 799 * \ingroup ircmd_oth
 800 */
 801int irc_cmd_nick (irc_session_t * session, const char * newnick);
 802
 803
 804/*!
 805 * \fn int irc_cmd_whois (irc_session_t * session, const char * nick)
 806 * \brief Queries the information about the nick.
 807 *
 808 * \param session An initiated and connected session.
 809 * \param nick    A nick to query the information abour. Must not be NULL. 
 810 *                A comma-separated list of several nicknames may be given.
 811 *
 812 * \return Return code 0 means success. Other value means error, the error 
 813 *  code may be obtained through irc_errno(). Any error, generated by the 
 814 *  IRC server, is available through irc_callbacks_t::event_numeric.
 815 *
 816 * This function queries various information about the nick: username, real 
 817 * name, the IRC server used, the channels user is in, idle time, away mode and so on.
 818 *
 819 * Possible error responces for this command from the RFC1459:
 820 * - ::LIBIRC_RFC_ERR_NOSUCHSERVER
 821 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
 822 * - ::LIBIRC_RFC_ERR_NONICKNAMEGIVEN
 823 *
 824 * And the information is returned using the following reply codes. The whois
 825 * query is completed when ::LIBIRC_RFC_RPL_ENDOFWHOIS message is received.
 826 * - ::LIBIRC_RFC_RPL_WHOISUSER
 827 * - ::LIBIRC_RFC_RPL_WHOISCHANNELS
 828 * - ::LIBIRC_RFC_RPL_WHOISSERVER
 829 * - ::LIBIRC_RFC_RPL_AWAY
 830 * - ::LIBIRC_RFC_RPL_WHOISOPERATOR
 831 * - ::LIBIRC_RFC_RPL_WHOISIDLE
 832 * - ::LIBIRC_RFC_RPL_ENDOFWHOIS
 833 *
 834 * \ingroup ircmd_oth
 835 */
 836int irc_cmd_whois (irc_session_t * session, const char * nick);
 837
 838
 839/*!
 840 * \fn irc_cmd_msg  (irc_session_t * session, const char * nch, const char * text)
 841 * \brief Sends the message to the nick or to the channel.
 842 *
 843 * \param session An initiated and connected session.
 844 * \param nch     A target nick or channel. Must not be NULL.
 845 * \param text    Message text. Must not be NULL.
 846 *
 847 * \return Return code 0 means success. Other value means error, the error 
 848 *  code may be obtained through irc_errno(). Any error, generated by the 
 849 *  IRC server, is available through irc_callbacks_t::event_numeric.
 850 *
 851 * This function is used to send the channel or private messages. The target
 852 * is determined by \a nch argument: if it describes nick, this will be a 
 853 * private message, if a channel name - public (channel) message. Note that
 854 * depending on channel modes, you may be required to join the channel to
 855 * send the channel messages.
 856 *
 857 * Possible error responces for this command from the RFC1459:
 858 * - ::LIBIRC_RFC_ERR_NORECIPIENT
 859 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND
 860 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
 861 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
 862 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL
 863 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL
 864 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS
 865 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
 866 *
 867 * On success there is NOTHING generated.
 868 *
 869 * \ingroup ircmd_msg
 870 */
 871int irc_cmd_msg  (irc_session_t * session, const char * nch, const char * text);
 872
 873
 874/*!
 875 * \fn int irc_cmd_me	 (irc_session_t * session, const char * nch, const char * text)
 876 * \brief Sends the /me (CTCP ACTION) message to the nick or to the channel.
 877 *
 878 * \param session An initiated and connected session.
 879 * \param nch     A target nick or channel. Must not be NULL.
 880 * \param text    Action message text. Must not be NULL.
 881 *
 882 * \return Return code 0 means success. Other value means error, the error 
 883 *  code may be obtained through irc_errno(). Any error, generated by the 
 884 *  IRC server, is available through irc_callbacks_t::event_numeric.
 885 *
 886 * This function is used to send the /me message to channel or private.
 887 * As for irc_cmd_msg, the target is determined by \a nch argument.
 888 *
 889 * Possible error responces for this command from the RFC1459:
 890 * - ::LIBIRC_RFC_ERR_NORECIPIENT
 891 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND
 892 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
 893 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
 894 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL
 895 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL
 896 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS
 897 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
 898 *
 899 * On success there is NOTHING generated. 
 900 * However, a ::LIBIRC_RFC_RPL_AWAY reply can be also generated.            
 901 *
 902 * \sa irc_cmd_msg
 903 * \ingroup ircmd_msg
 904 */
 905int irc_cmd_me (irc_session_t * session, const char * nch, const char * text);
 906
 907
 908/*!
 909 * \fn int irc_cmd_notice (irc_session_t * session, const char * nch, const char * text)
 910 * \brief Sends the notice to the nick or to the channel.
 911 *
 912 * \param session An initiated and connected session.
 913 * \param nch     A target nick or channel. Must not be NULL.
 914 * \param text    Notice text. Must not be NULL.
 915 *
 916 * \return Return code 0 means success. Other value means error, the error 
 917 *  code may be obtained through irc_errno(). Any error, generated by the 
 918 *  IRC server, is available through irc_callbacks_t::event_numeric.
 919 *
 920 * This function is used to send the channel or private notices. The target
 921 * is determined by \a nch argument: if it describes nick, this will be a 
 922 * private message, if a channel name - public (channel) message. Note that
 923 * depending on channel modes, you may be required to join the channel to
 924 * send the channel notices.
 925 *
 926 * The only difference between message and notice is that, according to RFC 
 927 * 1459, you must not automatically reply to NOTICE messages.
 928 *
 929 * Possible error responces for this command from the RFC1459:
 930 * - ::LIBIRC_RFC_ERR_NORECIPIENT
 931 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND
 932 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
 933 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
 934 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL
 935 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL
 936 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS
 937 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
 938 *
 939 * On success there is NOTHING generated. On notices sent to target nick, 
 940 * a ::LIBIRC_RFC_RPL_AWAY reply may be generated.
 941 *
 942 * \sa irc_cmd_msg
 943 * \ingroup ircmd_msg
 944 */
 945int irc_cmd_notice (irc_session_t * session, const char * nch, const char * text);
 946
 947
 948/*!
 949 * \fn int irc_cmd_kick (irc_session_t * session, const char * nick, const char * channel, const char * reason)
 950 * \brief Kick some lazy ass out of channel.
 951 *
 952 * \param session An initiated and connected session.
 953 * \param nick    A nick to kick. Must not be NULL.
 954 * \param channel A channel to kick this nick out of. Must not be NULL.
 955 * \param reason  A reason to kick. May be NULL.
 956 *
 957 * \return Return code 0 means success. Other value means error, the error 
 958 *  code may be obtained through irc_errno(). Any error, generated by the 
 959 *  IRC server, is available through irc_callbacks_t::event_numeric.
 960 *
 961 * This function is used to kick a person out of channel. Note that you must
 962 * be a channel operator to kick anyone.
 963 *
 964 * Possible error responces for this command from the RFC1459:
 965 * - ::LIBIRC_RFC_ERR_NEEDMOREPARAMS
 966 * - ::LIBIRC_RFC_ERR_BADCHANMASK
 967 * - ::LIBIRC_RFC_ERR_NOSUCHCHANNEL
 968 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
 969 * - ::LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
 970 *
 971 * On success the irc_callbacks_t::event_kick event will be generated.
 972 *
 973 * \sa irc_callbacks_t::event_numeric
 974 * \ingroup ircmd_ch
 975 */
 976int irc_cmd_kick (irc_session_t * session, const char * nick, const char * channel, const char * reason);
 977
 978
 979/*!
 980 * \fn int irc_cmd_ctcp_request (irc_session_t * session, const char * nick, const char * request)
 981 * \brief Generates a CTCP request.
 982 *
 983 * \param session An initiated and connected session.
 984 * \param nick    A target nick to send request to. Must not be NULL.
 985 * \param request A request string. Must not be NULL.
 986 *
 987 * \return Return code 0 means success. Other value means error, the error 
 988 *  code may be obtained through irc_errno(). Any error, generated by the 
 989 *  IRC server, is available through irc_callbacks_t::event_numeric.
 990 *
 991 * This function is used to send a CTCP request. There are four CTCP requests
 992 * supported by Mirc:
 993 *  VERSION - get the client software name and version
 994 *  FINGER  - get the client username, host and real name.
 995 *  PING    - get the client delay.
 996 *  TIME    - get the client local time.
 997 *
 998 * A reply to the CTCP request will be sent by the irc_callbacks_t::event_ctcp_rep callback;
 999 * be sure to define it.
1000 *
1001 * Possible error responces for this command from the RFC1459:
1002 * - ::LIBIRC_RFC_ERR_NORECIPIENT
1003 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND
1004 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
1005 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
1006 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL
1007 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL
1008 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS
1009 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
1010 *
1011 * \sa irc_callbacks_t::event_ctcp_rep irc_callbacks_t::event_numeric
1012 * \ingroup ctcp
1013 */
1014int irc_cmd_ctcp_request (irc_session_t * session, const char * nick, const char * request);
1015
1016
1017/*!
1018 * \fn int irc_cmd_ctcp_reply (irc_session_t * session, const char * nick, const char * reply)
1019 * \brief Generates a reply to the CTCP request.
1020 *
1021 * \param session An initiated and connected session.
1022 * \param nick    A target nick to send request to. Must not be NULL.
1023 * \param reply   A reply string. Must not be NULL.
1024 *
1025 * \return Return code 0 means success. Other value means error, the error 
1026 *  code may be obtained through irc_errno(). Any error, generated by the 
1027 *  IRC server, is available through irc_callbacks_t::event_numeric.
1028 *
1029 * This function is used to send a reply to the CTCP request, generated by 
1030 * irc_callbacks_t::event_ctcp_req. Note that you will not receive this event
1031 * unless you specify your own handler as \c event_ctcp_req callback during
1032 * the IRC session initialization.
1033 *
1034 * Possible error responces for this command from the RFC1459:
1035 * - ::LIBIRC_RFC_ERR_NORECIPIENT
1036 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND
1037 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
1038 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
1039 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL
1040 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL
1041 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS
1042 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
1043 *
1044 * \ingroup ctcp
1045 */
1046int irc_cmd_ctcp_reply (irc_session_t * session, const char * nick, const char * reply);
1047
1048
1049/*!
1050 * \fn void irc_target_get_nick (const char * target, char *nick, size_t size)
1051 * \brief Gets the nick part from the target
1052 *
1053 * \param target  A nick in common IRC server form like tim!root\@mycomain.com
1054 * \param nick    A buffer to hold the nickname.
1055 * \param size    A buffer size. If nick is longer than buffer size, it will 
1056 *                be truncated.
1057 *
1058 * For most events IRC server returns 'origin' (i.e. the person, who 
1059 * generated this event) in i.e. "common" form, like nick!host\@domain.
1060 * However, all the irc_cmd_* functions require just a nick/
1061 * This function parses this origin, and gets the nick, storing it into 
1062 * user-provided buffer.
1063 * A buffer of size 90 should be enough for most nicks :)
1064 *
1065 * \ingroup nnparse
1066 */
1067void irc_target_get_nick (const char * target, char *nick, size_t size);
1068
1069
1070/*!
1071 * \fn void irc_target_get_host (const char * target, char *nick, size_t size)
1072 * \brief Gets the host part from the target
1073 *
1074 * \param target  A nick in common IRC server form like tim!root\@mydomain.com
1075 * \param nick    A buffer to hold the nickname.
1076 * \param size    A buffer size. If nick is longer than buffer size, it will 
1077 *                be truncated.
1078 *
1079 * For most events IRC server returns 'origin' (i.e. the person, who 
1080 * generated this event) in i.e. "common" form, like nick!host\@domain.
1081 * I don't know any command, which requires host, but it may be useful :)
1082 * This function parses this origin, and gets the host, storing it into 
1083 * user-provided buffer.
1084 *
1085 * \ingroup nnparse
1086 */
1087void irc_target_get_host (const char * target, char *nick, size_t size);
1088
1089
1090/*!
1091 * \fn int irc_dcc_chat(irc_session_t * session, void * ctx, const char * nick, irc_dcc_callback_t callback, irc_dcc_t * dccid)
1092 * \brief Initiates a DCC CHAT.
1093 *
1094 * \param session An initiated and connected session.
1095 * \param ctx     A user-supplied DCC session context, which will be passed to 
1096 *                the DCC callback function. May be NULL.
1097 * \param nick    A nick to DCC CHAT with.
1098 * \param callback A DCC callback function, which will be called when 
1099 *                anything is said by other party. Must not be NULL.
1100 * \param dccid   On success, DCC session ID will be stored in this var.
1101 *
1102 * \return Return code 0 means success. Other value means error, the error 
1103 *  code may be obtained through irc_errno(). Any error, generated by the 
1104 *  IRC server, is available through irc_callbacks_t::event_numeric.
1105 *
1106 * This function requests a DCC CHAT between you and other user. For 
1107 * newbies, DCC chat is like private chat, but it goes directly between
1108 * two users, and bypasses IRC server. DCC CHAT request must be accepted 
1109 * by other side before you can send anything.
1110 *
1111 * When the chat is accepted, terminated, or some data is received, the 
1112 * callback function is called. See the details in irc_dcc_callback_t 
1113 * declaration.
1114 *
1115 * Possible error responces for this command from the RFC1459:
1116 * - ::LIBIRC_RFC_ERR_NORECIPIENT
1117 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND
1118 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
1119 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
1120 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL
1121 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL
1122 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS
1123 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
1124 *
1125 * \sa irc_dcc_callback_t irc_dcc_msg
1126 * \ingroup dccstuff
1127 */
1128int irc_dcc_chat (irc_session_t * session, void * ctx, const char * nick, irc_dcc_callback_t callback, irc_dcc_t * dccid);
1129
1130
1131/*!
1132 * \fn int irc_dcc_msg	(irc_session_t * session, irc_dcc_t dccid, const char * text)
1133 * \brief Sends the message to the specific DCC CHAT
1134 *
1135 * \param session An IRC session.
1136 * \param dccid   A DCC session ID, which chat request must have been accepted.
1137 * \param text    Message text. Must not be NULL.
1138 *
1139 * \return Return code 0 means success. Other value means error, the error 
1140 *  code may be obtained through irc_errno().
1141 *
1142 * This function is used to send the DCC CHAT messages. DCC CHAT request
1143 * must be initiated and accepted first (or just accepted, if initiated by
1144 * other side).
1145 *
1146 * \sa irc_dcc_chat
1147 * \ingroup dccstuff
1148 */
1149int irc_dcc_msg	(irc_session_t * session, irc_dcc_t dccid, const char * text);
1150
1151
1152/*!
1153 * \fn int irc_dcc_accept (irc_session_t * session, irc_dcc_t dccid, void * ctx, irc_dcc_callback_t callback)
1154 * \brief Accepts a remote DCC CHAT or DCC RECVFILE request.
1155 *
1156 * \param session An initiated and connected session.
1157 * \param dccid   A DCC session ID, returned by appropriate callback.
1158 * \param ctx     A user-supplied DCC session context, which will be passed 
1159 *                to the DCC callback function. May be NULL.
1160 * \param callback A DCC callback function, which will be called when 
1161 *                anything is said by other party. Must not be NULL.
1162 *
1163 * \return Return code 0 means success. Other value means error, the error 
1164 *  code may be obtained through irc_errno().
1165 *
1166 * This function accepts a remote DCC request - either DCC CHAT or DCC FILE.
1167 * After the request is accepted, the supplied callback will be called,
1168 * and you can start sending messages or receiving the file.
1169 *
1170 * This function should be called only after either event_dcc_chat_req or
1171 * event_dcc_send_req events are generated, and should react to them. It is
1172 * possible not to call irc_dcc_accept or irc_dcc_decline immediately in 
1173 * callback function - you may just return, and call it later. However, to
1174 * prevent memory leaks, you must call either irc_dcc_decline or 
1175 * irc_dcc_accept for any incoming DCC request.
1176 * 
1177 * \sa irc_dcc_decline event_dcc_chat_req event_dcc_send_req
1178 * \ingroup dccstuff
1179 */
1180int	irc_dcc_accept (irc_session_t * session, irc_dcc_t dccid, void * ctx, irc_dcc_callback_t callback);
1181
1182
1183/*!
1184 * \fn int irc_dcc_decline (irc_session_t * session, irc_dcc_t dccid)
1185 * \brief Declines a remote DCC CHAT or DCC RECVFILE request.
1186 *
1187 * \param session An initiated and connected session.
1188 * \param dccid   A DCC session ID, returned by appropriate callback.
1189 *
1190 * \return Return code 0 means success. Other value means error, the error 
1191 *  code may be obtained through irc_errno().
1192 *
1193 * This function declines a remote DCC request - either DCC CHAT or DCC FILE.
1194 *
1195 * This function should be called only after either event_dcc_chat_req or
1196 * event_dcc_send_req events are generated, and should react to them. It is
1197 * possible not to call irc_dcc_accept or irc_dcc_decline immediately in 
1198 * callback function - you may just return, and call it later. However, to
1199 * prevent memory leaks, you must call either irc_dcc_decline or 
1200 * irc_dcc_accept for any incoming DCC request.
1201 *
1202 * Do not use this function to close the accepted or initiated DCC session.
1203 * Use irc_dcc_destroy instead.
1204 *
1205 * \sa irc_dcc_accept irc_callbacks_t::event_dcc_chat_req irc_callbacks_t::event_dcc_send_req irc_dcc_destroy
1206 * \ingroup dccstuff
1207 */
1208int irc_dcc_decline (irc_session_t * session, irc_dcc_t dccid);
1209
1210
1211/*!
1212 * \fn int…

Large files files are truncated, but you can click here to view the full file