PageRenderTime 80ms CodeModel.GetById 51ms app.highlight 15ms RepoModel.GetById 6ms 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
   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 irc_dcc_sendfile (irc_session_t * session, void * ctx, const char * nick, const char * filename, irc_dcc_callback_t callback, irc_dcc_t * dccid)
1213 * \brief Sends a file via DCC.
1214 *
1215 * \param session An initiated and connected session.
1216 * \param ctx     A user-supplied DCC session context, which will be passed to 
1217 *                the DCC callback function. May be NULL.
1218 * \param nick    A nick to send file via DCC to.
1219 * \param filename A file name to sent. Must be an existing file.
1220 * \param callback A DCC callback function, which will be called when 
1221 *                file sent operation is failed, progressed or completed.
1222 * \param dccid   On success, DCC session ID will be stored in this var.
1223 *
1224 * \return Return code 0 means success. Other value means error, the error 
1225 *  code may be obtained through irc_errno(). Any error, generated by the 
1226 *  IRC server, is available through irc_callbacks_t::event_numeric.
1227 *
1228 * This function generates a DCC SEND request to send the file. When it is
1229 * accepted, the file is sent to the remote party, and the DCC session is
1230 * closed. The send operation progress and result can be checked in 
1231 * callback. See the details in irc_dcc_callback_t declaration.
1232 *
1233 * Possible error responces for this command from the RFC1459:
1234 * - ::LIBIRC_RFC_ERR_NORECIPIENT
1235 * - ::LIBIRC_RFC_ERR_NOTEXTTOSEND
1236 * - ::LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
1237 * - ::LIBIRC_RFC_ERR_NOTONCHANNEL
1238 * - ::LIBIRC_RFC_ERR_NOTOPLEVEL
1239 * - ::LIBIRC_RFC_ERR_WILDTOPLEVEL
1240 * - ::LIBIRC_RFC_ERR_TOOMANYTARGETS
1241 * - ::LIBIRC_RFC_ERR_NOSUCHNICK
1242 *
1243 * \sa irc_dcc_callback_t
1244 * \ingroup dccstuff
1245 */
1246int irc_dcc_sendfile (irc_session_t * session, void * ctx, const char * nick, const char * filename, irc_dcc_callback_t callback, irc_dcc_t * dccid);
1247
1248
1249/*!
1250 * \fn int irc_dcc_destroy (irc_session_t * session, irc_dcc_t dccid)
1251 * \brief Destroys a DCC session.
1252 *
1253 * \param session An initiated and connected session.
1254 * \param dccid   A DCC session ID.
1255 *
1256 * \return Return code 0 means success. Other value means error, the error 
1257 *  code may be obtained through irc_errno().
1258 *
1259 * This function closes the DCC connection (if available), and destroys
1260 * the DCC session, freeing the used resources. It can be called in any 
1261 * moment, even from callbacks or from different threads.
1262 *
1263 * Note that when DCC session is finished (either with success or failure),
1264 * you should not destroy it - it will be destroyed automatically.
1265 *
1266 * \ingroup dccstuff
1267 */
1268int irc_dcc_destroy (irc_session_t * session, irc_dcc_t dccid);
1269
1270
1271/*!
1272 * \fn void irc_get_version (unsigned int * high, unsigned int * low)
1273 * \brief Obtains a libircclient version.
1274 *
1275 * \param high A pointer to receive the high version part.
1276 * \param low  A pointer to receive the low version part.
1277 *
1278 * This function returns the libircclient version. You can use the version either
1279 * to check whether required options are available, or to output the version.
1280 * The preferred printf-like format string to output the version is:
1281 *
1282 * printf ("Version: %d.%02d", high, low);
1283 *
1284 * \ingroup common
1285 */
1286void irc_get_version (unsigned int * high, unsigned int * low);
1287
1288
1289/*!
1290 * \fn void irc_set_ctx (irc_session_t * session, void * ctx)
1291 * \brief Sets the IRC session context.
1292 *
1293 * \param session An initiated session.
1294 * \param ctx  A context.
1295 *
1296 * This function sets the user-defined context for this IRC session. This
1297 * context is not used by libircclient. Its purpose is to store session-specific
1298 * user data, which may be obtained later by calling irc_get_ctx().
1299 * Note that libircclient just 'carries out' this pointer. If you allocate some
1300 * memory, and store its address in ctx (most common usage), it is your 
1301 * responsibility to free it before calling irc_destroy_session().
1302 *
1303 * \sa irc_get_ctx
1304 * \ingroup contexts
1305 */
1306void irc_set_ctx (irc_session_t * session, void * ctx);
1307
1308
1309/*!
1310 * \fn void * irc_get_ctx (irc_session_t * session)
1311 * \brief Returns the IRC session context.
1312 *
1313 * \param session An initiated session.
1314 *
1315 * This function returns the IRC session context, which was set by 
1316 * irc_set_ctx(). If no context was set, this function returns NULL.
1317 *
1318 * \sa irc_set_ctx
1319 * \ingroup contexts
1320 */
1321void * irc_get_ctx (irc_session_t * session);
1322
1323
1324/*!
1325 * \fn int irc_errno (irc_session_t * session)
1326 * \brief Returns the last error code.
1327 *
1328 * \param session An initiated session.
1329 *
1330 * This function returns the last error code associated with last operation
1331 * of this IRC session. Possible error codes are defined in libirc_errors.h
1332 *
1333 * As usual, next errno rules apply:
1334 * - irc_errno() should be called ONLY if the called function fails;
1335 * - irc_errno() doesn't return 0 if function succeed; actually, the return
1336 *    value will be undefined.
1337 * - you should call irc_errno() IMMEDIATELY after function fails, before 
1338 *   calling any other libircclient function.
1339 *
1340 * \sa irc_strerror
1341 * \ingroup errors
1342 */
1343int irc_errno (irc_session_t * session);
1344
1345
1346/*!
1347 * \fn const char * irc_strerror (int ircerrno)
1348 * \brief Returns the text error message associated with this error code.
1349 *
1350 * \param ircerrno A numeric error code returned by irc_errno()
1351 *
1352 * This function returns the text representation of the given error code.
1353 *
1354 * \sa irc_errno()
1355 * \ingroup errors
1356 */
1357const char * irc_strerror (int ircerrno);
1358
1359
1360/*!
1361 * \fn void irc_option_set (irc_session_t * session, unsigned int option)
1362 * \brief Sets the libircclient option.
1363 *
1364 * \param session An initiated session.
1365 * \param option  An option from libirc_options.h
1366 *
1367 * This function sets the libircclient option, changing libircclient behavior. See the
1368 * option list for the meaning for every option.
1369 *
1370 * \sa irc_option_reset
1371 * \ingroup options
1372 */
1373void irc_option_set (irc_session_t * session, unsigned int option);
1374
1375
1376/*!
1377 * \fn void irc_option_reset (irc_session_t * session, unsigned int option)
1378 * \brief Resets the libircclient option.
1379 *
1380 * \param session An initiated session.
1381 * \param option  An option from libirc_options.h
1382 *
1383 * This function removes the previously set libircclient option, changing libircclient 
1384 * behavior. See the option list for the meaning for every option.
1385 *
1386 * \sa irc_option_set
1387 * \ingroup options
1388 */
1389void irc_option_reset (irc_session_t * session, unsigned int option);
1390
1391
1392/*!
1393 * \fn char * irc_color_strip_from_mirc (const char * message)
1394 * \brief Removes all the color codes and format options.
1395 *
1396 * \param message A message from IRC
1397 *
1398 * \return Returns a new plain text message with stripped mIRC color codes.
1399 * Note that the memory for the new message is allocated using malloc(), so
1400 * you should free it using free() when it is not used anymore. If memory 
1401 * allocation failed, returns 0.
1402 *
1403 * \sa irc_color_convert_from_mirc irc_color_convert_to_mirc
1404 * \ingroup colors
1405 */
1406char * irc_color_strip_from_mirc (const char * message);
1407
1408
1409/*!
1410 * \fn char * irc_color_convert_from_mirc (const char * message)
1411 * \brief Converts all the color codes and format options to libircclient colors.
1412 *
1413 * \param message A message from IRC
1414 *
1415 * \return Returns a new message with converted mIRC color codes and format
1416 * options. See the irc_color_convert_to_mirc() help to see how the colors 
1417 * are converted.\n
1418 * Note that the memory for the new message is allocated using malloc(), so
1419 * you should free it using free() when it is not used anymore. If memory 
1420 * allocation failed, returns 0.
1421 *
1422 * \sa irc_color_strip_from_mirc irc_color_convert_to_mirc
1423 * \ingroup colors
1424 */
1425char * irc_color_convert_from_mirc (const char * message);
1426
1427
1428/*!
1429 * \fn char * irc_color_convert_to_mirc (const char * message)
1430 * \brief Converts all the color codes from libircclient format to mIRC.
1431 *
1432 * \param message A message with color codes
1433 *
1434 * \return Returns a new message with converted color codes and format
1435 * options, or 0 if memory could not be allocated. Note that the memory for 
1436 * the new message is allocated using malloc(), so you should free it using 
1437 * free() when it is not used anymore.
1438 *
1439 * The color system of libircclient is designed to be easy to use, and 
1440 * portable between different IRC clients. Every color or format option is 
1441 * described using plain text commands written between square brackets. The 
1442 * possible codes are:
1443 * - [B] ... [/B] - bold format mode. Everything between [B] and [/B] is written in \b bold.
1444 * - [I] ... [/I] - italic/reverse format mode. Everything between [I] and [/I] is written in \c italic, or reversed (however, because some clients are incapable of rendering italic text, most clients display this as normal text with the background and foreground colors swapped).
1445 * - [U] ... [/U] - underline format mode. Everything between [U] and [/U] is written underlined.
1446 * - [COLOR=RED] ... [/COLOR] - write the text using specified foreground color. The color is set by using the \c COLOR keyword, and equal sign followed by text color code (see below).
1447 * - [COLOR=RED/BLUE] ... [/COLOR] - write the text using specified foreground and background color. The color is set by using the \c COLOR keyword, an equal sign followed by text foreground color code, a dash and a text background color code.
1448 * 
1449 * The supported text colors are:
1450 * - WHITE
1451 * - BLACK
1452 * - DARKBLUE
1453 * - DARKGREEN
1454 * - RED
1455 * - BROWN
1456 * - PURPLE
1457 * - OLIVE
1458 * - YELLOW
1459 * - GREEN
1460 * - TEAL
1461 * - CYAN
1462 * - BLUE
1463 * - MAGENTA
1464 * - DARKGRAY
1465 * - LIGHTGRAY
1466 * 
1467 * Examples of color sequences:
1468 * \code
1469 * Hello, [B]Tim[/B]. 
1470 * [U]Arsenal[/U] got a [COLOR=RED]red card[/COLOR]
1471 * The tree[U]s[/U] are [COLOR=GREEN/BLACK]green[/COLOR]
1472 * \endcode
1473 *
1474 * \sa irc_color_strip_from_mirc irc_color_convert_from_mirc
1475 * \ingroup colors
1476 */
1477char * irc_color_convert_to_mirc (const char * message);
1478
1479#ifdef	__cplusplus
1480}
1481#endif
1482
1483#endif /* INCLUDE_LIBIRC_H */